@shop-on/theme-loader 0.5.0 → 0.6.0

package/dist/closest-sources.d.ts

@@ -0,0 +1,61 @@
+import { SectionInstance, ThemeLoaderConfig } from "./types.js";
+import { DynamicSourceRoute } from "./dynamic-sources.js";
+import { ClosestLookup, ClosestOverlays, ClosestResource } from "@shop-on/theme-contract";
+//#region src/closest-sources.d.ts
+/** What a provider's scope binds, per picker field: the product metafields
+ * (`ns.key`) its cards must carry (a fetch arg), and whether the collection
+ * description is read (a separate lean query, not a fetch arg). */
+export interface ClosestNeeds {
+  metafieldKeys?: string[];
+  includeDescription?: boolean;
+}
+export interface ClosestNeedsMap {
+  /** Provider node → picker field id → needs. The spec context merges these
+   * into the field's fetch arg. */
+  providers: WeakMap<object, Record<string, ClosestNeeds>>;
+  /** Needs of the nodes the ROUTE resource serves (no provider above them). */
+  route: Partial<Record<ClosestResource, Pick<ClosestNeeds, "includeDescription">>>;
+}
+/** Per provider, what its scope binds — so the picker barrier fetches the
+ * bound metafield keys (and the collection description) for exactly the
+ * pickers whose items will be read, and nothing for the rest. */
+export declare function collectClosestNeeds(cfg: ThemeLoaderConfig, template: unknown, route: DynamicSourceRoute): Promise<ClosestNeedsMap>;
+/** The whole-value closest pass over every scope, and the lookup for the
+ * inline pass. Runs AFTER the picker barrier (the items are picker results)
+ * and before the inline pass. Exported so a route-fed list (v2) can resolve
+ * its own subtree the same way. */
+export declare function resolveClosestResources(cfg: ThemeLoaderConfig, template: unknown, route: DynamicSourceRoute & {
+  locale?: string;
+}, needs?: ClosestNeedsMap,
+/** The entries of each `$theme` list, by provider node. Only
+ * `resolveListOverlays` passes it; in the page's own enrichment a fed
+ * list has no items yet, so its subtree's closest values blank. */
+fed?: WeakMap<object, unknown[]>): Promise<ClosestLookup>;
+export interface FedList {
+  /** The section's instance id in `template.sections`. A section-group
+   * section is never fed: groups render on pages that have no such list. */
+  sectionId: string;
+  /** Block ids from the section down to the provider; `[]` is the section. */
+  path: string[];
+  resource: ClosestResource;
+  /** The section as authored, cloned before enrichment touched it. */
+  section: SectionInstance;
+  /** The product metafields (`ns.key`) the per-item subtree binds — what each
+   * item's fetch must carry. */
+  metafieldKeys: string[];
+}
+/** Every `$theme` list on the template whose per-item subtree binds a closest
+ * source of its resource. Call it on the template as loaded, before
+ * enrichment. A list whose cards bind nothing is not returned, so a grid
+ * without closest sources costs its requests nothing. */
+export declare function collectFedLists(cfg: ThemeLoaderConfig, template: unknown): Promise<FedList[]>;
+/** The per-item values of one `$theme` list for a batch of its entries — the
+ * whole-value and inline passes run over a copy of the list's section alone,
+ * with the batch as the list's items. Only what the subtree binds is read, so
+ * an entry needs the `metafieldKeys` its list asked for. `route` resolves the
+ * route sources a per-item string mixes in; leave out what the request does
+ * not have and those tokens blank, as they would anywhere else. */
+export declare function resolveListOverlays(cfg: ThemeLoaderConfig, list: FedList, entries: readonly unknown[], route?: DynamicSourceRoute & {
+  locale?: string;
+}): Promise<ClosestOverlays>;
+//#endregion

package/dist/closest-sources.js

