content-query 0.3.0 → 0.4.0

package/dist/{content-lwPxE9Yu.d.mts → content-CwTKqRs9.d.mts}

@@ -1,6 +1,7 @@
 import { n as ContentRenderResult } from "./types-Dh-Sydyw.mjs";
-import { c as Relationship, i as CollectionRegistry, l as RelationshipsOf, s as QueryData } from "./types-BC8gVJ6u.mjs";
-import { _ as QueryPlan, n as RelationalQueries, t as RelationalCountOptions, u as Query, v as QueryRegistry } from "./relational-types-B45zM34W.mjs";
+import { _ as RelationshipsOf, g as Relationship, h as QueryData, i as CollectionRegistry } from "./types-DbFfF6JE.mjs";
+import { b as QueryRegistry, n as RelationalQueries, t as RelationalCountOptions, u as Query, y as QueryPlan } from "./relational-types-C8xJtLG5.mjs";
+import { i as QueryStyleMember, n as QueryStyle, r as QueryStyleDisabled, t as MembersOf } from "./query-style-eXENQJ0O.mjs";
 //#region src/shared/errors.d.ts
 type ContentErrorCode = "variant-not-found" | "not-renderable" | "source-error" | "validation-error" | "duplicate-id" | "invalid-reference" | "invalid-query" | "artifact-error" | "render-error";
 type ContentDiagnostic = {
@@ -11,6 +12,10 @@ type ContentDiagnostic = {
   id?: string;
   source?: string;
   path?: readonly PropertyKey[];
+  /** The custom payload being resolved or loaded. */
+  payload?: string;
+  /** The payload's variant combination, with keys in sorted order. */
+  variant?: Readonly<Record<string, string>>;
   issues?: readonly unknown[];
   cause?: unknown;
 };
@@ -24,6 +29,8 @@ declare class ContentError extends Error {
   readonly id?: string;
   readonly source?: string;
   readonly path?: readonly PropertyKey[];
+  readonly payload?: string;
+  readonly variant?: Readonly<Record<string, string>>;
   readonly issues?: readonly unknown[];
   readonly diagnostics: readonly ContentDiagnostic[];
   /** Creates one failure or a grouped report preserving individual causes and issues. */
@@ -41,17 +48,12 @@ type CheckRelation<Registry extends CollectionRegistry, Name extends keyof Regis
 /** 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];
 //#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>;
-};
-//#endregion
 //#region src/runtime/revision.d.ts
 type QueryRecord = Record<string, unknown> & {
   id: string;
 };
+/** Custom payload loaders by payload name, entry ID, and canonical variant key. */
+type CustomPayloadTable = ReadonlyMap<string, ReadonlyMap<string, ReadonlyMap<string, () => Promise<unknown>>>>;
 /** The built-in side payload shared by an entry's `_body` and `_rendered` payloads. */
 type BuiltinPayload = {
   body?: string;
@@ -63,6 +65,11 @@ type PreparedCollection = {
   relationships: Record<string, Relationship>;
   /** Lazy built-in payloads, present only for entries with a body or rendered output. */
   builtins: ReadonlyMap<string, () => Promise<BuiltinPayload>>;
+  /**
+   * Lazy custom payloads by payload name, entry ID, and canonical variant key. A missing variant
+   * key means the entry has no such combination.
+   */
+  payloads?: CustomPayloadTable;
   sources?: ReadonlyMap<string, string | undefined>;
 };
 type PreparedRevision = {
@@ -70,9 +77,12 @@ type PreparedRevision = {
   collections: Record<string, PreparedCollection>;
   relations: Map<string, Map<string, readonly QueryRecord[]>>;
   active: number;
-  payloadCache: Map<string, Promise<BuiltinPayload>>;
+  /** Built-in payloads keyed by collection and ID; custom payloads also by name and variant. */
+  payloadCache: Map<string, Promise<unknown>>;
   renderCache: Map<string, Promise<ContentRenderResult>>;
   renderMarkdown?: (body: string) => Promise<ContentRenderResult>;
+  /** The only query style this revision's configuration allows; absent allows both. */
+  queryStyle?: QueryStyle;
   execute?: (plan: QueryPlan, terminal: "all" | "first" | "count", requests: PayloadRequest[]) => Promise<unknown>;
 };
 /** A projected row awaiting the payloads its query scope requested. */
@@ -90,19 +100,34 @@ 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>;
+  /**
+   * Starts a fluent query over one collection. Nothing is selected until `select()`, `with()`,
+   * `withPayload()`, or `selectAdjacent()` requests data, not even `id`.
+   */
+  from<Name extends keyof Registry & string>(collection: Name): Query<Registry, Name>;
   /** 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> : {
+/**
+ * Root members outside the allowed style. Property access reports the message type directly; a
+ * call reports it as the required `this` type, whatever arguments it passes.
+ */
+type DisabledMembers<Style extends QueryStyle> = { readonly [Member in Exclude<QueryStyleMember, MembersOf<Style>>]: ContentMethods[Member] extends ((...arguments_: never) => unknown) ? (this: QueryStyleDisabled<Member, Style>, ...arguments_: readonly unknown[]) => never : QueryStyleDisabled<Member, Style>; };
+/**
+ * The generated `content` export. `Style` narrows the root query APIs to the `queryStyle` exported
+ * by content-query.config; the default allows both fluent and relational queries.
+ *
+ * The gate avoids a conditional on `Style`: a conditional on a generic `Style` would make
+ * `ContentSession<Registry>` invariant in `Registry` and break assignment to wider sessions.
+ */
+type Content<Registry extends CollectionRegistry = {}, Style extends QueryStyle = QueryStyle> = InvalidRelationships<Registry> extends never ? Pick<ContentMethods<Registry>, MembersOf<Style>> & DisabledMembers<Style> : {
   readonly invalidRelationships: InvalidRelationships<Registry>;
 };
 /** Keeps dev builders live across host-delivered revisions while pinning active operations. */
 declare function createLiveRuntime(initial: ContentState): {
-  content: ContentMethods<CollectionRegistry>;
+  content: Pick<ContentMethods<CollectionRegistry>, "from" | "query" | "count"> & DisabledMembers<QueryStyle>;
   update(next: ContentState): void;
 };
 //#endregion

package/dist/{types-FmUJ3cH1.d.mts → descriptor-bcPa6XLk.d.mts}

@@ -149,4 +149,20 @@ type LoaderSource<Value> = Value extends {
   readonly [loaderSourceType]?: infer Source;
 } ? Source : unknown;
 //#endregion
-export { FileSource as a, LoaderContext as c, LoaderWatcher as d, MetaStore as f, FileEntrySource as i, LoaderLogger as l, MaybePromise as m, DataEntry as n, Loader as o, RecordLoader as p, DataStore as r, LoaderConfig as s, BodyLoader as t, LoaderSource as u };
+//#region src/loaders/descriptor.d.ts
+type GlobOptions = {
+  pattern: string | string[];
+  base?: string | URL;
+  generateId?: (context: {
+    entry: string;
+    base: URL;
+    data: Record<string, unknown>;
+  }) => string;
+  retainBody?: boolean;
+  deferRender?: boolean;
+};
+type FileOptions = {
+  parser?: (text: string) => MaybePromise<unknown>;
+};
+//#endregion
+export { DataStore as a, Loader as c, LoaderLogger as d, LoaderSource as f, MaybePromise as g, RecordLoader as h, DataEntry as i, LoaderConfig as l, MetaStore as m, GlobOptions as n, FileEntrySource as o, LoaderWatcher as p, BodyLoader as r, FileSource as s, FileOptions as t, LoaderContext as u };

package/dist/{diagnostics-Cu94mZhl.mjs → diagnostics-DmUZtrJ6.mjs}

@@ -1,4 +1,4 @@
-import { t as ContentError } from "./errors-C2iuBM0G.mjs";
+import { t as ContentError } from "./errors-Bfd0R4_P.mjs";
 import { o as encode, r as decode } from "./values-BbTV4QT-.mjs";
 //#region src/runtime/diagnostics.ts
 /** Transports Error nodes as records while preserving the supported diagnostic value graph. */
@@ -59,6 +59,8 @@ function serializeContentError(error) {
 		id: error.id,
 		source: error.source,
 		path: error.path,
+		payload: error.payload,
+		variant: error.variant,
 		issues: error.issues,
 		cause: error.cause,
 		diagnostics: error.diagnostics

package/dist/{errors-C2iuBM0G.mjs → errors-Bfd0R4_P.mjs}

@@ -12,6 +12,8 @@ var ContentError = class extends Error {
 	id;
 	source;
 	path;
+	payload;
+	variant;
 	issues;
 	diagnostics;
 	/** Creates one failure or a grouped report preserving individual causes and issues. */
@@ -25,10 +27,23 @@ var ContentError = class extends Error {
 		this.id = options.id;
 		this.source = options.source;
 		this.path = options.path;
+		this.payload = options.payload;
+		this.variant = options.variant;
 		this.issues = options.issues;
 		this.diagnostics = options.diagnostics ?? [{ ...options }];
 	}
 };
+/**
+* Formats a payload and its variant as a readable identity, such as `detail[locale=en-US]`.
+*
+* @param payload - The payload name.
+* @param variant - The variant combination; keys are listed in sorted order.
+* @returns The payload name, followed by its variant pairs when it has any.
+*/
+function payloadIdentity(payload, variant = {}) {
+	const pairs = Object.keys(variant).sort().map((key) => `${key}=${variant[key]}`);
+	return pairs.length ? `${payload}[${pairs.join(",")}]` : payload;
+}
 /** Rejects invalid query structure before any execution or payload access. */
 function invalidQuery(message) {
 	throw new ContentError({
@@ -69,4 +84,4 @@ function withContext(cause, context) {
 	})));
 }
 //#endregion
-export { invalidQuery as a, groupDiagnostics as i, contentError as n, withContext as o, describeCause as r, ContentError as t };
+export { invalidQuery as a, groupDiagnostics as i, contentError as n, payloadIdentity as o, describeCause as r, withContext as s, ContentError as t };

package/dist/file-DSOcdFj0.mjs

@@ -0,0 +1,81 @@
+import { a as recordData, f as builtinPath, i as parseData, o as populateStore, p as builtinSymbol, r as coerceIdentity } from "./glob-BXJuwy_p.mjs";
+import { i as groupDiagnostics, n as contentError, r as describeCause, t as ContentError } from "./errors-Bfd0R4_P.mjs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+//#region src/loaders/file.ts
+/** Declares a multi-entry data file with typed source paths and record keys, plus an optional parser. */
+function file(filename, options = {}) {
+	if (typeof filename !== "string" || !filename) throw new TypeError("file() requires a filename.");
+	const descriptor = {
+		kind: "file",
+		filename,
+		options
+	};
+	return {
+		[builtinSymbol]: descriptor,
+		name: "content-query/file",
+		async load(context) {
+			const entries = await loadFile(descriptor, fileURLToPath(context.config.root), context.signal ?? new AbortController().signal);
+			await populateStore(context, entries);
+		}
+	};
+}
+/** Captures a complete multi-entry data source without applying collection validation. */
+async function loadFile(descriptor, root, signal) {
+	const resolved = builtinPath(descriptor, root);
+	let parsed;
+	try {
+		const text = await readFile(resolved, {
+			encoding: "utf8",
+			signal
+		});
+		parsed = descriptor.options.parser ? await descriptor.options.parser(text) : parseData(text, resolved);
+	} catch (cause) {
+		signal.throwIfAborted();
+		throw contentError(cause, {
+			code: "source-error",
+			source: resolved,
+			message: `Could not load "${descriptor.filename}": ${describeCause(cause)}`,
+			cause
+		});
+	}
+	const array = Array.isArray(parsed);
+	if (!array && (!parsed || typeof parsed !== "object")) throw new ContentError({
+		code: "source-error",
+		source: resolved,
+		message: `"${descriptor.filename}" must parse to an array or keyed record.`
+	});
+	const diagnostics = [];
+	const entries = Object.entries(parsed).flatMap(([key, value]) => {
+		if (!array && key === "$schema" && typeof value === "string") return [];
+		const source = `${resolved}#${key}`;
+		try {
+			const data = recordData(value);
+			const identity = array ? data.id ?? data.slug : key;
+			if (identity == null || coerceIdentity(identity) === "") throw new Error("Array entries require a nonempty id or slug.");
+			const { id: _transportId, ...metadata } = data;
+			return [{
+				id: coerceIdentity(identity),
+				data: metadata,
+				source: array ? source : `${resolved}#${coerceIdentity(identity)}`,
+				sourceData: {
+					filePath: path.relative(root, resolved).split(path.sep).join("/"),
+					key
+				}
+			}];
+		} catch (cause) {
+			diagnostics.push({
+				code: "source-error",
+				source,
+				message: `Invalid entry "${key}" in "${descriptor.filename}": ${describeCause(cause)}`,
+				cause
+			});
+			return [];
+		}
+	});
+	if (diagnostics.length) throw groupDiagnostics(diagnostics);
+	return entries;
+}
+//#endregion
+export { loadFile as n, file as t };

package/dist/{glob-Bv0dpvCQ.mjs → glob-BXJuwy_p.mjs}

@@ -1,5 +1,5 @@
-import { n as normalizeSnapshot, o as builtinPath, s as builtinSymbol } from "./validation-D_XdE1pF.mjs";
-import { i as groupDiagnostics, n as contentError, r as describeCause, t as ContentError } from "./errors-C2iuBM0G.mjs";
+import { i as groupDiagnostics, n as contentError, r as describeCause, t as ContentError } from "./errors-Bfd0R4_P.mjs";
+import { i as detach } from "./values-BbTV4QT-.mjs";
 import { n as slug } from "./github-slugger-BMgR_Q0I.mjs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
@@ -8,6 +8,85 @@ import { glob } from "tinyglobby";
 import matter from "gray-matter";
 import { parse } from "yaml";
 import { parse as parse$1 } from "smol-toml";
+//#region src/loaders/descriptor.ts
+const builtinSymbol = Symbol.for("content-query.builtin-loader");
+/** Finds library-owned loader settings without depending on module instance identity. */
+function builtinLoader(loader) {
+	return loader[builtinSymbol];
+}
+/** Resolves a loader's watch root from the application root, including file URLs. */
+function builtinPath(descriptor, root) {
+	if (descriptor.kind === "file") return path.resolve(root, descriptor.filename);
+	return descriptor.options.base instanceof URL ? path.resolve(fileURLToPath(descriptor.options.base)) : path.resolve(root, descriptor.options.base ?? ".");
+}
+//#endregion
+//#region src/preparation/validation.ts
+/** Checks records independently from validation-provider schema introspection. */
+function isRecord(value) {
+	return !!value && typeof value === "object" && !Array.isArray(value) && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+}
+/** Validates one result, retaining structured provider issues and their original detail. */
+async function validate(schema, value, context) {
+	if (!schema) return value;
+	try {
+		const result = await schema["~standard"].validate(value);
+		if (result.issues) {
+			const firstPath = result.issues[0]?.path?.map((segment) => typeof segment === "object" ? segment.key : segment);
+			throw new ContentError({
+				...context,
+				code: "validation-error",
+				message: result.issues.map((issue) => issue.message).join("; "),
+				issues: result.issues,
+				path: [...context.path ?? [], ...firstPath ?? []]
+			});
+		}
+		return result.value;
+	} catch (cause) {
+		throw contentError(cause, {
+			...context,
+			code: "validation-error",
+			message: "Schema validation failed."
+		});
+	}
+}
+/** Checks loader transport structure and rejects duplicate snapshot/upsert identities. */
+function normalizeSnapshot(entries, collection) {
+	if (!Array.isArray(entries)) throw new ContentError({
+		code: "source-error",
+		collection,
+		message: "load() must return an array of structured entries."
+	});
+	const snapshot = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		if (!entry || typeof entry.id !== "string" || !entry.id || !isRecord(entry.data) || entry.body !== void 0 && typeof entry.body !== "string" || entry.source !== void 0 && typeof entry.source !== "string") throw new ContentError({
+			code: "source-error",
+			collection,
+			id: entry && typeof entry === "object" && typeof entry.id === "string" ? entry.id : void 0,
+			source: entry && typeof entry === "object" && typeof entry.source === "string" ? entry.source : void 0,
+			message: "Invalid structured loader entry."
+		});
+		if (snapshot.has(entry.id)) throw new ContentError({
+			code: "duplicate-id",
+			collection,
+			id: entry.id,
+			source: entry.source,
+			message: `Duplicate entry ID "${entry.id}".`
+		});
+		snapshot.set(entry.id, entry);
+	}
+	return snapshot;
+}
+/** Validates supplied rendering data and normalizes omitted headings. */
+function renderedPayload(entry) {
+	if (entry.rendered === void 0) return;
+	const rendered = entry.rendered;
+	if (!rendered || typeof rendered.html !== "string" || rendered.metadata !== void 0 && (!isRecord(rendered.metadata) || rendered.metadata.headings !== void 0 && (!Array.isArray(rendered.metadata.headings) || rendered.metadata.headings.some((heading) => !heading || !Number.isInteger(heading.depth) || heading.depth < 1 || heading.depth > 6 || typeof heading.slug !== "string" || typeof heading.text !== "string")))) throw new Error("Invalid supplied HTML/headings payload.");
+	return {
+		html: rendered.html,
+		headings: detach(rendered.metadata?.headings ?? [])
+	};
+}
+//#endregion
 //#region src/loaders/populate.ts
 /** Validates a complete built-in source before replacing its collection store. */
 async function populateStore(context, entries) {
@@ -67,15 +146,24 @@ function glob$1(options) {
 		}
 	};
 }
-/** Captures complete matching Markdown and data sources before deployment. */
-async function loadGlob(descriptor, root, signal) {
+/**
+* Captures complete matching Markdown and data sources before deployment.
+*
+* @param descriptor - The glob loader's options.
+* @param root - The project root that relative bases and source paths use.
+* @param signal - Cancels outstanding reads.
+* @param options - `warnEmpty: false` skips the warning when nothing matches, for callers where an
+* empty result is expected, such as resolvers' `files.glob()`.
+* @returns Loader entries in sorted path order.
+*/
+async function loadGlob(descriptor, root, signal, { warnEmpty = true } = {}) {
 	const resolved = builtinPath(descriptor, root);
 	const entries = await glob(descriptor.options.pattern, {
 		cwd: resolved,
 		onlyFiles: true,
 		dot: false
 	});
-	if (entries.length === 0) console.warn(`[content-query] No content matched ${JSON.stringify(descriptor.options.pattern)} in ${resolved}.`);
+	if (entries.length === 0 && warnEmpty) console.warn(`[content-query] No content matched ${JSON.stringify(descriptor.options.pattern)} in ${resolved}.`);
 	const base = pathToFileURL(`${resolved}${path.sep}`);
 	entries.sort();
 	const results = [];
@@ -156,4 +244,4 @@ async function loadEntry(descriptor, entry, filename, base, signal) {
 	};
 }
 //#endregion
-export { populateStore as a, recordData as i, coerceIdentity as n, parseData as r, glob$1 as t };
+export { recordData as a, normalizeSnapshot as c, builtinLoader as d, builtinPath as f, parseData as i, renderedPayload as l, loadGlob as n, populateStore as o, builtinSymbol as p, coerceIdentity as r, isRecord as s, glob$1 as t, validate as u };

package/dist/index.d.mts

@@ -1,7 +1,7 @@
-import { a as FileSource, c as LoaderContext, d as LoaderWatcher, f as MetaStore, i as FileEntrySource, l as LoaderLogger, m as MaybePromise, n as DataEntry, o as Loader, p as RecordLoader, r as DataStore, s as LoaderConfig, t as BodyLoader, u as LoaderSource } from "./types-FmUJ3cH1.mjs";
+import { a as DataStore, c as Loader, d as LoaderLogger, f as LoaderSource, g as MaybePromise, h as RecordLoader, i as DataEntry, l as LoaderConfig, m as MetaStore, n as GlobOptions, o as FileEntrySource, p as LoaderWatcher, r as BodyLoader, s as FileSource, u as LoaderContext } from "./descriptor-bcPa6XLk.mjs";
 import { n as ContentRenderResult, r as RenderedContent, t as ContentHeading } from "./types-Dh-Sydyw.mjs";
-import { a as ComputedContext, c as Relationship, d as SchemaOutput, i as CollectionRegistry, n as BuiltinPayloads, o as PayloadsOf, r as CollectionDefinition, s as QueryData, t as BuiltinPayloadMarker, u as Schema } from "./types-BC8gVJ6u.mjs";
-import { n as GlobOptions } from "./descriptor-BUPT2J7X.mjs";
+import { C as VariantValues, S as VariantOf, a as ComputedContext, b as VariantContext, c as EntryFiles, d as PayloadData, f as PayloadDeclaration, g as Relationship, h as QueryData, i as CollectionRegistry, l as FileEntry, m as PayloadsOf, n as BuiltinPayloads, o as CustomPayload, p as PayloadDefinition, r as CollectionDefinition, s as CustomPayloadMarker, t as BuiltinPayloadMarker, u as PayloadContext, v as Schema, x as VariantField, y as SchemaOutput } from "./types-DbFfF6JE.mjs";
+import { n as QueryStyle } from "./query-style-eXENQJ0O.mjs";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/collection/source.d.ts
 type CollectionSource = string | ({
@@ -15,7 +15,35 @@ type CollectionSource = string | ({
 type RecordSource = Extract<CollectionSource, object> & {
   type: "json" | "yaml" | "toml";
 };
-type CollectionFields<SourceSchema extends Schema | undefined, ComputedSchemas extends Record<string, Schema>, Relationships extends Record<string, Relationship>, Source> = {
+/** Variant values are typed `string`, so inference never depends on declaration order. */
+type VariantRecord<Keys> = { [Key in keyof Keys]: string; };
+/** Metadata plus computed fields, as payload enumerators and resolvers receive them. */
+type PayloadData$1<SourceSchema extends Schema | undefined, ComputedSchemas extends Record<string, Schema>> = SchemaOutput<NoInfer<SourceSchema>> & { [Field in keyof NoInfer<ComputedSchemas>]: SchemaOutput<NoInfer<ComputedSchemas>[Field]>; };
+/**
+ * Custom payload declarations. Schemas and variant keys are inferred through separate mapped
+ * types, so resolvers are contextually typed without annotations. Variant values are data field
+ * names or fixed lists rather than callbacks: TypeScript cannot infer keys from an object whose
+ * values are all unannotated callbacks.
+ */
+type PayloadDeclarations<SourceSchema extends Schema | undefined, ComputedSchemas extends Record<string, Schema>, PayloadSchemas extends Record<string, Schema>, PayloadVariants extends Record<string, unknown>, Source> = { [Name in keyof PayloadSchemas]: {
+  schema: PayloadSchemas[Name];
+}; } & { [Name in keyof PayloadVariants]: {
+  variants?: { [Key in keyof PayloadVariants[Name]]: VariantValues<PayloadData$1<SourceSchema, ComputedSchemas>>; };
+  combinations?(context: VariantContext<PayloadData$1<SourceSchema, ComputedSchemas>, Source> & {
+    variants: Readonly<{ [Key in keyof NoInfer<PayloadVariants>[Name]]: readonly string[]; }>;
+  }): Iterable<VariantRecord<NoInfer<PayloadVariants>[Name]>> | PromiseLike<Iterable<VariantRecord<NoInfer<PayloadVariants>[Name]>>>;
+  resolve(context: PayloadContext<PayloadData$1<SourceSchema, ComputedSchemas>, Source, VariantRecord<NoInfer<PayloadVariants>[Name]>>): unknown;
+  /** Set to `false` to resolve again in every revision. */
+  cache?: boolean;
+}; } & ReservedPayloadNames<NoInfer<PayloadSchemas>>;
+/**
+ * Rejects underscore payload names, which built-ins own. A conditional keeps declaration inference
+ * intact, unlike a key-remapped mapped type.
+ */
+type ReservedPayloadNames<PayloadSchemas> = Extract<keyof PayloadSchemas, `_${string}`> extends never ? unknown : {
+  "Custom payload names cannot start with an underscore": Extract<keyof PayloadSchemas, `_${string}`>;
+};
+type CollectionFields<SourceSchema extends Schema | undefined, ComputedSchemas extends Record<string, Schema>, Relationships extends Record<string, Relationship>, PayloadSchemas extends Record<string, Schema>, PayloadVariants extends Record<string, unknown>, Source> = {
   schema?: SourceSchema;
   computed?: { [Name in keyof ComputedSchemas]: {
     schema: ComputedSchemas[Name];
@@ -26,16 +54,22 @@ type CollectionFields<SourceSchema extends Schema | undefined, ComputedSchemas e
       id: string;
     } & { [Field in keyof ComputedSchemas]: SchemaOutput<ComputedSchemas[Field]>; }) & string;
   }; };
+  /** Directories, relative to the project root, that resolvers' `files` helpers may also read. */
+  sharedFiles?: readonly string[];
+  /** Named per-entry data resolved during preparation and loaded only when a query requests it. */
+  payloads?: PayloadDeclarations<SourceSchema, ComputedSchemas, PayloadSchemas, PayloadVariants, Source>;
 };
-type Definition<SourceSchema extends Schema | undefined, ComputedSchemas extends Record<string, Schema>, Relationships extends Record<string, Relationship>, ContentLoader extends Loader> = ({
+type Definition<SourceSchema extends Schema | undefined, ComputedSchemas extends Record<string, Schema>, Relationships extends Record<string, Relationship>, PayloadSchemas extends Record<string, Schema>, PayloadVariants extends Record<string, unknown>, ContentLoader extends Loader> = ({
   source: CollectionSource;
   loader?: never;
-} & CollectionFields<SourceSchema, ComputedSchemas, Relationships, FileSource>) | ({
+} & CollectionFields<SourceSchema, ComputedSchemas, Relationships, PayloadSchemas, PayloadVariants, FileSource>) | ({
   loader: ContentLoader;
   source?: never;
-} & CollectionFields<SourceSchema, ComputedSchemas, Relationships, LoaderSource<NoInfer<ContentLoader>>>);
+} & CollectionFields<SourceSchema, ComputedSchemas, Relationships, PayloadSchemas, PayloadVariants, LoaderSource<NoInfer<ContentLoader>>>);
+/** Records each declared payload's validated value type and variant record. */
+type PayloadMarker<PayloadSchemas extends Record<string, Schema>, PayloadVariants extends Record<string, unknown>> = CustomPayloadMarker<{ [Name in keyof PayloadSchemas & string]: CustomPayload<SchemaOutput<PayloadSchemas[Name]>, VariantRecord<PayloadVariants[Name & keyof PayloadVariants]>>; }>;
 /** Normalizes either declaration form into a definition with a native loader. */
-declare function collectionOf<SourceSchema extends StandardSchemaV1<unknown, Record<string, unknown>> | undefined, ComputedSchemas extends Record<string, Schema>, Relationships extends Record<string, Relationship>, ContentLoader extends Loader>(definition: Definition<SourceSchema, ComputedSchemas, Relationships, ContentLoader>): {
+declare function collectionOf<SourceSchema extends StandardSchemaV1<unknown, Record<string, unknown>> | undefined, ComputedSchemas extends Record<string, Schema>, Relationships extends Record<string, Relationship>, PayloadSchemas extends Record<string, Schema>, PayloadVariants extends Record<string, unknown>, ContentLoader extends Loader>(definition: Definition<SourceSchema, ComputedSchemas, Relationships, PayloadSchemas, PayloadVariants, ContentLoader>): {
   loader: ContentLoader | Loader<FileSource>;
   schema: SourceSchema;
   computed: { [Name in keyof ComputedSchemas]: {
@@ -47,6 +81,10 @@ declare function collectionOf<SourceSchema extends StandardSchemaV1<unknown, Rec
   }; };
   relationships: Relationships;
   source: CollectionSource;
+  /** Directories, relative to the project root, that resolvers' `files` helpers may also read. */
+  sharedFiles?: readonly string[];
+  /** Named per-entry data resolved during preparation and loaded only when a query requests it. */
+  payloads?: PayloadDeclarations<SourceSchema, ComputedSchemas, PayloadSchemas, PayloadVariants, FileSource> | undefined;
 } | {
   loader: ContentLoader | Loader<FileSource>;
   schema: SourceSchema;
@@ -59,21 +97,26 @@ declare function collectionOf<SourceSchema extends StandardSchemaV1<unknown, Rec
   }; };
   relationships: Relationships;
   source?: never;
+  /** Directories, relative to the project root, that resolvers' `files` helpers may also read. */
+  sharedFiles?: readonly string[];
+  /** Named per-entry data resolved during preparation and loaded only when a query requests it. */
+  payloads?: PayloadDeclarations<SourceSchema, ComputedSchemas, PayloadSchemas, PayloadVariants, LoaderSource<NoInfer<ContentLoader>>> | undefined;
 };
-type Defined<SourceSchema extends StandardSchemaV1<unknown, Record<string, unknown>> | undefined, ComputedSchemas extends Record<string, Schema>, Relationships extends Record<string, Relationship>, ContentLoader extends Loader> = ReturnType<typeof collectionOf<SourceSchema, ComputedSchemas, Relationships, ContentLoader>>;
+type Defined<SourceSchema extends StandardSchemaV1<unknown, Record<string, unknown>> | undefined, ComputedSchemas extends Record<string, Schema>, Relationships extends Record<string, Relationship>, PayloadSchemas extends Record<string, Schema>, PayloadVariants extends Record<string, unknown>, ContentLoader extends Loader> = ReturnType<typeof collectionOf<SourceSchema, ComputedSchemas, Relationships, PayloadSchemas, PayloadVariants, ContentLoader>> & PayloadMarker<PayloadSchemas, PayloadVariants>;
 /**
- * Declares fields with inferred schema data and optional loader source metadata, plus relationships.
- * JSON, YAML, and TOML sources carry no built-in `_body` or `_rendered` payloads.
+ * Declares fields with inferred schema data and optional loader source metadata, plus
+ * relationships and custom payloads. JSON, YAML, and TOML sources carry no built-in `_body` or
+ * `_rendered` payloads.
  */
-export declare function defineCollection<const SourceSchema extends StandardSchemaV1<unknown, Record<string, unknown>> | undefined = undefined, const ComputedSchemas extends Record<string, Schema> = {}, const Relationships extends Record<string, Relationship> = {}>(definition: {
+export declare function defineCollection<const SourceSchema extends StandardSchemaV1<unknown, Record<string, unknown>> | undefined = undefined, const ComputedSchemas extends Record<string, Schema> = {}, const Relationships extends Record<string, Relationship> = {}, const PayloadSchemas extends Record<string, Schema> = {}, const PayloadVariants extends Record<string, unknown> = {}>(definition: {
   source: RecordSource;
   loader?: never;
-} & CollectionFields<SourceSchema, ComputedSchemas, Relationships, FileSource>): Defined<SourceSchema, ComputedSchemas, Relationships, Loader> & BuiltinPayloadMarker<never>;
+} & CollectionFields<SourceSchema, ComputedSchemas, Relationships, PayloadSchemas, PayloadVariants, FileSource>): Defined<SourceSchema, ComputedSchemas, Relationships, PayloadSchemas, PayloadVariants, Loader> & BuiltinPayloadMarker<never>;
 /**
- * Declares fields with inferred schema data and optional loader source metadata, plus relationships.
- * Record loaders such as `file()` carry no built-in `_body` or `_rendered` payloads, and body
- * loaders carry `_body` without `_rendered`.
+ * Declares fields with inferred schema data and optional loader source metadata, plus
+ * relationships and custom payloads. Record loaders such as `file()` carry no built-in `_body` or
+ * `_rendered` payloads, and body loaders carry `_body` without `_rendered`.
  */
-export declare function defineCollection<const SourceSchema extends StandardSchemaV1<unknown, Record<string, unknown>> | undefined = undefined, const ComputedSchemas extends Record<string, Schema> = {}, const Relationships extends Record<string, Relationship> = {}, const ContentLoader extends Loader = Loader>(definition: Definition<SourceSchema, ComputedSchemas, Relationships, ContentLoader>): Defined<SourceSchema, ComputedSchemas, Relationships, ContentLoader> & BuiltinPayloadMarker<[ContentLoader] extends [RecordLoader] ? never : [ContentLoader] extends [BodyLoader] ? "_body" : keyof BuiltinPayloads>;
+export declare function defineCollection<const SourceSchema extends StandardSchemaV1<unknown, Record<string, unknown>> | undefined = undefined, const ComputedSchemas extends Record<string, Schema> = {}, const Relationships extends Record<string, Relationship> = {}, const PayloadSchemas extends Record<string, Schema> = {}, const PayloadVariants extends Record<string, unknown> = {}, const ContentLoader extends Loader = Loader>(definition: Definition<SourceSchema, ComputedSchemas, Relationships, PayloadSchemas, PayloadVariants, ContentLoader>): Defined<SourceSchema, ComputedSchemas, Relationships, PayloadSchemas, PayloadVariants, ContentLoader> & BuiltinPayloadMarker<[ContentLoader] extends [RecordLoader] ? never : [ContentLoader] extends [BodyLoader] ? "_body" : keyof BuiltinPayloads>;
 //#endregion
-export type { BodyLoader, BuiltinPayloads, CollectionDefinition, CollectionRegistry, CollectionSource, ComputedContext, ContentHeading, ContentRenderResult, DataEntry, DataStore, FileEntrySource, FileSource, Loader, LoaderConfig, LoaderContext, LoaderLogger, LoaderSource, LoaderWatcher, MaybePromise, MetaStore, PayloadsOf, QueryData, RecordLoader, Relationship, RenderedContent };
+export type { BodyLoader, BuiltinPayloads, CollectionDefinition, CollectionRegistry, CollectionSource, ComputedContext, ContentHeading, ContentRenderResult, DataEntry, DataStore, EntryFiles, FileEntry, FileEntrySource, FileSource, Loader, LoaderConfig, LoaderContext, LoaderLogger, LoaderSource, LoaderWatcher, MaybePromise, MetaStore, PayloadContext, PayloadData, PayloadDeclaration, PayloadDefinition, PayloadsOf, QueryData, QueryStyle, RecordLoader, Relationship, RenderedContent, VariantContext, VariantField, VariantOf, VariantValues };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { t as glob } from "./glob-Bv0dpvCQ.mjs";
+import { t as glob } from "./glob-BXJuwy_p.mjs";
 import { t as assertServerOnly } from "./server-only-CIJUlyL-.mjs";
 //#region src/collection/source.ts
 const patterns = {

package/dist/internal.d.mts

@@ -1,12 +1,15 @@
-import { n as createLiveRuntime, o as ContentError, r as PreparedRevision, t as Content } from "./content-lwPxE9Yu.mjs";
+import { n as createLiveRuntime, o as ContentError, r as PreparedRevision, t as Content } from "./content-CwTKqRs9.mjs";
 import { n as ContentRenderResult } from "./types-Dh-Sydyw.mjs";
-import { i as CollectionRegistry } from "./types-BC8gVJ6u.mjs";
-import { v as QueryRegistry } from "./relational-types-B45zM34W.mjs";
+import { i as CollectionRegistry } from "./types-DbFfF6JE.mjs";
+import { b as QueryRegistry } from "./relational-types-C8xJtLG5.mjs";
+import { n as QueryStyle } from "./query-style-eXENQJ0O.mjs";
 //#region src/artifacts/types.d.ts
 type ArtifactManifest = {
   version: number;
   codec: string;
   collections: QueryRegistry;
+  /** Optional and additive, so it needs no version bump; absent allows both query styles. */
+  queryStyle?: QueryStyle;
 };
 type EncodedCollection = {
   records: readonly string[];
@@ -14,13 +17,17 @@ type EncodedCollection = {
   builtins: Record<string, () => Promise<{
     default: string;
   }>>;
+  /** Lazy encoded custom payloads by payload name, entry ID, and canonical variant key. */
+  payloads?: Record<string, Record<string, Record<string, () => Promise<{
+    default: string;
+  }>>>>;
 };
 //#endregion
 //#region src/artifacts/runtime.d.ts
 /** Initializes generated/embedded prepared content. This versioned wiring is internal. */
 export declare function createArtifactRevision(manifest: ArtifactManifest, collections: Record<string, EncodedCollection>, renderMarkdown?: (body: string) => Promise<ContentRenderResult>): PreparedRevision;
 /** Initializes the public generated server export from a complete immutable artifact revision. */
-export declare function createArtifactRuntime<Registry extends CollectionRegistry>(manifest: ArtifactManifest, collections: Record<string, EncodedCollection>, renderMarkdown?: (body: string) => Promise<ContentRenderResult>): Content<Registry>;
+export declare function createArtifactRuntime<Registry extends CollectionRegistry>(manifest: ArtifactManifest, collections: Record<string, EncodedCollection>, renderMarkdown?: (body: string) => Promise<ContentRenderResult>): Content<Registry, QueryStyle>;
 //#endregion
 //#region src/artifacts/payloads.d.ts
 /**

package/dist/internal.mjs

@@ -1,13 +1,35 @@
-import { t as ContentError } from "./errors-C2iuBM0G.mjs";
+import { t as ContentError } from "./errors-Bfd0R4_P.mjs";
 import { r as decode } from "./values-BbTV4QT-.mjs";
-import { i as prepareRelationships, n as createRuntime, t as createLiveRuntime } from "./content-N1gYshjg.mjs";
-import { t as restoreContentError } from "./diagnostics-Cu94mZhl.mjs";
+import { n as createRuntime, o as prepareRelationships, r as isQueryStyle, t as createLiveRuntime } from "./content-BXrgP7nL.mjs";
+import { t as restoreContentError } from "./diagnostics-DmUZtrJ6.mjs";
 import { gunzipSync } from "fflate/browser";
 //#region src/artifacts/runtime.ts
+/** Checks that a value is a plain record before reading generated payload tables from it. */
+function isTable(value) {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+/**
+* Restores lazy custom payload loaders from a generated payload table.
+*
+* @param collection - The collection name, for error messages.
+* @param payloads - Encoded loaders by payload name, entry ID, and canonical variant key.
+* @returns Decoding loaders with the same keys.
+*/
+function customPayloadTable(collection, payloads) {
+	if (!isTable(payloads)) throw new Error(`Invalid payload table for collection "${collection}".`);
+	return new Map(Object.entries(payloads).map(([payload, entries]) => {
+		if (!isTable(entries)) throw new Error(`Invalid payload table for collection "${collection}".`);
+		return [payload, new Map(Object.entries(entries).map(([id, variants]) => {
+			if (!isTable(variants) || Object.values(variants).some((load) => typeof load !== "function")) throw new Error(`Invalid payload table for collection "${collection}".`);
+			return [id, new Map(Object.entries(variants).map(([variant, load]) => [variant, async () => decode((await load()).default)]))];
+		}))];
+	}));
+}
 /** Initializes generated/embedded prepared content. This versioned wiring is internal. */
 function createArtifactRevision(manifest, collections, renderMarkdown) {
 	try {
 		if (manifest.version !== 2 || manifest.codec !== "devalue-6.0.2") throw new Error("Incompatible content artifact or codec version; regenerate content.");
+		if (manifest.queryStyle !== void 0 && !isQueryStyle(manifest.queryStyle)) throw new Error("Invalid query style in content artifact; regenerate content.");
 		const revision = {
 			registry: manifest.collections,
 			collections: Object.create(null),
@@ -15,7 +37,8 @@ function createArtifactRevision(manifest, collections, renderMarkdown) {
 			active: 0,
 			payloadCache: /* @__PURE__ */ new Map(),
 			renderCache: /* @__PURE__ */ new Map(),
-			renderMarkdown
+			renderMarkdown,
+			...manifest.queryStyle ? { queryStyle: manifest.queryStyle } : {}
 		};
 		for (const [name, descriptor] of Object.entries(manifest.collections)) {
 			const encoded = collections[name];
@@ -25,7 +48,8 @@ function createArtifactRevision(manifest, collections, renderMarkdown) {
 			revision.collections[name] = {
 				records,
 				relationships: descriptor.relationships,
-				builtins: new Map(Object.entries(encoded.builtins ?? {}).map(([id, load]) => [id, async () => decode((await load()).default)]))
+				builtins: new Map(Object.entries(encoded.builtins ?? {}).map(([id, load]) => [id, async () => decode((await load()).default)])),
+				...encoded.payloads ? { payloads: customPayloadTable(name, encoded.payloads) } : {}
 			};
 		}
 		const errors = prepareRelationships(revision);