@shop-on/theme-loader 0.0.0-stage → 0.2.0

package/dist/LICENSE.md

@@ -0,0 +1,39 @@
+# Cody Theme Development License
+
+Copyright (c) 2026 Cody LLC. All rights reserved except as granted below.
+
+"The Software" is this package, its source, and its documentation. "The
+Platform" is Cody, the commerce platform operated by Cody LLC.
+
+## 1. Grant
+
+You may use, copy and modify the Software, and distribute modified copies, solely
+to develop, test, and distribute themes, apps and other extensions that run on
+the Platform.
+
+## 2. Restrictions
+
+You may not:
+
+1. use the Software, or anything derived from it, with any commerce platform,
+   storefront or hosting service other than the Platform;
+2. use the Software to build a product that competes with the Platform;
+3. sublicense the Software, or distribute it other than as part of a theme,
+   app or extension for the Platform;
+4. remove or alter this license or any copyright notice in the Software.
+
+## 3. Your work
+
+Themes, apps and extensions you build with the Software are yours. The parts of
+the Software they include stay under this license.
+
+## 4. Termination
+
+This license ends automatically if you break any of its terms. You must then
+stop using the Software and delete your copies of it.
+
+## 5. No warranty
+
+The Software is provided "as is", without warranty of any kind. Cody LLC is not
+liable for any claim, damages or other liability arising from the Software or
+its use.

package/dist/disk.d.ts

@@ -0,0 +1,42 @@
+import { LoadedTemplate, SectionGroupJson } from "./types.js";
+import { buildSectionInstance } from "@shop-on/theme-contract";
+import { BlockSchema, SectionSchema } from "@shop-on/theme-system";
+//#region src/disk.d.ts
+/** Path-segment guard for anything that reaches the disk loaders — template
+ * ids, section types. Dots are allowed so template VARIANTS (`product.sale`)
+ * resolve; `/` and `..` segments cannot survive it. */
+export declare const SAFE_TEMPLATE_ID: RegExp;
+/** Theme-wide settings for the active preset. Missing/partial file → `{}` so a
+ * page renders with theme.css fallbacks rather than 500-ing. */
+export declare function loadThemeSettings(configDir: string): Promise<Record<string, unknown>>;
+/** The theme's settings SCHEMA (groups of `settings[]`), used to discover
+ * theme-wide picker settings. Missing file → `[]`. */
+export declare function loadSettingsSchema(configDir: string): Promise<Array<{
+  settings?: Array<{
+    type?: string;
+    id?: string;
+    allow_uploads?: boolean;
+  }>;
+}>>;
+export declare function loadSectionGroupsForLayout(configDir: string, layoutName: string, listingDir?: string | null): Promise<Record<string, SectionGroupJson> | undefined>;
+/** Exact-id template reader. Not memoized (parses fresh per call), which the
+ * per-locale translation overlay relies on — it mutates the loaded document in
+ * place. If templates are ever cached, the cache key MUST include the locale.
+ *
+ * A missing template returns `undefined` so the CALLER owns the fallback
+ * policy: a silent variant→base swap here would starve the preview-or-disk
+ * retry in `resolveTemplateVariant` and hand editor previews the raw on-disk
+ * scaffold instead of the draft's base template. */
+export declare function loadTemplate(configDir: string, templateId: string): Promise<LoadedTemplate | undefined>;
+export declare function loadBlockSchemas(configDir: string): Promise<Map<string, BlockSchema>>;
+export declare function loadSectionSchemas(configDir: string): Promise<Map<string, SectionSchema>>;
+/** Raw section schema JSON (presets included) for the standalone section
+ * preview — deliberately unparsed, since the preview seeds from the file's own
+ * `presets` blob. */
+export declare function loadSectionSchemaJson(configDir: string, type: string): Promise<Record<string, unknown> | null>;
+/** The schema-locale catalog the section preview resolves `t:` keys against. */
+export declare function loadPreviewLocale(configDir: string, previewLocale?: string): Promise<Record<string, unknown>>;
+/** Deep-resolve `t:` keys in a JSON document against a locale catalog. */
+export declare function resolveTranslations(obj: unknown, locale: Record<string, unknown>): unknown;
+//#endregion
+export { buildSectionInstance };

package/dist/disk.js