@@ -0,0 +1,287 @@
+import { loadBlockSchemas, loadSectionSchemas } from "./disk.js";
+import { collectionModule } from "./server-modules.js";
+import { applyInlineSourceTokens, loadMetaobjectFieldSources, loadSinkTypeAt, productAttributes } from "./dynamic-sources.js";
+import { CLOSEST_RESOURCES, THEME_FED, applyClosestBindings, closestResourceOf, closestScopeAt, nodeSourceDescriptors, providersOf, routeTwin } from "@shop-on/theme-contract";
+import { serializeRichText } from "@shop-on/theme-runtime/richtext";
+//#region src/closest-sources.ts
+const ROUTE = Symbol("closest/route");
+function schemaOf(map, type) {
+	if (!type) return void 0;
+	return map.get(type) ?? map.get(type.replace(/^_/, ""));
+}
+function* walkScoped(template, sectionSchemas, blockSchemas, root) {
+	const t = template;
+	const sectionMaps = [t.sections ?? {}];
+	for (const group of Object.values(t.section_groups ?? {})) sectionMaps.push(group.sections ?? {});
+	function* descend(node, key, providers, chain, nodes) {
+		if (node?.disabled) return;
+		const nextChain = [...chain, {
+			providers,
+			key
+		}];
+		const nextNodes = [...nodes, node];
+		yield {
+			node,
+			chain: nextChain,
+			nodes: nextNodes
+		};
+		for (const [blockId, block] of Object.entries(node.blocks ?? {})) {
+			const b = block;
+			yield* descend(b, blockId, providersOf(schemaOf(blockSchemas, b?.type)), nextChain, nextNodes);
+		}
+	}
+	for (const sections of sectionMaps) for (const [sectionId, section] of Object.entries(sections)) yield* descend(section, sectionId, providersOf(schemaOf(sectionSchemas, section?.type)), [root], [ROUTE]);
+}
+/** The route link: a single provider per resource the request carries. */
+function routeLink(route) {
+	const providers = {};
+	for (const resource of CLOSEST_RESOURCES) if (route[resource]) providers[resource] = { from: "$route" };
+	return {
+		providers,
+		key: ""
+	};
+}
+async function loadSchemas(cfg) {
+	const [sectionSchemas, blockSchemas] = await Promise.all([loadSectionSchemas(cfg.configDir), loadBlockSchemas(cfg.configDir)]);
+	return {
+		sectionSchemas,
+		blockSchemas
+	};
+}
+/** Per provider, what its scope binds — so the picker barrier fetches the
+* bound metafield keys (and the collection description) for exactly the
+* pickers whose items will be read, and nothing for the rest. */
+async function collectClosestNeeds(cfg, template, route) {
+	const { sectionSchemas, blockSchemas } = await loadSchemas(cfg);
+	const needs = {
+		providers: /* @__PURE__ */ new WeakMap(),
+		route: {}
+	};
+	const bindsDescription = (resource, twin) => resource === "collection" && twin?.source === "collection_attribute" && twin.attribute === "description";
+	const add = (slot, resource, twin) => {
+		if (!twin) return;
+		if (resource === "product" && twin.source === "product_metafield") {
+			const key = `${twin.namespace}.${twin.key}`;
+			if (!(slot.metafieldKeys ??= []).includes(key)) slot.metafieldKeys.push(key);
+		} else if (bindsDescription(resource, twin)) slot.includeDescription = true;
+	};
+	for (const { node, chain, nodes } of walkScoped(template, sectionSchemas, blockSchemas, routeLink(route))) for (const d of nodeSourceDescriptors(node)) {
+		const resource = closestResourceOf(d);
+		if (!resource) continue;
+		const scope = closestScopeAt(chain, resource);
+		if (!scope) continue;
+		if (scope.index === 0) {
+			if (bindsDescription(resource, routeTwin(d))) (needs.route[resource] ??= {}).includeDescription = true;
+			continue;
+		}
+		const provider = nodes[scope.index];
+		let byField = needs.providers.get(provider);
+		if (!byField) needs.providers.set(provider, byField = {});
+		add(byField[scope.decl.from] ??= {}, resource, routeTwin(d));
+	}
+	return needs;
+}
+function titled(data) {
+	const title = data?.title;
+	return typeof title === "string" ? { attributes: { title } } : null;
+}
+/** One picker result (or route resource) as the resolvers read it. */
+async function toItem(resource, data, description) {
+	if (!data || typeof data !== "object") return null;
+	if (resource === "product") {
+		const p = data;
+		if (typeof p.title !== "string" || !p.price) return null;
+		return {
+			attributes: productAttributes(p),
+			metafields: p.metafields ?? {}
+		};
+	}
+	const item = titled(data);
+	if (!item || resource !== "collection") return item;
+	const handle = data.handle;
+	const descriptionHtml = description && typeof handle === "string" ? await description(handle) : null;
+	return {
+		...item,
+		descriptionHtml
+	};
+}
+/** The items an `each` provider renders: the picker's `${from}Data`, read by
+* the picker's own setting type. A declaration the loader does not know how
+* to read (a type/resource pair not listed here) yields no items, so its
+* subtree keeps the literal. Keyed by handle — the id the theme's list wraps
+* each card's `ClosestScope` with. */
+async function itemsOf(resource, pickerType, data, description) {
+	let list;
+	if (pickerType === "collection" && resource === "product") list = data?.products;
+	else if (pickerType === "product_list" && resource === "product") list = data;
+	else if (pickerType === "collection_list" && resource === "collection") list = data;
+	else if (pickerType === "blog" && resource === "article") list = data?.articles;
+	return toItems(resource, list, description);
+}
+/** A list's entries as items, keyed by handle; an entry without one (or one
+* the resolvers cannot read) is dropped and its card keeps the literal. */
+async function toItems(resource, list, description) {
+	if (!Array.isArray(list)) return [];
+	return (await Promise.all(list.map(async (entry) => {
+		const handle = entry?.handle;
+		if (typeof handle !== "string" || !handle) return null;
+		const sources = await toItem(resource, entry, description);
+		return sources ? {
+			id: handle,
+			sources
+		} : null;
+	}))).filter((item) => item !== null);
+}
+function settingTypeOf(schema, id) {
+	return schema?.settings?.find((s) => s.id === id)?.type;
+}
+/** The whole-value closest pass over every scope, and the lookup for the
+* inline pass. Runs AFTER the picker barrier (the items are picker results)
+* and before the inline pass. Exported so a route-fed list (v2) can resolve
+* its own subtree the same way. */
+async function resolveClosestResources(cfg, template, route, needs = {
+	providers: /* @__PURE__ */ new WeakMap(),
+	route: {}
+}, fed) {
+	const [{ sectionSchemas, blockSchemas }, sinkTypeAt] = await Promise.all([loadSchemas(cfg), loadSinkTypeAt(cfg)]);
+	const opts = {
+		serializeRichText,
+		sinkTypeAt
+	};
+	const describe = async (handle) => (await collectionModule()).fetchCollectionDescriptionHtml(handle, route.locale);
+	const descriptionFor = (provider, from) => needs.providers.get(provider)?.[from]?.includeDescription ? describe : void 0;
+	const routeItems = {};
+	if (route.product) routeItems.product = await toItem("product", route.product) ?? void 0;
+	if (route.collection) routeItems.collection = {
+		attributes: { title: route.collection.title },
+		descriptionHtml: needs.route.collection?.includeDescription ? await route.collection.getDescriptionHtml() : null
+	};
+	for (const resource of [
+		"page",
+		"blog",
+		"article"
+	]) {
+		const r = route[resource];
+		if (r) routeItems[resource] = { attributes: { title: r.title } };
+	}
+	const single = /* @__PURE__ */ new WeakMap();
+	const each = /* @__PURE__ */ new WeakMap();
+	const singleItems = /* @__PURE__ */ new WeakMap();
+	const itemLists = /* @__PURE__ */ new WeakMap();
+	const singleItemOf = async (provider, resource, from) => {
+		let byResource = singleItems.get(provider);
+		if (!byResource) singleItems.set(provider, byResource = {});
+		if (!(resource in byResource)) byResource[resource] = await toItem(resource, provider.settings?.[`${from}Data`], descriptionFor(provider, from));
+		return byResource[resource] ?? null;
+	};
+	for (const { node, chain, nodes } of walkScoped(template, sectionSchemas, blockSchemas, routeLink(route))) for (const resource of CLOSEST_RESOURCES) {
+		const scope = closestScopeAt(chain, resource);
+		if (!scope) continue;
+		const providerNode = nodes[scope.index];
+		if (!scope.decl.each) {
+			const item = scope.index === 0 ? routeItems[resource] : await singleItemOf(providerNode, resource, scope.decl.from);
+			if (!item) continue;
+			applyClosestBindings(node, resource, item, opts);
+			let byResource = single.get(node);
+			if (!byResource) single.set(node, byResource = {});
+			byResource[resource] = item;
+			continue;
+		}
+		let lists = itemLists.get(providerNode);
+		if (!lists) itemLists.set(providerNode, lists = {});
+		let items = lists[resource];
+		if (!items) {
+			const schema = schemaOf(scope.index === 1 ? sectionSchemas : blockSchemas, providerNode.type);
+			items = lists[resource] = scope.decl.from === THEME_FED ? await toItems(resource, fed?.get(providerNode)) : await itemsOf(resource, settingTypeOf(schema, scope.decl.from), providerNode.settings?.[`${scope.decl.from}Data`], descriptionFor(providerNode, scope.decl.from));
+		}
+		each.set(node, {
+			resource,
+			items
+		});
+		const n = node;
+		for (const item of items) {
+			const into = {};
+			applyClosestBindings(node, resource, item.sources, opts, into);
+			if (Object.keys(into).length === 0) continue;
+			const overlay = n.closestSettings ??= {};
+			const prior = Object.hasOwn(overlay, item.id) ? overlay[item.id] : void 0;
+			overlay[item.id] = {
+				...prior,
+				...into
+			};
+		}
+	}
+	return {
+		singleAt: (node, resource) => single.get(node)?.[resource] ?? null,
+		eachAt: (node) => each.get(node) ?? null
+	};
+}
+/** Every `$theme` list on the template whose per-item subtree binds a closest
+* source of its resource. Call it on the template as loaded, before
+* enrichment. A list whose cards bind nothing is not returned, so a grid
+* without closest sources costs its requests nothing. */
+async function collectFedLists(cfg, template) {
+	const { sectionSchemas, blockSchemas } = await loadSchemas(cfg);
+	const body = template.sections ?? {};
+	const lists = /* @__PURE__ */ new Map();
+	const clones = /* @__PURE__ */ new Map();
+	for (const { node, chain, nodes } of walkScoped(template, sectionSchemas, blockSchemas, {
+		providers: {},
+		key: ""
+	})) for (const d of nodeSourceDescriptors(node)) {
+		const resource = closestResourceOf(d);
+		if (!resource) continue;
+		const scope = closestScopeAt(chain, resource);
+		if (!scope || scope.decl.from !== THEME_FED) continue;
+		const sectionId = chain[1].key;
+		if (!Object.hasOwn(body, sectionId) || body[sectionId] !== nodes[1]) continue;
+		const provider = nodes[scope.index];
+		let list = lists.get(provider);
+		if (!list) {
+			let section = clones.get(sectionId);
+			if (!section) clones.set(sectionId, section = structuredClone(body[sectionId]));
+			list = {
+				sectionId,
+				path: chain.slice(2, scope.index + 1).map((link) => link.key),
+				resource,
+				section,
+				metafieldKeys: []
+			};
+			lists.set(provider, list);
+		}
+		const twin = routeTwin(d);
+		if (resource === "product" && twin?.source === "product_metafield") {
+			const key = `${twin.namespace}.${twin.key}`;
+			if (!list.metafieldKeys.includes(key)) list.metafieldKeys.push(key);
+		}
+	}
+	return [...lists.values()];
+}
+/** The per-item values of one `$theme` list for a batch of its entries — the
+* whole-value and inline passes run over a copy of the list's section alone,
+* with the batch as the list's items. Only what the subtree binds is read, so
+* an entry needs the `metafieldKeys` its list asked for. `route` resolves the
+* route sources a per-item string mixes in; leave out what the request does
+* not have and those tokens blank, as they would anywhere else. */
+async function resolveListOverlays(cfg, list, entries, route = {}) {
+	const section = structuredClone(list.section);
+	const template = { sections: { [list.sectionId]: section } };
+	let provider = section;
+	for (const id of list.path) provider = provider?.blocks?.[id];
+	if (!provider || entries.length === 0) return {};
+	const [metaobjectFields, closest] = await Promise.all([loadMetaobjectFieldSources(template, null), resolveClosestResources(cfg, template, route, void 0, new WeakMap([[provider, [...entries]]]))]);
+	applyInlineSourceTokens(template, route, metaobjectFields, closest);
+	const out = {};
+	const collect = (node, path) => {
+		for (const [id, child] of Object.entries(node.blocks ?? {})) {
+			const c = child;
+			const at = [...path, id];
+			if (c.closestSettings && Object.keys(c.closestSettings).length > 0) out[at.join("/")] = c.closestSettings;
+			collect(c, at);
+		}
+	};
+	collect(provider, []);
+	return out;
+}
+//#endregion
+export { collectClosestNeeds, collectFedLists, resolveClosestResources, resolveListOverlays };

