@shop-on/theme-contract 0.3.0 → 0.5.0

package/dist/document.d.ts

@@ -21,6 +21,19 @@ export interface CollectedTypes {
   layouts: Set<string>;
 }
 export declare function defaultSettings(schemaDefs?: SchemaSetting[]): Record<string, unknown>;
+/** The `blocks` entry a section or block schema lists to accept app blocks
+ * (Shopify's `{ "type": "@app" }`). Honoured on a section, and on a block that
+ * is a direct child of a section, so an app block is never deeper than
+ * depth 2. */
+export declare const APP_BLOCK_WILDCARD = "@app";
+/** The most block ancestors an app block's container may have: 0 for a
+ * section, 1 for a block directly in a section. */
+export declare const MAX_APP_BLOCK_CONTAINER_DEPTH = 1;
+export declare function acceptsAppBlocks(schema: {
+  blocks?: {
+    type: string;
+  }[];
+}): boolean;
 export declare function staticChildId(childType: string, parentType: string): string;
 export declare function staticBlockId(type: string): string;
 export declare function buildStaticChildren(args: {

package/dist/document.js

@@ -4,6 +4,17 @@ function defaultSettings(schemaDefs) {
 	for (const st of schemaDefs ?? []) if (st.id && st.default != null) out[st.id] = st.default;
 	return out;
 }
+/** The `blocks` entry a section or block schema lists to accept app blocks
+* (Shopify's `{ "type": "@app" }`). Honoured on a section, and on a block that
+* is a direct child of a section, so an app block is never deeper than
+* depth 2. */
+const APP_BLOCK_WILDCARD = "@app";
+/** The most block ancestors an app block's container may have: 0 for a
+* section, 1 for a block directly in a section. */
+const MAX_APP_BLOCK_CONTAINER_DEPTH = 1;
+function acceptsAppBlocks(schema) {
+	return schema.blocks?.some((b) => b.type === "@app") ?? false;
+}
 function staticChildId(childType, parentType) {
 	const cleanChild = childType.replace(/^_/, "");
 	const cleanParent = parentType.replace(/^_/, "");
@@ -17,7 +28,7 @@ function buildStaticChildren(args) {
 	const blocks = {};
 	const block_order = [];
 	for (const childDef of args.childDefs) {
-		if (!childDef.static) continue;
+		if (!childDef.static || childDef.type === "@app") continue;
 		const childSchema = lookupSchema(args.getBlockSchema, childDef.type);
 		const id = staticChildId(childDef.type, args.parentType);
 		const block = {
@@ -92,6 +103,7 @@ function buildPresetBlock(blockDef, getBlockSchema, idFor, parentType) {
 		block_order.push(...statics.block_order);
 	}
 	for (const childDef of blockDef.blocks ?? []) {
+		if (childDef.type === "@app") continue;
 		const child = buildPresetBlock(childDef, getBlockSchema, idFor, blockDef.type);
 		blocks[child.id] = child.block;
 		if (!child.isStatic) block_order.push(child.id);
@@ -140,6 +152,7 @@ function buildSectionInstance(args) {
 	const block_order = [];
 	const blockDefs = preset?.blocks ?? sectionSchema?.blocks ?? [];
 	for (const blockDef of blockDefs) {
+		if (blockDef.type === "@app") continue;
 		const built = buildPresetBlock(blockDef, getBlockSchema, idFor);
 		blocks[built.id] = built.block;
 		if (!built.isStatic) block_order.push(built.id);
@@ -157,11 +170,11 @@ function buildSectionInstance(args) {
 function selectRenderableSections(sections, order) {
 	const out = [];
 	for (const instanceId of order) {
-		const section = sections[instanceId];
+		const section = Object.hasOwn(sections, instanceId) ? sections[instanceId] : void 0;
 		if (!section || section.disabled) continue;
 		const blocks = [];
 		for (const blockId of section.block_order ?? []) {
-			const raw = section.blocks?.[blockId];
+			const raw = section.blocks && Object.hasOwn(section.blocks, blockId) ? section.blocks[blockId] : void 0;
 			if (!raw || raw.disabled) continue;
 			blocks.push({
 				...raw,
@@ -197,7 +210,7 @@ function selectRenderableChildren(block) {
 	}
 	for (const id of block.block_order ?? []) {
 		if (seen.has(id)) continue;
-		const child = block.blocks?.[id];
+		const child = block.blocks && Object.hasOwn(block.blocks, id) ? block.blocks[id] : void 0;
 		if (!child || child.disabled) continue;
 		out.push({
 			...child,
@@ -212,6 +225,7 @@ function collectTypes(template) {
 	const layouts = /* @__PURE__ */ new Set();
 	layouts.add(template.layout ?? "main");
 	const walkBlock = (block) => {
+		if (block.source === "app") return;
 		blocks.add(block.type);
 		if (block.blocks) for (const child of Object.values(block.blocks)) walkBlock(child);
 	};
@@ -294,4 +308,4 @@ function deepClone(value) {
 	return JSON.parse(JSON.stringify(value));
 }
 //#endregion
-export { buildBlockInstance, buildSectionInstance, buildStaticChildren, collectTypes, defaultSettings, seedMissingStatics, selectRenderableChildren, selectRenderableSections, staticBlockId, staticChildId, stripStaticFromBlockOrder };
+export { APP_BLOCK_WILDCARD, MAX_APP_BLOCK_CONTAINER_DEPTH, acceptsAppBlocks, buildBlockInstance, buildSectionInstance, buildStaticChildren, collectTypes, defaultSettings, seedMissingStatics, selectRenderableChildren, selectRenderableSections, staticBlockId, staticChildId, stripStaticFromBlockOrder };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { BlockDefinition, BlockSchema, LayoutGroupDef, SchemaSetting, SectionGroup, SectionGroupData, SectionPreset, SectionSchema, SettingBinding, SettingBindings, SettingValue, SettingsData, SettingsSchema, SettingsSchemaSection, Template, TemplateBlock, TemplateSection } from "./schemas.js";
 import { BLOCK_PATH_SEPARATOR, blockPathsEqual, isBlockPathPrefix, joinBlockPath, normalizeBlockPath, resolveContainerAtPath, splitBlockPath } from "./block-path.js";
 import { EDITOR_COMMANDS, EditorCommand, EditorKeyInput, editorCommand, isEditorCommand, shortcutKey, undoHotkey } from "./editor-keys.js";
-import { CollectedTypes, SeedMissingStaticsReport, SelectedSection, TemplateShape, buildBlockInstance, buildSectionInstance, buildStaticChildren, collectTypes, defaultSettings, seedMissingStatics, selectRenderableChildren, selectRenderableSections, staticBlockId, staticChildId, stripStaticFromBlockOrder } from "./document.js";
+import { APP_BLOCK_WILDCARD, CollectedTypes, MAX_APP_BLOCK_CONTAINER_DEPTH, SeedMissingStaticsReport, SelectedSection, TemplateShape, acceptsAppBlocks, buildBlockInstance, buildSectionInstance, buildStaticChildren, collectTypes, defaultSettings, seedMissingStatics, selectRenderableChildren, selectRenderableSections, staticBlockId, staticChildId, stripStaticFromBlockOrder } from "./document.js";
 import { MAX_PALETTE_COLORS, MIN_PALETTE_COLORS, PALETTE_FALLBACK_COLOR, PALETTE_GROUP_TYPE, PALETTE_PREFIX, PALETTE_REF_PREFIX, PaletteColor, comparePaletteIds, hasPaletteRefs, paletteKey, paletteRef, paletteValues, parsePalette, parsePaletteRef, resolvePaletteRefs, resolvePaletteValue, resolveThemeSettingsPalette } from "./color-palette.js";
 import { FieldSource, ResolverCtx, ResolverScope, ResolverShape, ResolverSpec, SKIP, Skip, buildDisabledAncestorSet, buildParentMap, resolveField, walkBlocks, walkSections } from "./resolvers.js";
 import { ARTICLE_ATTRIBUTE_KEYS, ArticleAttributeKey, BLOG_ATTRIBUTE_KEYS, BlogAttributeKey, COLLECTION_ATTRIBUTE_KEYS, COLLECTION_INLINE_ATTRIBUTE_KEYS, CollectionAttributeBindingSources, CollectionAttributeKey, CollectionInlineAttributeKey, InlineSegment, InlineSources, PAGE_ATTRIBUTE_KEYS, PRODUCT_ATTRIBUTE_KEYS, PageAttributeKey, ProductAttributeKey, WholeValueBindingOpts, applyCollectionAttributeBindings, applyInlineSources, applyMetafieldBindings, applyMetaobjectFieldBindings, collectCollectionAttributeBindings, collectMetaobjectEntryIds, collectTraversedEntryIds, decodeStorefrontMetafield, encodeSourceToken, escapeInertHtmlText, metafieldDefinitionFitsSetting, metafieldTypeSupportsInlineToken, metafieldTypeToSettingTypes, parseSourceDescriptor, serializeSourceDescriptor, settingTypeSupportsBinding, splitInlineTokens, stripInlineTokenSentinels } from "./metafield-binding.js";
@@ -9,4 +9,4 @@ import { metaobjectGid, metaobjectIdFromGid } from "./metaobject-gid.js";
 import { RICHTEXT_ALLOWED_TAGS, RichtextTag } from "./richtext.js";
 import { isNodeIdToken, nodeGid } from "./node-id.js";
 import { INSTALL_ID_RE, STORE_SLUG_RE } from "./store-path.js";
-export { ARTICLE_ATTRIBUTE_KEYS, ArticleAttributeKey, BLOCK_PATH_SEPARATOR, BLOG_ATTRIBUTE_KEYS, BlockDefinition, BlockSchema, BlogAttributeKey, COLLECTION_ATTRIBUTE_KEYS, COLLECTION_INLINE_ATTRIBUTE_KEYS, CollectedTypes, CollectionAttributeBindingSources, CollectionAttributeKey, CollectionInlineAttributeKey, EDITOR_COMMANDS, EditorCommand, EditorKeyInput, FieldSource, INSTALL_ID_RE, InlineSegment, InlineSources, LayoutGroupDef, MAX_PALETTE_COLORS, MIN_PALETTE_COLORS, PAGE_ATTRIBUTE_KEYS, PALETTE_FALLBACK_COLOR, PALETTE_GROUP_TYPE, PALETTE_PREFIX, PALETTE_REF_PREFIX, PRODUCT_ATTRIBUTE_KEYS, PageAttributeKey, PaletteColor, ProductAttributeKey, RICHTEXT_ALLOWED_TAGS, ResolverCtx, ResolverScope, ResolverShape, ResolverSpec, RichtextTag, SKIP, STORE_SLUG_RE, SchemaSetting, SectionGroup, SectionGroupData, SectionPreset, SectionSchema, SeedMissingStaticsReport, SelectedSection, SettingBinding, SettingBindings, SettingValue, SettingsData, SettingsSchema, SettingsSchemaSection, Skip, Template, TemplateBlock, TemplateSection, TemplateShape, WholeValueBindingOpts, applyCollectionAttributeBindings, applyInlineSources, applyMetafieldBindings, applyMetaobjectFieldBindings, blockPathsEqual, buildBlockInstance, buildDisabledAncestorSet, buildParentMap, buildSectionInstance, buildStaticChildren, collectCollectionAttributeBindings, collectMetaobjectEntryIds, collectTraversedEntryIds, collectTypes, comparePaletteIds, decodeStorefrontMetafield, defaultSettings, editorCommand, encodeSourceToken, escapeInertHtmlText, hasPaletteRefs, isBlockPathPrefix, isEditorCommand, isNodeIdToken, joinBlockPath, metafieldDefinitionFitsSetting, metafieldTypeSupportsInlineToken, metafieldTypeToSettingTypes, metaobjectGid, metaobjectIdFromGid, nodeGid, normalizeBlockPath, paletteKey, paletteRef, paletteValues, parsePalette, parsePaletteRef, parseSourceDescriptor, resolveContainerAtPath, resolveField, resolvePaletteRefs, resolvePaletteValue, resolveThemeSettingsPalette, seedMissingStatics, selectRenderableChildren, selectRenderableSections, serializeSourceDescriptor, settingTypeSupportsBinding, shortcutKey, splitBlockPath, splitInlineTokens, staticBlockId, staticChildId, stripInlineTokenSentinels, stripStaticFromBlockOrder, undoHotkey, walkBlocks, walkSections };
+export { APP_BLOCK_WILDCARD, ARTICLE_ATTRIBUTE_KEYS, ArticleAttributeKey, BLOCK_PATH_SEPARATOR, BLOG_ATTRIBUTE_KEYS, BlockDefinition, BlockSchema, BlogAttributeKey, COLLECTION_ATTRIBUTE_KEYS, COLLECTION_INLINE_ATTRIBUTE_KEYS, CollectedTypes, CollectionAttributeBindingSources, CollectionAttributeKey, CollectionInlineAttributeKey, EDITOR_COMMANDS, EditorCommand, EditorKeyInput, FieldSource, INSTALL_ID_RE, InlineSegment, InlineSources, LayoutGroupDef, MAX_APP_BLOCK_CONTAINER_DEPTH, MAX_PALETTE_COLORS, MIN_PALETTE_COLORS, PAGE_ATTRIBUTE_KEYS, PALETTE_FALLBACK_COLOR, PALETTE_GROUP_TYPE, PALETTE_PREFIX, PALETTE_REF_PREFIX, PRODUCT_ATTRIBUTE_KEYS, PageAttributeKey, PaletteColor, ProductAttributeKey, RICHTEXT_ALLOWED_TAGS, ResolverCtx, ResolverScope, ResolverShape, ResolverSpec, RichtextTag, SKIP, STORE_SLUG_RE, SchemaSetting, SectionGroup, SectionGroupData, SectionPreset, SectionSchema, SeedMissingStaticsReport, SelectedSection, SettingBinding, SettingBindings, SettingValue, SettingsData, SettingsSchema, SettingsSchemaSection, Skip, Template, TemplateBlock, TemplateSection, TemplateShape, WholeValueBindingOpts, acceptsAppBlocks, applyCollectionAttributeBindings, applyInlineSources, applyMetafieldBindings, applyMetaobjectFieldBindings, blockPathsEqual, buildBlockInstance, buildDisabledAncestorSet, buildParentMap, buildSectionInstance, buildStaticChildren, collectCollectionAttributeBindings, collectMetaobjectEntryIds, collectTraversedEntryIds, collectTypes, comparePaletteIds, decodeStorefrontMetafield, defaultSettings, editorCommand, encodeSourceToken, escapeInertHtmlText, hasPaletteRefs, isBlockPathPrefix, isEditorCommand, isNodeIdToken, joinBlockPath, metafieldDefinitionFitsSetting, metafieldTypeSupportsInlineToken, metafieldTypeToSettingTypes, metaobjectGid, metaobjectIdFromGid, nodeGid, normalizeBlockPath, paletteKey, paletteRef, paletteValues, parsePalette, parsePaletteRef, parseSourceDescriptor, resolveContainerAtPath, resolveField, resolvePaletteRefs, resolvePaletteValue, resolveThemeSettingsPalette, seedMissingStatics, selectRenderableChildren, selectRenderableSections, serializeSourceDescriptor, settingTypeSupportsBinding, shortcutKey, splitBlockPath, splitInlineTokens, staticBlockId, staticChildId, stripInlineTokenSentinels, stripStaticFromBlockOrder, undoHotkey, walkBlocks, walkSections };

package/dist/index.js

@@ -1,7 +1,7 @@
 import { BlockDefinition, BlockSchema, SchemaSetting, SectionGroup, SectionPreset, SectionSchema, SettingBinding, SettingBindings, SettingsData, SettingsSchema, SettingsSchemaSection, Template, TemplateBlock, TemplateSection } from "./schemas.js";
 import { BLOCK_PATH_SEPARATOR, blockPathsEqual, isBlockPathPrefix, joinBlockPath, normalizeBlockPath, resolveContainerAtPath, splitBlockPath } from "./block-path.js";
 import { EDITOR_COMMANDS, editorCommand, isEditorCommand, shortcutKey, undoHotkey } from "./editor-keys.js";
-import { buildBlockInstance, buildSectionInstance, buildStaticChildren, collectTypes, defaultSettings, seedMissingStatics, selectRenderableChildren, selectRenderableSections, staticBlockId, staticChildId, stripStaticFromBlockOrder } from "./document.js";
+import { APP_BLOCK_WILDCARD, MAX_APP_BLOCK_CONTAINER_DEPTH, acceptsAppBlocks, buildBlockInstance, buildSectionInstance, buildStaticChildren, collectTypes, defaultSettings, seedMissingStatics, selectRenderableChildren, selectRenderableSections, staticBlockId, staticChildId, stripStaticFromBlockOrder } from "./document.js";
 import { MAX_PALETTE_COLORS, MIN_PALETTE_COLORS, PALETTE_FALLBACK_COLOR, PALETTE_GROUP_TYPE, PALETTE_PREFIX, PALETTE_REF_PREFIX, comparePaletteIds, hasPaletteRefs, paletteKey, paletteRef, paletteValues, parsePalette, parsePaletteRef, resolvePaletteRefs, resolvePaletteValue, resolveThemeSettingsPalette } from "./color-palette.js";
 import { SKIP, buildDisabledAncestorSet, buildParentMap, resolveField, walkBlocks, walkSections } from "./resolvers.js";
 import { metaobjectGid, metaobjectIdFromGid } from "./metaobject-gid.js";
@@ -9,4 +9,4 @@ import { ARTICLE_ATTRIBUTE_KEYS, BLOG_ATTRIBUTE_KEYS, COLLECTION_ATTRIBUTE_KEYS,
 import { RICHTEXT_ALLOWED_TAGS } from "./richtext.js";
 import { isNodeIdToken, nodeGid } from "./node-id.js";
 import { INSTALL_ID_RE, STORE_SLUG_RE } from "./store-path.js";
-export { ARTICLE_ATTRIBUTE_KEYS, BLOCK_PATH_SEPARATOR, BLOG_ATTRIBUTE_KEYS, BlockDefinition, BlockSchema, COLLECTION_ATTRIBUTE_KEYS, COLLECTION_INLINE_ATTRIBUTE_KEYS, EDITOR_COMMANDS, INSTALL_ID_RE, MAX_PALETTE_COLORS, MIN_PALETTE_COLORS, PAGE_ATTRIBUTE_KEYS, PALETTE_FALLBACK_COLOR, PALETTE_GROUP_TYPE, PALETTE_PREFIX, PALETTE_REF_PREFIX, PRODUCT_ATTRIBUTE_KEYS, RICHTEXT_ALLOWED_TAGS, SKIP, STORE_SLUG_RE, SchemaSetting, SectionGroup, SectionPreset, SectionSchema, SettingBinding, SettingBindings, SettingsData, SettingsSchema, SettingsSchemaSection, Template, TemplateBlock, TemplateSection, applyCollectionAttributeBindings, applyInlineSources, applyMetafieldBindings, applyMetaobjectFieldBindings, blockPathsEqual, buildBlockInstance, buildDisabledAncestorSet, buildParentMap, buildSectionInstance, buildStaticChildren, collectCollectionAttributeBindings, collectMetaobjectEntryIds, collectTraversedEntryIds, collectTypes, comparePaletteIds, decodeStorefrontMetafield, defaultSettings, editorCommand, encodeSourceToken, escapeInertHtmlText, hasPaletteRefs, isBlockPathPrefix, isEditorCommand, isNodeIdToken, joinBlockPath, metafieldDefinitionFitsSetting, metafieldTypeSupportsInlineToken, metafieldTypeToSettingTypes, metaobjectGid, metaobjectIdFromGid, nodeGid, normalizeBlockPath, paletteKey, paletteRef, paletteValues, parsePalette, parsePaletteRef, parseSourceDescriptor, resolveContainerAtPath, resolveField, resolvePaletteRefs, resolvePaletteValue, resolveThemeSettingsPalette, seedMissingStatics, selectRenderableChildren, selectRenderableSections, serializeSourceDescriptor, settingTypeSupportsBinding, shortcutKey, splitBlockPath, splitInlineTokens, staticBlockId, staticChildId, stripInlineTokenSentinels, stripStaticFromBlockOrder, undoHotkey, walkBlocks, walkSections };
+export { APP_BLOCK_WILDCARD, ARTICLE_ATTRIBUTE_KEYS, BLOCK_PATH_SEPARATOR, BLOG_ATTRIBUTE_KEYS, BlockDefinition, BlockSchema, COLLECTION_ATTRIBUTE_KEYS, COLLECTION_INLINE_ATTRIBUTE_KEYS, EDITOR_COMMANDS, INSTALL_ID_RE, MAX_APP_BLOCK_CONTAINER_DEPTH, MAX_PALETTE_COLORS, MIN_PALETTE_COLORS, PAGE_ATTRIBUTE_KEYS, PALETTE_FALLBACK_COLOR, PALETTE_GROUP_TYPE, PALETTE_PREFIX, PALETTE_REF_PREFIX, PRODUCT_ATTRIBUTE_KEYS, RICHTEXT_ALLOWED_TAGS, SKIP, STORE_SLUG_RE, SchemaSetting, SectionGroup, SectionPreset, SectionSchema, SettingBinding, SettingBindings, SettingsData, SettingsSchema, SettingsSchemaSection, Template, TemplateBlock, TemplateSection, acceptsAppBlocks, applyCollectionAttributeBindings, applyInlineSources, applyMetafieldBindings, applyMetaobjectFieldBindings, blockPathsEqual, buildBlockInstance, buildDisabledAncestorSet, buildParentMap, buildSectionInstance, buildStaticChildren, collectCollectionAttributeBindings, collectMetaobjectEntryIds, collectTraversedEntryIds, collectTypes, comparePaletteIds, decodeStorefrontMetafield, defaultSettings, editorCommand, encodeSourceToken, escapeInertHtmlText, hasPaletteRefs, isBlockPathPrefix, isEditorCommand, isNodeIdToken, joinBlockPath, metafieldDefinitionFitsSetting, metafieldTypeSupportsInlineToken, metafieldTypeToSettingTypes, metaobjectGid, metaobjectIdFromGid, nodeGid, normalizeBlockPath, paletteKey, paletteRef, paletteValues, parsePalette, parsePaletteRef, parseSourceDescriptor, resolveContainerAtPath, resolveField, resolvePaletteRefs, resolvePaletteValue, resolveThemeSettingsPalette, seedMissingStatics, selectRenderableChildren, selectRenderableSections, serializeSourceDescriptor, settingTypeSupportsBinding, shortcutKey, splitBlockPath, splitInlineTokens, staticBlockId, staticChildId, stripInlineTokenSentinels, stripStaticFromBlockOrder, undoHotkey, walkBlocks, walkSections };

package/dist/preset-materializer.d.ts

@@ -0,0 +1,9 @@
+//#region src/preset-materializer.d.ts
+export declare function materializePreset(opts: {
+  configDir: string;
+  presetHandle: string;
+}): Promise<void>;
+/** Deep-merges each of a listing's overridable dirs over `configDir`'s copy;
+ * a file only the listing has lands as is. Leaves settings-data alone. */
+export declare function overlayPresetListing(listingDir: string, configDir: string): Promise<void>;
+//#endregion

package/dist/preset-materializer.js

@@ -0,0 +1,70 @@
+import { LISTING_DIRS, PRESET_HANDLE_RE, mergePresetJson, normalizePresetKey } from "./preset-listing.js";
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+//#region src/preset-materializer.ts
+function isPlainObject(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+async function readJson(filePath) {
+	try {
+		return JSON.parse(await readFile(filePath, "utf-8"));
+	} catch (err) {
+		if (err instanceof Error && err.code === "ENOENT") return null;
+		throw err;
+	}
+}
+async function dirExists(dir) {
+	try {
+		return (await stat(dir)).isDirectory();
+	} catch {
+		return false;
+	}
+}
+async function materializeJsonOverrides(sourceDir, targetDir) {
+	if (!await dirExists(sourceDir)) return;
+	await mkdir(targetDir, { recursive: true });
+	const entries = await readdir(sourceDir, { withFileTypes: true });
+	for (const entry of entries) {
+		const sourcePath = path.join(sourceDir, entry.name);
+		const targetPath = path.join(targetDir, entry.name);
+		if (entry.isDirectory()) {
+			await materializeJsonOverrides(sourcePath, targetPath);
+			continue;
+		}
+		if (!entry.isFile() || !entry.name.endsWith(".json") || entry.name.startsWith("._")) continue;
+		const override = await readJson(sourcePath);
+		if (override === null) continue;
+		const base = await readJson(targetPath);
+		const output = base === null ? override : mergePresetJson(base, override);
+		await writeFile(targetPath, `${JSON.stringify(output, null, 2)}\n`, "utf-8");
+	}
+}
+async function flattenSettingsData(configDir, presetHandle) {
+	const settingsPath = path.join(configDir, "settings-data.json");
+	const data = await readJson(settingsPath);
+	if (!isPlainObject(data)) return;
+	const presets = data.presets;
+	if (!isPlainObject(presets)) return;
+	const currentPreset = isPlainObject(data.current) ? data.current.preset : null;
+	const keys = Object.keys(presets);
+	const selectedKey = keys.find((key) => key === presetHandle) ?? keys.find((key) => normalizePresetKey(key) === presetHandle) ?? (typeof currentPreset === "string" && normalizePresetKey(currentPreset) === presetHandle ? currentPreset : null);
+	if (!selectedKey) throw new Error(`settings-data.json does not contain selected preset "${presetHandle}" in presets wrapper`);
+	const selected = presets[selectedKey];
+	if (!isPlainObject(selected) || !isPlainObject(selected.settings)) throw new Error(`settings-data.json preset "${selectedKey}" is missing a settings object`);
+	await writeFile(settingsPath, `${JSON.stringify(selected.settings, null, 2)}\n`, "utf-8");
+}
+async function materializePreset(opts) {
+	const presetHandle = opts.presetHandle.trim();
+	if (!PRESET_HANDLE_RE.test(presetHandle)) throw new Error(`invalid preset handle "${opts.presetHandle}"`);
+	const listingDir = path.join(opts.configDir, "listings", presetHandle);
+	if (!await dirExists(listingDir)) throw new Error(`selected preset "${presetHandle}" not found at config/listings/${presetHandle}`);
+	await flattenSettingsData(opts.configDir, presetHandle);
+	await overlayPresetListing(listingDir, opts.configDir);
+}
+/** Deep-merges each of a listing's overridable dirs over `configDir`'s copy;
+* a file only the listing has lands as is. Leaves settings-data alone. */
+async function overlayPresetListing(listingDir, configDir) {
+	for (const dir of LISTING_DIRS) await materializeJsonOverrides(path.join(listingDir, dir), path.join(configDir, dir));
+}
+//#endregion
+export { materializePreset, overlayPresetListing };

package/dist/schemas.d.ts

@@ -283,6 +283,10 @@ export type TemplateBlock = {
   custom_css?: string;
   blocks?: Record<string, TemplateBlock>;
   block_order?: string[];
+  source?: "app";
+  appId?: string;
+  tag?: string;
+  scriptUrl?: string;
 };
 export declare const TemplateBlock: z.ZodType<TemplateBlock>;
 export declare const TemplateSection: z.ZodObject<{

package/dist/schemas.js

@@ -115,7 +115,11 @@ const TemplateBlock = z.lazy(() => z.object({
 	customName: z.string().optional(),
 	custom_css: z.string().optional(),
 	blocks: z.record(z.string(), TemplateBlock).optional(),
-	block_order: z.array(z.string()).optional()
+	block_order: z.array(z.string()).optional(),
+	source: z.literal("app").optional(),
+	appId: z.string().optional(),
+	tag: z.string().optional(),
+	scriptUrl: z.string().optional()
 }).passthrough());
 const TemplateSection = z.object({
 	type: z.string(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shop-on/theme-contract",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "license": "SEE LICENSE IN dist/LICENSE.md",
   "files": [
     "dist"
@@ -10,12 +10,14 @@
   "exports": {
     ".": "./dist/index.js",
     "./preset-listing": "./dist/preset-listing.js",
+    "./preset-materializer": "./dist/preset-materializer.js",
     "./package.json": "./package.json"
   },
   "dependencies": {
     "zod": "4.6.7"
   },
   "devDependencies": {
+    "@types/node": "26.6.5",
     "typescript": "7.0.2",
     "vitest": "5.0.5"
   },