@@ -0,0 +1,150 @@
+import { buildSectionInstance } from "@shop-on/theme-contract";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { currentPresetHandle, mergePresetJson } from "@shop-on/theme-contract/preset-listing";
+import { loadBlockSchemasFrom, loadSectionSchemasFrom } from "@shop-on/theme-system";
+//#region src/disk.ts
+/** Path-segment guard for anything that reaches the disk loaders — template
+* ids, section types. Dots are allowed so template VARIANTS (`product.sale`)
+* resolve; `/` and `..` segments cannot survive it. */
+const SAFE_TEMPLATE_ID = /^[a-zA-Z0-9_.-]+$/;
+async function readJson(filePath) {
+	return JSON.parse(await fs.readFile(filePath, "utf-8"));
+}
+function extractPresetSettings(data) {
+	if (data && typeof data === "object" && "presets" in data) {
+		const d = data;
+		return d.presets?.[d.current?.preset ?? ""]?.settings ?? {};
+	}
+	return data ?? {};
+}
+async function readConfigJson(configDir, file) {
+	for (const candidate of [path.join(configDir, file), path.join(configDir, "config", file)]) try {
+		return JSON.parse(await fs.readFile(candidate, "utf-8"));
+	} catch {}
+	return null;
+}
+const artifactDirs = /* @__PURE__ */ new Set();
+async function currentListingDir(configDir) {
+	if (artifactDirs.has(configDir)) return null;
+	try {
+		await fs.readFile(path.join(configDir, "settings-data.json"));
+		artifactDirs.add(configDir);
+		return null;
+	} catch {}
+	const data = await readJson(path.join(configDir, "config", "settings-data.json")).catch(() => null);
+	const override = typeof process === "undefined" ? void 0 : process.env.THEME_PRESET;
+	const handle = currentPresetHandle(data, override);
+	return handle ? path.join(configDir, "listings", handle) : null;
+}
+/** `<configDir>/<dir>/<file>` with the preset listing merged over it. Either
+* half may be missing; both missing → `undefined`. */
+async function readWithListing(configDir, listingDir, dir, file) {
+	const [base, override] = await Promise.all([readJson(path.join(configDir, dir, file)).catch(() => void 0), listingDir ? readJson(path.join(listingDir, dir, file)).catch(() => void 0) : void 0]);
+	if (override === void 0) return base;
+	return base === void 0 ? override : mergePresetJson(base, override);
+}
+/** Theme-wide settings for the active preset. Missing/partial file → `{}` so a
+* page renders with theme.css fallbacks rather than 500-ing. */
+async function loadThemeSettings(configDir) {
+	return extractPresetSettings(await readConfigJson(configDir, "settings-data.json"));
+}
+/** The theme's settings SCHEMA (groups of `settings[]`), used to discover
+* theme-wide picker settings. Missing file → `[]`. */
+async function loadSettingsSchema(configDir) {
+	const raw = await readConfigJson(configDir, "settings-schema.json");
+	return Array.isArray(raw) ? raw : [];
+}
+async function loadSectionGroupsForLayout(configDir, layoutName, listingDir) {
+	if (!SAFE_TEMPLATE_ID.test(layoutName)) return void 0;
+	let layout;
+	try {
+		layout = await readJson(path.join(configDir, "layouts", `${layoutName}.json`));
+	} catch {
+		return;
+	}
+	if (!layout.section_groups?.length) return void 0;
+	const listing = listingDir === void 0 ? await currentListingDir(configDir) : listingDir;
+	const reads = await Promise.all(layout.section_groups.map(async (ref) => {
+		if (!SAFE_TEMPLATE_ID.test(ref.type)) return null;
+		return await readWithListing(configDir, listing, "section-groups", `${ref.type}-group.json`) ?? null;
+	}));
+	const groups = {};
+	for (const group of reads) if (group) groups[group.type] = group;
+	return groups;
+}
+/** Exact-id template reader. Not memoized (parses fresh per call), which the
+* per-locale translation overlay relies on — it mutates the loaded document in
+* place. If templates are ever cached, the cache key MUST include the locale.
+*
+* A missing template returns `undefined` so the CALLER owns the fallback
+* policy: a silent variant→base swap here would starve the preview-or-disk
+* retry in `resolveTemplateVariant` and hand editor previews the raw on-disk
+* scaffold instead of the draft's base template. */
+async function loadTemplate(configDir, templateId) {
+	const listingDir = await currentListingDir(configDir);
+	const template = await readWithListing(configDir, listingDir, "templates", `${templateId}.json`);
+	if (!template) return void 0;
+	const section_groups = await loadSectionGroupsForLayout(configDir, template.layout ?? "main", listingDir);
+	return {
+		...template,
+		section_groups
+	};
+}
+const blockSchemaCache = /* @__PURE__ */ new Map();
+const sectionSchemaCache = /* @__PURE__ */ new Map();
+function loadBlockSchemas(configDir) {
+	let cached = blockSchemaCache.get(configDir);
+	if (!cached) {
+		cached = loadBlockSchemasFrom([path.join(configDir, "blocks")]);
+		blockSchemaCache.set(configDir, cached);
+	}
+	return cached;
+}
+function loadSectionSchemas(configDir) {
+	let cached = sectionSchemaCache.get(configDir);
+	if (!cached) {
+		cached = loadSectionSchemasFrom([path.join(configDir, "sections")]);
+		sectionSchemaCache.set(configDir, cached);
+	}
+	return cached;
+}
+/** Raw section schema JSON (presets included) for the standalone section
+* preview — deliberately unparsed, since the preview seeds from the file's own
+* `presets` blob. */
+async function loadSectionSchemaJson(configDir, type) {
+	if (!SAFE_TEMPLATE_ID.test(type)) return null;
+	try {
+		return await readJson(path.join(configDir, "sections", `${type}.json`));
+	} catch {
+		return null;
+	}
+}
+const previewLocaleCache = /* @__PURE__ */ new Map();
+/** The schema-locale catalog the section preview resolves `t:` keys against. */
+function loadPreviewLocale(configDir, previewLocale = "en.default") {
+	const file = path.join(configDir, "locales", `${previewLocale}.schema.json`);
+	let cached = previewLocaleCache.get(file);
+	if (!cached) {
+		cached = readJson(file).catch(() => ({}));
+		previewLocaleCache.set(file, cached);
+	}
+	return cached;
+}
+/** Deep-resolve `t:` keys in a JSON document against a locale catalog. */
+function resolveTranslations(obj, locale) {
+	if (typeof obj === "string" && obj.startsWith("t:")) {
+		let cur = locale;
+		for (const p of obj.slice(2).split(".")) cur = cur && typeof cur === "object" ? cur[p] : void 0;
+		return typeof cur === "string" ? cur : obj;
+	}
+	if (Array.isArray(obj)) return obj.map((v) => resolveTranslations(v, locale));
+	if (obj && typeof obj === "object") {
+		const out = {};
+		for (const [k, v] of Object.entries(obj)) out[k] = resolveTranslations(v, locale);
+		return out;
+	}
+	return obj;
+}
+//#endregion
+export { SAFE_TEMPLATE_ID, buildSectionInstance, loadBlockSchemas, loadPreviewLocale, loadSectionGroupsForLayout, loadSectionSchemaJson, loadSectionSchemas, loadSettingsSchema, loadTemplate, loadThemeSettings, resolveTranslations };