package/dist/dynamic-sources.d.ts

@@ -1,28 +1,61 @@
 import { DynamicSourceArticle, DynamicSourceBlog, DynamicSourceCollection, DynamicSourcePage, SectionGroupJson, TemplateJson, ThemeLoaderConfig } from "./types.js";
+import { ClosestLookup, ProductAttributeKey, RouteMetafieldSource } from "@shop-on/theme-contract";
+import { Money } from "@shop-on/theme-runtime/money";
 import { ProductData } from "@shop-on/theme-server/product";
 //#region src/dynamic-sources.d.ts
 /** Route product projection the dynamic-source passes actually read. */
 export type DynamicSourceProduct = Pick<ProductData, "title" | "vendor" | "price" | "metafields"> | null;
+/** The product projection every product source reads — the route
+ * `ProductData`, a `product` picker's, or a list's `CollectionProductData`
+ * card: all three carry these four. */
+export interface ClosestProduct {
+  title: string;
+  vendor?: string | null;
+  price: Money;
+  metafields?: Record<string, {
+    type: string;
+    value: string;
+  }>;
+}
+/** The product's inline attributes — ONE builder for the route pass and the
+ * closest items. `satisfies` so adding a PRODUCT_ATTRIBUTE_KEYS entry without
+ * populating it here is a compile error, not a silent empty render. */
+export declare function productAttributes(p: ClosestProduct): Record<ProductAttributeKey, string>;
 /** entry id → field key → { type, value } — the shape the whole-value + inline
  * binding passes read for `metaobject_field` sources. */
 export type MetaobjectFieldSources = Record<string, Record<string, {
   type: string;
   value: string;
 }>>;
+/** "namespace.key" → wire field — a resource's storefront metafields. */
+export type MetafieldMap = Record<string, {
+  type: string;
+  value: string;
+}>;
+/** The route collection's, page's, blog's or article's metafields, keyed by
+ * the source that reads them. */
+export type RouteMetafields = Partial<Record<RouteMetafieldSource, MetafieldMap>>;
+type RouteResources = Pick<DynamicSourceRoute, "collection" | "page" | "blog" | "article">;
+/** Each route resource's metafields, read only when the template binds that
+ * resource's source (sidecar or inline token) and the theme supplies the
+ * provider. A load that binds none returns `{}` without a request — which is
+ * what keeps the metafield read off every page that does not use it. */
+export declare function loadRouteMetafields(template: unknown, route: RouteResources): Promise<RouteMetafields>;
 /** Fetch every metaobject entry the template needs, keyed by the numeric entry
  * id: the entries PINNED by `metaobject_field` descriptors (whole-value
  * bindings + inline tokens) UNION the entries a field-bearing
- * `product_metafield` binding traverses (each METAOBJECT_REFERENCE metafield
- * value on the route product). Early-out (no fetch) when the template
- * references none. `fetchMetaobject` is memoTTL'd + content-version keyed, so
- * repeats collapse to one trip. */
-export declare function loadMetaobjectFieldSources(template: unknown, product: Pick<ProductData, "metafields"> | null): Promise<MetaobjectFieldSources>;
-/** Whole-value binding pass (product_metafield + metaobject_field +
- * collection_attribute), sharing one schema-derived `sinkTypeAt` so every
+ * `product_metafield` or route-resource (`collection_metafield`, …) binding
+ * traverses (each METAOBJECT_REFERENCE metafield value on the route resource).
+ * Early-out (no fetch) when the template references none. `fetchMetaobject` is
+ * memoTTL'd + content-version keyed, so repeats collapse to one trip. */
+export declare function loadMetaobjectFieldSources(template: unknown, product: Pick<ProductData, "metafields"> | null, routeMetafields?: RouteMetafields | Promise<RouteMetafields>): Promise<MetaobjectFieldSources>;
+export declare function loadSinkTypeAt(cfg: ThemeLoaderConfig): Promise<(node: unknown, settingId: string) => string | undefined>;
+/** Whole-value binding pass (product_metafield + the route-resource
+ * `*_metafield` sources + metaobject_field + collection_attribute), sharing one schema-derived `sinkTypeAt` so every
  * source routes by the theme's declared sink. Runs BEFORE the picker specs so a
  * bound GID is in place for the `${id}Data` resolution to dereference. The
  * collection description is fetched only when a sidecar binds it. */