package/dist/dynamic-sources.d.ts

@@ -0,0 +1,60 @@
+import { DynamicSourceArticle, DynamicSourceBlog, DynamicSourceCollection, DynamicSourcePage, SectionGroupJson, TemplateJson, ThemeLoaderConfig } from "./types.js";
+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;
+/** 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;
+}>>;
+/** 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
+ * 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>;
+/** 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
+ * than five positional args: a source added here is a named field at every call
+ * site, not a `null` in the right slot. */
+export interface DynamicSourceRoute {
+  product?: DynamicSourceProduct;
+  collection?: DynamicSourceCollection;
+  page?: DynamicSourcePage;
+  blog?: DynamicSourceBlog;
+  article?: DynamicSourceArticle;
+}
+/** 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;
+/** 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
+ * container: the template's own JSON_TEMPLATE rows plus one SECTION_GROUP per
+ * group. The section_groups record KEY is the container handle — the
+ * orchestrator's preview merge strips each group's `type` field, so
+ * `group.type` is undefined on the preview path and would fetch zero rows.
+ * Each container has its own try/catch: a failed fetch degrades that slice to
+ * base-language text instead of aborting the others or 500-ing the page. */
+export declare function overlayTemplateTranslations(cfg: ThemeLoaderConfig, template: TemplateJson & {
+  section_groups?: Record<string, SectionGroupJson>;
+  templateId?: string;
+}, locale: string): Promise<void>;
+/** 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

package/dist/dynamic-sources.js

@@ -0,0 +1,149 @@
+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 { formatMoney } from "@shop-on/theme-runtime/money";
+import { serializeRichText } from "@shop-on/theme-runtime/richtext";
+//#region src/dynamic-sources.ts
+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 ?? {});
+	const seen = /* @__PURE__ */ new Set();
+	const ids = [];
+	for (const id of pinned) {
+		if (seen.has(id)) continue;
+		seen.add(id);
+		ids.push(id);
+	}
+	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))));
+	const sources = {};
+	entryIds.forEach((entryId, i) => {
+		const entry = entries[i];
+		if (!entry) return;
+		const fields = {};
+		for (const [key, field] of Object.entries(entry.fields)) {
+			if (field.value == null) continue;
+			fields[key] = {
+				type: field.type,
+				value: field.value
+			};
+		}
+		sources[entryId] = fields;
+	});
+	return sources;
+}
+async function loadSinkTypeAt(cfg) {
+	const [sectionSchemas, blockSchemas] = await Promise.all([loadSectionSchemas(cfg.configDir), loadBlockSchemas(cfg.configDir)]);
+	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;
+	};
+}
+/** Whole-value binding pass (product_metafield + 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) {
+	const sinkTypeAt = await loadSinkTypeAt(cfg);
+	if (collection && collectCollectionAttributeBindings(template).includes("description")) {
+		const descriptionHtml = await collection.getDescriptionHtml();
+		applyCollectionAttributeBindings(template, { descriptionHtml }, { sinkTypeAt });
+	}
+	const opts = {
+		serializeRichText,
+		sinkTypeAt
+	};
+	applyMetafieldBindings(template, product?.metafields ?? {}, {
+		...opts,
+		metaobjectFields
+	});
+	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;
+	applyInlineSources(template, {
+		metafields: product?.metafields ?? {},
+		attributes: product ? {
+			title: product.title,
+			vendor: product.vendor ?? "",
+			price: formatMoney(product.price)
+		} : {},
+		collectionAttributes: collection ? { title: collection.title } : {},
+		pageAttributes: page ? { title: page.title } : {},
+		blogAttributes: blog ? { title: blog.title } : {},
+		articleAttributes: article ? { title: article.title } : {},
+		metaobjectFields
+	});
+}
+/** 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
+* container: the template's own JSON_TEMPLATE rows plus one SECTION_GROUP per
+* group. The section_groups record KEY is the container handle — the
+* orchestrator's preview merge strips each group's `type` field, so
+* `group.type` is undefined on the preview path and would fetch zero rows.
+* Each container has its own try/catch: a failed fetch degrades that slice to
+* base-language text instead of aborting the others or 500-ing the page. */
+async function overlayTemplateTranslations(cfg, template, locale) {
+	if (!cfg.installId) return;
+	const { applyContentOverrides, fetchThemeContent } = await translationsModule();
+	const jobs = [];
+	const templateHandle = template.templateId;
+	if (templateHandle) jobs.push((async () => {
+		try {
+			const rows = await fetchThemeContent(cfg.installId, locale, {
+				type: "JSON_TEMPLATE",
+				handle: templateHandle
+			});
+			applyContentOverrides(template, rows);
+		} catch {}
+	})());
+	for (const [handle, group] of Object.entries(template.section_groups ?? {})) jobs.push((async () => {
+		try {
+			const rows = await fetchThemeContent(cfg.installId, locale, {
+				type: "SECTION_GROUP",
+				handle
+			});
+			applyContentOverrides(group, rows);
+		} catch {}
+	})());
+	await Promise.all(jobs);
+}
+/** SETTINGS_DATA sibling of the template overlay: flat setting-id keys applied
+* onto the raw theme-settings map, before its own enrichment pass. */
+async function overlayThemeSettingsTranslations(cfg, settings, locale) {
+	if (!cfg.installId) return;
+	const { applyContentOverrides, fetchThemeContent } = await translationsModule();
+	try {
+		applyContentOverrides(settings, await fetchThemeContent(cfg.installId, locale, { type: "SETTINGS_DATA" }));
+	} catch {}
+}
+//#endregion
+export { applyInlineSourceTokens, applyWholeValueBindings, loadMetaobjectFieldSources, overlayTemplateTranslations, overlayThemeSettingsTranslations };