-export declare function applyWholeValueBindings(cfg: ThemeLoaderConfig, template: unknown, product: DynamicSourceProduct, collection: DynamicSourceCollection, metaobjectFields: MetaobjectFieldSources): Promise<void>;
+export declare function applyWholeValueBindings(cfg: ThemeLoaderConfig, template: unknown, product: DynamicSourceProduct, collection: DynamicSourceCollection, metaobjectFields: MetaobjectFieldSources, routeMetafields?: RouteMetafields): Promise<void>;
 /** The route resources an inline token can resolve against. Each is `null`
  * (or absent) on every template but its own, which is what makes a token in a
  * section group render "" instead of leaking its descriptor. One object rather
@@ -31,6 +64,9 @@ export declare function applyWholeValueBindings(cfg: ThemeLoaderConfig, template
 export interface DynamicSourceRoute {
   product?: DynamicSourceProduct;
   collection?: DynamicSourceCollection;
+  /** The route resource's metafields as `loadRouteMetafields` read them —
+   * resolved once, before the whole-value pass, and reused here. */
+  routeMetafields?: RouteMetafields;
   page?: DynamicSourcePage;
   blog?: DynamicSourceBlog;
   article?: DynamicSourceArticle;
@@ -38,9 +74,11 @@ export interface DynamicSourceRoute {
 /** The SINGLE inline-source pass — product attributes/metafields (PDP only) +
  * collection attributes (PLP only) + page attributes (CMS page only) + blog and
  * article attributes (their own templates only) + metaobject fields (every
- * template) folded into one substitution so a resolved value is never
- * re-scanned. Runs LAST in `runEnrichment`. */
-export declare function applyInlineSourceTokens(template: unknown, route: DynamicSourceRoute, metaobjectFields: MetaobjectFieldSources): void;
+ * template) + the `closest_*` arms through `closest` (the per-node scope
+ * lookup `resolveClosestResources` built; absent ⇒ they blank) folded into one
+ * substitution so a resolved value is never re-scanned. Runs LAST in
+ * `runEnrichment`. */
+export declare function applyInlineSourceTokens(template: unknown, route: DynamicSourceRoute, metaobjectFields: MetaobjectFieldSources, closest?: ClosestLookup): void;
 /** Merchant translation overlay for editor-authored template content, applied
  * to the raw parsed template BEFORE picker enrichment (see
  * applyContentOverrides for why the order is load-bearing). One fetch per
@@ -57,4 +95,5 @@ export declare function overlayTemplateTranslations(cfg: ThemeLoaderConfig, temp
 /** SETTINGS_DATA sibling of the template overlay: flat setting-id keys applied
  * onto the raw theme-settings map, before its own enrichment pass. */
 export declare function overlayThemeSettingsTranslations(cfg: ThemeLoaderConfig, settings: Record<string, unknown>, locale: string): Promise<void>;
-//#endregion
+//#endregion
+export {};

package/dist/dynamic-sources.js

@@ -1,45 +1,74 @@
 import { loadBlockSchemas, loadSectionSchemas } from "./disk.js";
 import { metaobjectModule, translationsModule } from "./server-modules.js";
-import { applyCollectionAttributeBindings, applyInlineSources, applyMetafieldBindings, applyMetaobjectFieldBindings, collectCollectionAttributeBindings, collectMetaobjectEntryIds, collectTraversedEntryIds, metaobjectGid } from "@shop-on/theme-contract";
+import { ROUTE_METAFIELD_RESOURCE, ROUTE_METAFIELD_SOURCES, applyCollectionAttributeBindings, applyInlineSources, applyMetafieldBindings, applyMetaobjectFieldBindings, collectCollectionAttributeBindings, collectMetaobjectEntryIds, collectTraversedEntryIds, metaobjectGid, templateReferencesSource } from "@shop-on/theme-contract";
 import { formatMoney } from "@shop-on/theme-runtime/money";
 import { serializeRichText } from "@shop-on/theme-runtime/richtext";
 //#region src/dynamic-sources.ts