package/dist/enrich.d.ts

@@ -0,0 +1,36 @@
+import { EnrichRequest, LoadedTemplate, SectionInstance, ThemeEnrichAdapter, ThemeLoaderConfig } from "./types.js";
+import { ResolverCtx } from "@shop-on/theme-contract";
+//#region src/enrich.d.ts
+/** Every section on the page — the template's own plus each section group's —
+ * in one flat list, the shape theme passes consume. */
+export declare function flattenSections(template: LoadedTemplate): SectionInstance[];
+/** Resolver context for one template: the theme's schema maps (which drive
+ * `schemaType` field discovery at both scopes), the block→section parent map
+ * arg policies read, and the set of blocks sitting under a disabled container
+ * at any depth. */
+export declare function buildResolverCtx(cfg: ThemeLoaderConfig, template: unknown): Promise<ResolverCtx>;
+export interface EnrichOptions {
+  locale?: string;
+  /** Editor session id — only used to build the request flags. */
+  sid?: string;
+  /** Route product for dynamic-source resolution; PDP loaders only. */
+  product?: EnrichRequest["product"];
+  /** Route collection for dynamic-source resolution; collection loaders only. */
+  collection?: EnrichRequest["collection"];
+  /** Route CMS page for dynamic-source resolution; page loaders only. */
+  page?: EnrichRequest["page"];
+  /** Route blog for dynamic-source resolution; blog-listing loaders only. */
+  blog?: EnrichRequest["blog"];
+  /** Route article for dynamic-source resolution; article loaders only. */
+  article?: EnrichRequest["article"];
+}
+/** Resolve every picker on `template` in place, and return the request flags
+ * the adapter resolved. The theme's server fn calls this once per request,
+ * after the template document is resolved.
+ *
+ * Returning the flags is what keeps `requestFlags` a SINGLE read: care's hook
+ * loads the theme-settings document to answer "are card swatches on?", and its
+ * route fetches need the same answer — the caller parks this value on the
+ * template rather than deriving it a second time. */
+export declare function runEnrichment(cfg: ThemeLoaderConfig, template: LoadedTemplate, adapter: ThemeEnrichAdapter, opts?: EnrichOptions): Promise<EnrichRequest["flags"]>;
+//#endregion