+/** The product's inline attributes — ONE builder for the route pass and the
+* closest items. `satisfies` so adding a PRODUCT_ATTRIBUTE_KEYS entry without
+* populating it here is a compile error, not a silent empty render. */
+function productAttributes(p) {
+	return {
+		title: p.title,
+		vendor: p.vendor ?? "",
+		price: formatMoney(p.price)
+	};
+}
+/** Each route resource's metafields, read only when the template binds that
+* resource's source (sidecar or inline token) and the theme supplies the
+* provider. A load that binds none returns `{}` without a request — which is
+* what keeps the metafield read off every page that does not use it. */
+async function loadRouteMetafields(template, route) {
+	const reads = ROUTE_METAFIELD_SOURCES.map(async (source) => {
+		const resource = route[ROUTE_METAFIELD_RESOURCE[source]];
+		if (!resource?.getMetafields || !templateReferencesSource(template, source)) return null;
+		try {
+			return [source, await resource.getMetafields()];
+		} catch (err) {
+			console.warn(`[loadRouteMetafields] ${source} read failed:`, err);
+			return null;
+		}
+	});
+	return Object.fromEntries((await Promise.all(reads)).filter((r) => r !== null));
+}
 const MAX_METAOBJECT_ENTRIES = 50;
 /** Fetch every metaobject entry the template needs, keyed by the numeric entry
 * id: the entries PINNED by `metaobject_field` descriptors (whole-value
 * bindings + inline tokens) UNION the entries a field-bearing
-* `product_metafield` binding traverses (each METAOBJECT_REFERENCE metafield
-* value on the route product). Early-out (no fetch) when the template
-* references none. `fetchMetaobject` is memoTTL'd + content-version keyed, so
-* repeats collapse to one trip. */
-async function loadMetaobjectFieldSources(template, product) {
-	const pinned = collectMetaobjectEntryIds(template);
-	const traversed = collectTraversedEntryIds(template, product?.metafields ?? {});
+* `product_metafield` or route-resource (`collection_metafield`, …) binding
+* traverses (each METAOBJECT_REFERENCE metafield value on the route resource).
+* Early-out (no fetch) when the template references none. `fetchMetaobject` is
+* memoTTL'd + content-version keyed, so repeats collapse to one trip. */
+async function loadMetaobjectFieldSources(template, product, routeMetafields = {}) {
 	const seen = /* @__PURE__ */ new Set();
 	const ids = [];
-	for (const id of pinned) {
-		if (seen.has(id)) continue;
-		seen.add(id);
-		ids.push(id);
-	}
+	const append = (list) => {
+		for (const id of list) {
+			if (seen.has(id)) continue;
+			seen.add(id);
+			ids.push(id);
+		}
+	};
+	append(collectMetaobjectEntryIds(template));
 	const pinnedCount = ids.length;
-	for (const id of traversed) {
-		if (seen.has(id)) continue;
-		seen.add(id);
-		ids.push(id);
-	}
-	if (ids.length === 0) return {};
-	let entryIds = ids;
-	if (ids.length > MAX_METAOBJECT_ENTRIES) {
-		console.warn(`[loadMetaobjectFieldSources] template references ${ids.length} metaobject entries (${pinnedCount} pinned + ${ids.length - pinnedCount} traversed); capping the fetch at ${MAX_METAOBJECT_ENTRIES}.`);
-		entryIds = ids.slice(0, MAX_METAOBJECT_ENTRIES);
-	}
-	const { fetchMetaobject } = await metaobjectModule();
-	const entries = await Promise.all(entryIds.map((id) => fetchMetaobject(metaobjectGid(id))));
+	append(collectTraversedEntryIds(template, product?.metafields ?? {}));
+	const fetchBatch = async (batch) => {
+		if (batch.length === 0) return [];
+		const { fetchMetaobject } = await metaobjectModule();
+		return Promise.all(batch.map(async (id) => [id, await fetchMetaobject(metaobjectGid(id))]));
+	};
+	const early = ids.length;
+	const batches = await Promise.all([fetchBatch(ids.slice(0, MAX_METAOBJECT_ENTRIES)), Promise.resolve(routeMetafields).then((maps) => {
+		for (const source of ROUTE_METAFIELD_SOURCES) {
+			const map = maps[source];
+			if (map) append(collectTraversedEntryIds(template, map, source));
+		}
+		return fetchBatch(ids.slice(early, MAX_METAOBJECT_ENTRIES));
+	})]);
+	if (ids.length > MAX_METAOBJECT_ENTRIES) console.warn(`[loadMetaobjectFieldSources] template references ${ids.length} metaobject entries (${pinnedCount} pinned + ${ids.length - pinnedCount} traversed); capping the fetch at ${MAX_METAOBJECT_ENTRIES}.`);
 	const sources = {};
-	entryIds.forEach((entryId, i) => {
-		const entry = entries[i];
-		if (!entry) return;
+	for (const [entryId, entry] of batches.flat()) {
+		if (!entry) continue;
 		const fields = {};
 		for (const [key, field] of Object.entries(entry.fields)) {
 			if (field.value == null) continue;
@@ -49,7 +78,7 @@ async function loadMetaobjectFieldSources(template, product) {
 			};
 		}
 		sources[entryId] = fields;
-	});
+	}
 	return sources;
 }
 async function loadSinkTypeAt(cfg) {
@@ -57,15 +86,15 @@ async function loadSinkTypeAt(cfg) {
 	return (node, settingId) => {
 		const type = node.type;
 		if (!type) return void 0;
-		return (sectionSchemas.get(type) ?? blockSchemas.get(type))?.settings?.find((s) => s.id === settingId)?.type;
+		return (sectionSchemas.get(type) ?? blockSchemas.get(type) ?? blockSchemas.get(type.replace(/^_/, "")))?.settings?.find((s) => s.id === settingId)?.type;
 	};
 }
-/** Whole-value binding pass (product_metafield + metaobject_field +
-* collection_attribute), sharing one schema-derived `sinkTypeAt` so every
+/** Whole-value binding pass (product_metafield + the route-resource
+* `*_metafield` sources + metaobject_field + collection_attribute), sharing one schema-derived `sinkTypeAt` so every
 * source routes by the theme's declared sink. Runs BEFORE the picker specs so a
 * bound GID is in place for the `${id}Data` resolution to dereference. The
 * collection description is fetched only when a sidecar binds it. */
-async function applyWholeValueBindings(cfg, template, product, collection, metaobjectFields) {
+async function applyWholeValueBindings(cfg, template, product, collection, metaobjectFields, routeMetafields = {}) {
 	const sinkTypeAt = await loadSinkTypeAt(cfg);
 	if (collection && collectCollectionAttributeBindings(template).includes("description")) {
 		const descriptionHtml = await collection.getDescriptionHtml();
@@ -79,27 +108,35 @@ async function applyWholeValueBindings(cfg, template, product, collection, metao
 		...opts,
 		metaobjectFields
 	});
+	for (const source of ROUTE_METAFIELD_SOURCES) {
+		const map = routeMetafields[source];
+		if (map) applyMetafieldBindings(template, map, {
+			...opts,
+			metaobjectFields,
+			source
+		});
+	}
 	applyMetaobjectFieldBindings(template, metaobjectFields, opts);
 }
 /** The SINGLE inline-source pass — product attributes/metafields (PDP only) +
 * collection attributes (PLP only) + page attributes (CMS page only) + blog and
 * article attributes (their own templates only) + metaobject fields (every
-* template) folded into one substitution so a resolved value is never
-* re-scanned. Runs LAST in `runEnrichment`. */
-function applyInlineSourceTokens(template, route, metaobjectFields) {
-	const { product = null, collection = null, page = null, blog = null, article = null } = route;
+* template) + the `closest_*` arms through `closest` (the per-node scope
+* lookup `resolveClosestResources` built; absent ⇒ they blank) folded into one
+* substitution so a resolved value is never re-scanned. Runs LAST in
+* `runEnrichment`. */
+function applyInlineSourceTokens(template, route, metaobjectFields, closest) {
+	const { product = null, collection = null, routeMetafields = {}, page = null, blog = null, article = null } = route;
 	applyInlineSources(template, {
 		metafields: product?.metafields ?? {},
-		attributes: product ? {
-			title: product.title,
-			vendor: product.vendor ?? "",
-			price: formatMoney(product.price)
-		} : {},
+		attributes: product ? productAttributes(product) : {},
 		collectionAttributes: collection ? { title: collection.title } : {},
+		routeMetafields,
 		pageAttributes: page ? { title: page.title } : {},
 		blogAttributes: blog ? { title: blog.title } : {},
 		articleAttributes: article ? { title: article.title } : {},
-		metaobjectFields
+		metaobjectFields,
+		closest
 	});
 }
 /** Merchant translation overlay for editor-authored template content, applied
@@ -146,4 +183,4 @@ async function overlayThemeSettingsTranslations(cfg, settings, locale) {
 	} catch {}
 }
 //#endregion
-export { applyInlineSourceTokens, applyWholeValueBindings, loadMetaobjectFieldSources, overlayTemplateTranslations, overlayThemeSettingsTranslations };
+export { applyInlineSourceTokens, applyWholeValueBindings, loadMetaobjectFieldSources, loadRouteMetafields, loadSinkTypeAt, overlayTemplateTranslations, overlayThemeSettingsTranslations, productAttributes };

package/dist/enrich.js

@@ -1,5 +1,6 @@
 import { loadBlockSchemas, loadSectionSchemas } from "./disk.js";
-import { applyInlineSourceTokens, applyWholeValueBindings, loadMetaobjectFieldSources } from "./dynamic-sources.js";
+import { applyInlineSourceTokens, applyWholeValueBindings, loadMetaobjectFieldSources, loadRouteMetafields } from "./dynamic-sources.js";
+import { collectClosestNeeds, resolveClosestResources } from "./closest-sources.js";
 import { resolveReviewLists, standardSpecs } from "./specs.js";
 import { buildDisabledAncestorSet, buildParentMap, resolveField } from "@shop-on/theme-contract";
 //#region src/enrich.ts
@@ -43,21 +44,31 @@ async function runEnrichment(cfg, template, adapter, opts = {}) {
 		flags: await adapter.requestFlags?.(opts.sid, opts.locale) ?? {}
 	};
 	const sections = flattenSections(template);
-	const metaobjectFields = await loadMetaobjectFieldSources(template, req.product);
-	await applyWholeValueBindings(cfg, template, req.product, req.collection, metaobjectFields);
+	const routeMetafieldsRead = loadRouteMetafields(template, req);
+	const [routeMetafields, metaobjectFields, closestNeeds] = await Promise.all([
+		routeMetafieldsRead,
+		loadMetaobjectFieldSources(template, req.product, routeMetafieldsRead),
+		collectClosestNeeds(cfg, template, req)
+	]);
+	await applyWholeValueBindings(cfg, template, req.product, req.collection, metaobjectFields, routeMetafields);
 	const resolverCtx = await buildResolverCtx(cfg, template);
 	const specCtx = {
 		req,
 		adapter,
-		disabledAncestors: resolverCtx.disabledAncestors
+		disabledAncestors: resolverCtx.disabledAncestors,
+		closestNeeds: closestNeeds.providers
 	};
 	await Promise.all([
 		...standardSpecs(specCtx).map((spec) => resolveField(template, spec, resolverCtx)),
 		resolveReviewLists(template, resolverCtx, specCtx),
 		...(adapter.customPasses ?? []).map((pass) => pass(sections, req))
 	]);
+	const closest = await resolveClosestResources(cfg, template, req, closestNeeds);
 	await adapter.postPickers?.(sections, req);
-	applyInlineSourceTokens(template, req, metaobjectFields);
+	applyInlineSourceTokens(template, {
+		...req,
+		routeMetafields
+	}, metaobjectFields, closest);
 	return req.flags;
 }
 //#endregion

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 import { ArgOf, ArgPolicy, BlogArg, CollectionArg, DynamicSourceArticle, DynamicSourceBlog, DynamicSourceCollection, DynamicSourcePage, EnrichOverride, EnrichPass, EnrichRequest, FileArg, LoadedTemplate, LocaleArg, PickerArgs, PickerType, ProductArg, SKIP, SectionGroupJson, SectionInstance, Skip, TemplateJson, ThemeArgPolicies, ThemeEnrichAdapter, ThemeLoaderConfig, Transform } from "./types.js";
 import { SAFE_TEMPLATE_ID, buildSectionInstance, loadBlockSchemas, loadPreviewLocale, loadSectionGroupsForLayout, loadSectionSchemaJson, loadSectionSchemas, loadSettingsSchema, loadTemplate, loadThemeSettings, resolveTranslations } from "./disk.js";
-import { DynamicSourceProduct, DynamicSourceRoute, MetaobjectFieldSources, applyInlineSourceTokens, applyWholeValueBindings, loadMetaobjectFieldSources, overlayTemplateTranslations, overlayThemeSettingsTranslations } from "./dynamic-sources.js";
+import { ClosestProduct, DynamicSourceProduct, DynamicSourceRoute, MetaobjectFieldSources, RouteMetafields, applyInlineSourceTokens, applyWholeValueBindings, loadMetaobjectFieldSources, loadRouteMetafields, overlayTemplateTranslations, overlayThemeSettingsTranslations } from "./dynamic-sources.js";
 import { EnrichOptions, buildResolverCtx, flattenSections, runEnrichment } from "./enrich.js";
 import { buildOrchestratorUrl, fetchPreviewSettings, fetchPreviewTemplate, previewEnabled } from "./orchestrator.js";
 import { loadRawThemeSettings, loadTemplateForRequest, resolveTemplateVariant } from "./template-request.js";
+import { ClosestNeeds, ClosestNeedsMap, FedList, collectClosestNeeds, collectFedLists, resolveClosestResources, resolveListOverlays } from "./closest-sources.js";
 import { AnySpec, SpecContext, resolveReviewLists, standardSpecs } from "./specs.js";
 import { enrichThemeSettings } from "./theme-settings.js";
 import { SectionPreviewInput, SectionPreviewOptions, buildSectionPreviewTemplate } from "./section-preview.js";
 import { SeoContext, blogPerPage, buildBreadcrumb, collectionPerPage, emptySearchPage, seoContext } from "./seo.js";
-export { type AnySpec, type ArgOf, type ArgPolicy, type BlogArg, type CollectionArg, type DynamicSourceArticle, type DynamicSourceBlog, type DynamicSourceCollection, type DynamicSourcePage, type DynamicSourceProduct, type DynamicSourceRoute, type EnrichOptions, type EnrichOverride, type EnrichPass, type EnrichRequest, type FileArg, type LoadedTemplate, type LocaleArg, type MetaobjectFieldSources, type PickerArgs, type PickerType, type ProductArg, SAFE_TEMPLATE_ID, SKIP, type SectionGroupJson, type SectionInstance, type SectionPreviewInput, type SectionPreviewOptions, type SeoContext, type Skip, type SpecContext, type TemplateJson, type ThemeArgPolicies, type ThemeEnrichAdapter, type ThemeLoaderConfig, type Transform, applyInlineSourceTokens, applyWholeValueBindings, blogPerPage, buildBreadcrumb, buildOrchestratorUrl, buildResolverCtx, buildSectionInstance, buildSectionPreviewTemplate, collectionPerPage, emptySearchPage, enrichThemeSettings, fetchPreviewSettings, fetchPreviewTemplate, flattenSections, loadBlockSchemas, loadMetaobjectFieldSources, loadPreviewLocale, loadRawThemeSettings, loadSectionGroupsForLayout, loadSectionSchemaJson, loadSectionSchemas, loadSettingsSchema, loadTemplate, loadTemplateForRequest, loadThemeSettings, overlayTemplateTranslations, overlayThemeSettingsTranslations, previewEnabled, resolveReviewLists, resolveTemplateVariant, resolveTranslations, runEnrichment, seoContext, standardSpecs };
+export { type AnySpec, type ArgOf, type ArgPolicy, type BlogArg, type ClosestNeeds, type ClosestNeedsMap, type ClosestProduct, type CollectionArg, type DynamicSourceArticle, type DynamicSourceBlog, type DynamicSourceCollection, type DynamicSourcePage, type DynamicSourceProduct, type DynamicSourceRoute, type EnrichOptions, type EnrichOverride, type EnrichPass, type EnrichRequest, type FedList, type FileArg, type LoadedTemplate, type LocaleArg, type MetaobjectFieldSources, type PickerArgs, type PickerType, type ProductArg, type RouteMetafields, SAFE_TEMPLATE_ID, SKIP, type SectionGroupJson, type SectionInstance, type SectionPreviewInput, type SectionPreviewOptions, type SeoContext, type Skip, type SpecContext, type TemplateJson, type ThemeArgPolicies, type ThemeEnrichAdapter, type ThemeLoaderConfig, type Transform, applyInlineSourceTokens, applyWholeValueBindings, blogPerPage, buildBreadcrumb, buildOrchestratorUrl, buildResolverCtx, buildSectionInstance, buildSectionPreviewTemplate, collectClosestNeeds, collectFedLists, collectionPerPage, emptySearchPage, enrichThemeSettings, fetchPreviewSettings, fetchPreviewTemplate, flattenSections, loadBlockSchemas, loadMetaobjectFieldSources, loadPreviewLocale, loadRawThemeSettings, loadRouteMetafields, loadSectionGroupsForLayout, loadSectionSchemaJson, loadSectionSchemas, loadSettingsSchema, loadTemplate, loadTemplateForRequest, loadThemeSettings, overlayTemplateTranslations, overlayThemeSettingsTranslations, previewEnabled, resolveClosestResources, resolveListOverlays, resolveReviewLists, resolveTemplateVariant, resolveTranslations, runEnrichment, seoContext, standardSpecs };

package/dist/index.js

@@ -1,11 +1,12 @@
 import { SKIP } from "./types.js";
 import { SAFE_TEMPLATE_ID, buildSectionInstance, loadBlockSchemas, loadPreviewLocale, loadSectionGroupsForLayout, loadSectionSchemaJson, loadSectionSchemas, loadSettingsSchema, loadTemplate, loadThemeSettings, resolveTranslations } from "./disk.js";
 import { buildOrchestratorUrl, fetchPreviewSettings, fetchPreviewTemplate, previewEnabled } from "./orchestrator.js";
-import { applyInlineSourceTokens, applyWholeValueBindings, loadMetaobjectFieldSources, overlayTemplateTranslations, overlayThemeSettingsTranslations } from "./dynamic-sources.js";
+import { applyInlineSourceTokens, applyWholeValueBindings, loadMetaobjectFieldSources, loadRouteMetafields, overlayTemplateTranslations, overlayThemeSettingsTranslations } from "./dynamic-sources.js";
 import { loadRawThemeSettings, loadTemplateForRequest, resolveTemplateVariant } from "./template-request.js";
+import { collectClosestNeeds, collectFedLists, resolveClosestResources, resolveListOverlays } from "./closest-sources.js";
 import { resolveReviewLists, standardSpecs } from "./specs.js";
 import { buildResolverCtx, flattenSections, runEnrichment } from "./enrich.js";
 import { enrichThemeSettings } from "./theme-settings.js";
 import { buildSectionPreviewTemplate } from "./section-preview.js";
 import { blogPerPage, buildBreadcrumb, collectionPerPage, emptySearchPage, seoContext } from "./seo.js";
-export { SAFE_TEMPLATE_ID, SKIP, applyInlineSourceTokens, applyWholeValueBindings, blogPerPage, buildBreadcrumb, buildOrchestratorUrl, buildResolverCtx, buildSectionInstance, buildSectionPreviewTemplate, collectionPerPage, emptySearchPage, enrichThemeSettings, fetchPreviewSettings, fetchPreviewTemplate, flattenSections, loadBlockSchemas, loadMetaobjectFieldSources, loadPreviewLocale, loadRawThemeSettings, loadSectionGroupsForLayout, loadSectionSchemaJson, loadSectionSchemas, loadSettingsSchema, loadTemplate, loadTemplateForRequest, loadThemeSettings, overlayTemplateTranslations, overlayThemeSettingsTranslations, previewEnabled, resolveReviewLists, resolveTemplateVariant, resolveTranslations, runEnrichment, seoContext, standardSpecs };
+export { SAFE_TEMPLATE_ID, SKIP, applyInlineSourceTokens, applyWholeValueBindings, blogPerPage, buildBreadcrumb, buildOrchestratorUrl, buildResolverCtx, buildSectionInstance, buildSectionPreviewTemplate, collectClosestNeeds, collectFedLists, collectionPerPage, emptySearchPage, enrichThemeSettings, fetchPreviewSettings, fetchPreviewTemplate, flattenSections, loadBlockSchemas, loadMetaobjectFieldSources, loadPreviewLocale, loadRawThemeSettings, loadRouteMetafields, loadSectionGroupsForLayout, loadSectionSchemaJson, loadSectionSchemas, loadSettingsSchema, loadTemplate, loadTemplateForRequest, loadThemeSettings, overlayTemplateTranslations, overlayThemeSettingsTranslations, previewEnabled, resolveClosestResources, resolveListOverlays, resolveReviewLists, resolveTemplateVariant, resolveTranslations, runEnrichment, seoContext, standardSpecs };

package/dist/specs.d.ts

@@ -1,4 +1,5 @@
 import { CollectionArg, EnrichRequest, ProductArg, ThemeEnrichAdapter } from "./types.js";
+import { ClosestNeedsMap } from "./closest-sources.js";
 import { ResolverCtx, ResolverSpec } from "@shop-on/theme-contract";
 //#region src/specs.d.ts
 export type AnySpec = ResolverSpec<any, any>;
@@ -10,6 +11,11 @@ export interface SpecContext {
    * answer "my section is off" — this answers "a container above me is off",
    * however many levels up. Optional: absent reads as "none". */
   disabledAncestors?: WeakSet<object>;
+  /** What the `closest_*` sources bound under each provider picker need its
+   * fetch to carry (`collectClosestNeeds`). Merged ON TOP of whatever arg the
+   * policy chain produced, so a theme's policy never learns about bindings.
+   * Optional: absent reads as "nothing bound". */
+  closestNeeds?: ClosestNeedsMap["providers"];
 }
 export declare function fetchCollectionByFlavor(ref: string, arg: CollectionArg): Promise<import("@shop-on/theme-server/collection").CollectionData | import("@shop-on/theme-server/collection").CollectionMeta | null>;
 export declare function fetchProductByFlavor(ref: string, arg: ProductArg): Promise<import("@shop-on/theme-server/product").ProductData | null>;

package/dist/specs.js

@@ -15,7 +15,7 @@ function isClaimed(adapter, scope, nodeType, fieldId) {
 * theme policy → the package's lean default. Each layer either answers or
 * defers; only a policy's explicit `SKIP` and the disabled/claim checks
 * decline. */
-function composeArg(type, scope, { req, adapter, disabledAncestors }, lean) {
+function composeArg(type, scope, { req, adapter, disabledAncestors, closestNeeds }, lean) {
 	const policy = adapter.args?.[type]?.[scope];
 	return (node, fieldId, parent) => {
 		if (node?.disabled || parent?.disabled || node && disabledAncestors?.has(node)) return SKIP;
@@ -24,10 +24,39 @@ function composeArg(type, scope, { req, adapter, disabledAncestors }, lean) {
 			parent,
 			req
 		});
-		if (chosen !== void 0) return withReqLocale(type, chosen, req);
-		return lean(node, fieldId, req);
+		const arg = chosen !== void 0 ? withReqLocale(type, chosen, req) : lean(node, fieldId, req);
+		const needs = node ? closestNeeds?.get(node)?.[fieldId] : void 0;
+		return needs ? withClosestNeeds(type, arg, needs) : arg;
 	};
 }
+/** The closest sources bound in this picker's scope, on top of the arg the
+* policy chain chose: the product metafield keys a card must carry — on a
+* product picker's own card, or on each card of the collection it lists. A
+* SKIP stays a SKIP: a declined picker provides nothing. (The collection
+* description is not a fetch arg; `resolveClosestResources` reads it through
+* the lean description query, as the route collection does.) */
+function withClosestNeeds(type, arg, needs) {
+	if (arg === SKIP || !needs.metafieldKeys?.length) return arg;
+	if (type === "product" || type === "product_list" || type === "collection") {
+		const a = arg;
+		return {
+			...a,
+			metafieldKeys: unionKeys(a.metafieldKeys, needs.metafieldKeys)
+		};
+	}
+	return arg;
+}
+function unionKeys(a, b) {
+	if (!b?.length) return a;
+	const out = [...a ?? []];
+	for (const key of b) if (!out.includes(key)) out.push(key);
+	return out;
+}
+/** Sorted so two scopes binding the same keys in a different order share one
+* cache entry and one fetch. */
+function keysKey(keys) {
+	return keys?.length ? [...keys].sort().join(",") : "";
+}
 /** File args carry no locale; every other picker arg does. */
 const LOCALE_FREE_TYPES = /* @__PURE__ */ new Set(["image_picker", "video"]);
 /** A policy that returns a concrete arg but forgets `locale` would silently
@@ -68,7 +97,7 @@ function localeKey(ref, arg) {
 	return `${ref}|${arg.locale ?? ""}`;
 }
 function collectionKey(ref, arg) {
-	return arg.flavor === "full" ? `full|${arg.first}|${arg.mediaFirst}|${arg.includeOptions}|${arg.includeVariants ?? false}|${arg.locale ?? ""}|${ref}` : `${arg.flavor}|${arg.locale ?? ""}|${ref}`;
+	return arg.flavor === "full" ? `full|${arg.first}|${arg.mediaFirst}|${arg.includeOptions}|${arg.includeVariants ?? false}|${arg.locale ?? ""}|${keysKey(arg.metafieldKeys)}|${ref}` : `${arg.flavor}|${arg.locale ?? ""}|${ref}`;
 }
 async function fetchCollectionByFlavor(ref, arg) {
 	const collection = await collectionModule();
@@ -80,11 +109,12 @@ async function fetchCollectionByFlavor(ref, arg) {
 		mediaFirst: arg.mediaFirst,
 		includeOptions: arg.includeOptions,
 		includeVariants: arg.includeVariants,
-		locale: arg.locale
+		locale: arg.locale,
+		metafieldKeys: arg.metafieldKeys
 	});
 }
 function productKey(ref, arg) {
-	return `${arg.flavor}|${arg.includeOptions}|${arg.locale ?? ""}|${arg.metafield ?? ""}|${ref}`;
+	return `${arg.flavor}|${arg.includeOptions}|${arg.locale ?? ""}|${keysKey(arg.metafieldKeys)}|${ref}`;
 }
 async function fetchProductByFlavor(ref, arg) {
 	const product = await productModule();
@@ -98,7 +128,7 @@ async function fetchProductByFlavor(ref, arg) {
 		default: return product.fetchProduct(ref, {
 			includeOptions: arg.includeOptions,
 			locale: arg.locale,
-			metafield: arg.metafield
+			metafieldKeys: arg.metafieldKeys
 		});
 	}
 }

package/dist/types.d.ts

@@ -44,31 +44,42 @@ export type LoadedTemplate = TemplateJson & {
   section_groups?: Record<string, SectionGroupJson>;
   templateId?: string;
 };
+/** A route resource's storefront-visible metafields keyed `"namespace.key"`,
+ * like `ProductData.metafields`. A provider, so the loader reads them only when
+ * the template binds one. Optional on every resource so a theme built before
+ * that resource's `*_metafield` source keeps type-checking; without it the
+ * source renders its literal. */
+type MetafieldsProvider = {
+  getMetafields?: () => Promise<Record<string, {
+    type: string;
+    value: string;
+  }>>;
+};
 /** Route collection the dynamic-source passes read. `title` rides the lean
- * meta read the loader already makes; the description HTML is a provider so it
- * is fetched only when the template binds it. */
-export type DynamicSourceCollection = {
+ * meta read the loader already makes; the description HTML is a provider so
+ * it is fetched only when the template binds it. */
+export type DynamicSourceCollection = ({
   title: string;
   getDescriptionHtml: () => Promise<string | null>;
-} | null;
-/** Route CMS page the dynamic-source passes read. `title` only — it rides the
- * page read the loader already makes, and the page body reaches the storefront
- * through the theme's page-content block, not through a binding. */
-export type DynamicSourcePage = {
+} & MetafieldsProvider) | null;
+/** Route CMS page the dynamic-source passes read. `title` rides the page read
+ * the loader already makes, and the page body reaches the storefront through
+ * the theme's page-content block, not through a binding. */
+export type DynamicSourcePage = ({
   title: string;
-} | null;
-/** Route blog the dynamic-source passes read. `title` only — it rides the blog
- * read the loader already makes, and the article list reaches the storefront
- * through the theme's blog section, not through a binding. */
-export type DynamicSourceBlog = {
+} & MetafieldsProvider) | null;
+/** Route blog the dynamic-source passes read. `title` rides the blog read the
+ * loader already makes, and the article list reaches the storefront through
+ * the theme's blog section, not through a binding. */
+export type DynamicSourceBlog = ({
   title: string;
-} | null;
-/** Route article the dynamic-source passes read. `title` only — it rides the
- * article read the loader already makes; the body and the cover reach the
- * storefront through the theme's own blocks. */
-export type DynamicSourceArticle = {
+} & MetafieldsProvider) | null;
+/** Route article the dynamic-source passes read. `title` rides the article
+ * read the loader already makes; the body and the cover reach the storefront
+ * through the theme's own blocks. */
+export type DynamicSourceArticle = ({
   title: string;
-} | null;
+} & MetafieldsProvider) | null;
 /** Per-request context every spec's arg policy sees. `flags` is whatever the
  * theme's `requestFlags` hook returned (care: `{ cardOptions: boolean }`). */
 export interface EnrichRequest {
@@ -111,14 +122,22 @@ export interface CollectionArg {
    * whose swatches switch it between them. Off when omitted. */
   includeVariants?: boolean;
   locale?: string;
+  /** `full` only: storefront-visible metafields (`namespace.key`) to carry on
+   * each product card, for the `closest_product_metafield` sources bound in
+   * the list's per-item subtrees. The loader fills it from the bindings; a
+   * policy never has to. */
+  metafieldKeys?: string[];
 }
 export interface ProductArg {
   flavor: "card" | "showcase" | "listDetail" | "full";
   includeOptions: boolean;
   locale?: string;
-  /** `card` only: one storefront-visible metafield (`namespace.key`) to carry
-   * in the product's `metafields`. */
-  metafield?: string;
+  /** `card` only: the storefront-visible metafields (`namespace.key`) to carry
+   * in the product's `metafields` — a theme's own needs (volt's variation
+   * swatches name one) plus whatever `closest_product_metafield` sources the
+   * loader finds bound in the picker's scope. `full` carries every visible
+   * metafield already; `showcase` / `listDetail` carry none. */
+  metafieldKeys?: string[];
 }
 export interface BlogArg {
   first: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shop-on/theme-loader",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "license": "SEE LICENSE IN dist/LICENSE.md",
   "files": [
     "dist"
@@ -22,10 +22,10 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@shop-on/theme-contract": "0.5.0",
-    "@shop-on/theme-runtime": "0.5.0",
-    "@shop-on/theme-system": "0.5.0",
-    "@shop-on/theme-server": "0.5.0"
+    "@shop-on/theme-runtime": "0.6.0",
+    "@shop-on/theme-server": "0.6.0",
+    "@shop-on/theme-contract": "0.6.0",
+    "@shop-on/theme-system": "0.6.0"
   },
   "devDependencies": {
     "@types/node": "26.6.5",