package/dist/enrich.js

@@ -0,0 +1,64 @@
+import { loadBlockSchemas, loadSectionSchemas } from "./disk.js";
+import { applyInlineSourceTokens, applyWholeValueBindings, loadMetaobjectFieldSources } from "./dynamic-sources.js";
+import { resolveReviewLists, standardSpecs } from "./specs.js";
+import { buildDisabledAncestorSet, buildParentMap, resolveField } from "@shop-on/theme-contract";
+//#region src/enrich.ts
+/** Every section on the page — the template's own plus each section group's —
+* in one flat list, the shape theme passes consume. */
+function flattenSections(template) {
+	const sections = Object.values(template.sections ?? {});
+	for (const group of Object.values(template.section_groups ?? {})) sections.push(...Object.values(group.sections ?? {}));
+	return sections;
+}
+/** Resolver context for one template: the theme's schema maps (which drive
+* `schemaType` field discovery at both scopes), the block→section parent map
+* arg policies read, and the set of blocks sitting under a disabled container
+* at any depth. */
+async function buildResolverCtx(cfg, template) {
+	const [blockSchemas, sectionSchemas] = await Promise.all([loadBlockSchemas(cfg.configDir), loadSectionSchemas(cfg.configDir)]);
+	return {
+		blockSchemas,
+		sectionSchemas,
+		parentOf: buildParentMap(template),
+		disabledAncestors: buildDisabledAncestorSet(template)
+	};
+}
+/** Resolve every picker on `template` in place, and return the request flags
+* the adapter resolved. The theme's server fn calls this once per request,
+* after the template document is resolved.
+*
+* Returning the flags is what keeps `requestFlags` a SINGLE read: care's hook
+* loads the theme-settings document to answer "are card swatches on?", and its
+* route fetches need the same answer — the caller parks this value on the
+* template rather than deriving it a second time. */
+async function runEnrichment(cfg, template, adapter, opts = {}) {
+	const req = {
+		locale: opts.locale,
+		sid: opts.sid,
+		product: opts.product ?? null,
+		collection: opts.collection ?? null,
+		page: opts.page ?? null,
+		blog: opts.blog ?? null,
+		article: opts.article ?? null,
+		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 resolverCtx = await buildResolverCtx(cfg, template);
+	const specCtx = {
+		req,
+		adapter,
+		disabledAncestors: resolverCtx.disabledAncestors
+	};
+	await Promise.all([
+		...standardSpecs(specCtx).map((spec) => resolveField(template, spec, resolverCtx)),
+		resolveReviewLists(template, resolverCtx, specCtx),
+		...(adapter.customPasses ?? []).map((pass) => pass(sections, req))
+	]);
+	await adapter.postPickers?.(sections, req);
+	applyInlineSourceTokens(template, req, metaobjectFields);
+	return req.flags;
+}
+//#endregion
+export { buildResolverCtx, flattenSections, runEnrichment };

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+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 { EnrichOptions, buildResolverCtx, flattenSections, runEnrichment } from "./enrich.js";
+import { buildOrchestratorUrl, fetchPreviewSettings, fetchPreviewTemplate, previewEnabled } from "./orchestrator.js";
+import { loadRawThemeSettings, loadTemplateForRequest, resolveTemplateVariant } from "./template-request.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 };

package/dist/index.js

@@ -0,0 +1,11 @@
+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 { loadRawThemeSettings, loadTemplateForRequest, resolveTemplateVariant } from "./template-request.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 };

package/dist/orchestrator.d.ts

@@ -0,0 +1,8 @@
+import { LoadedTemplate, ThemeLoaderConfig } from "./types.js";
+//#region src/orchestrator.d.ts
+export declare function buildOrchestratorUrl(cfg: ThemeLoaderConfig, endpoint: string, query: Record<string, string>): string;
+/** True when the preview endpoints are addressable at all. */
+export declare function previewEnabled(cfg: ThemeLoaderConfig, sid: string | undefined): sid is string;
+export declare function fetchPreviewTemplate(cfg: ThemeLoaderConfig, sid: string, templateId: string): Promise<LoadedTemplate | null>;
+export declare function fetchPreviewSettings(cfg: ThemeLoaderConfig, sid: string): Promise<Record<string, unknown> | null>;
+//#endregion

package/dist/orchestrator.js

@@ -0,0 +1,35 @@
+//#region src/orchestrator.ts
+function buildOrchestratorUrl(cfg, endpoint, query) {
+	const url = new URL(`${cfg.orchestratorUrl}/api/stores/${cfg.storeSlug}/${cfg.installId}/${endpoint}`);
+	for (const [k, v] of Object.entries(query)) url.searchParams.set(k, v);
+	return url.toString();
+}
+/** True when the preview endpoints are addressable at all. */
+function previewEnabled(cfg, sid) {
+	return Boolean(sid && cfg.storeSlug && cfg.installId);
+}
+async function fetchPreviewTemplate(cfg, sid, templateId) {
+	try {
+		const res = await fetch(buildOrchestratorUrl(cfg, "template", {
+			sid,
+			templateId
+		}));
+		if (!res.ok) return null;
+		return await res.json();
+	} catch (err) {
+		console.warn("[fetchPreviewTemplate] failed:", err);
+		return null;
+	}
+}
+async function fetchPreviewSettings(cfg, sid) {
+	try {
+		const res = await fetch(buildOrchestratorUrl(cfg, "settings", { sid }));
+		if (!res.ok) return null;
+		return await res.json();
+	} catch (err) {
+		console.warn("[fetchPreviewSettings] failed:", err);
+		return null;
+	}
+}
+//#endregion
+export { buildOrchestratorUrl, fetchPreviewSettings, fetchPreviewTemplate, previewEnabled };

package/dist/section-preview.d.ts

@@ -0,0 +1,19 @@
+import { ThemeLoaderConfig } from "./types.js";
+//#region src/section-preview.d.ts
+export interface SectionPreviewInput {
+  type?: string;
+  preset?: number;
+  block?: string;
+}
+export interface SectionPreviewOptions {
+  /** Block type → the section type it previews inside, so a block renders with
+   * a real host section's chrome and context. A block with no host entry is not
+   * previewable. */
+  hosts: Record<string, string>;
+  /** Preview-only settings for blocks that would otherwise render blank on
+   * schema defaults. Merged onto the seeded preview instance only — never onto
+   * real merchant defaults. */
+  seedSettings?: Record<string, Record<string, unknown>>;
+}
+export declare function buildSectionPreviewTemplate(cfg: ThemeLoaderConfig, { type, preset, block }: SectionPreviewInput, { hosts, seedSettings }: SectionPreviewOptions): Promise<any>;
+//#endregion