@shop-on/theme-contract 0.4.0 → 0.6.0

package/dist/ai-files.d.ts

@@ -0,0 +1,18 @@
+import { AiEntry, LoadedRecipe } from "./editor-tools/recipes.js";
+//#region src/ai-files.d.ts
+/** Every entry `aiManifest` judges: the top level, and `recipes/` when it is
+ *  a directory. Nothing deeper is listed: a subdir is refused as itself. */
+export declare function listAiDir(dir: string): Promise<AiEntry[]>;
+export interface ThemeAiFiles {
+  guide: string;
+  recipes: LoadedRecipe[];
+  /** Every path left out, and why: refused by the rule, or a recipe that didn't parse. */
+  skipped: {
+    path: string;
+    reason: string;
+  }[];
+  /** The bytes read, guide and recipes. */
+  bytes: number;
+}
+export declare function readThemeAiDir(dir: string): Promise<ThemeAiFiles>;
+//#endregion

package/dist/ai-files.js

@@ -0,0 +1,47 @@
+import { aiManifest, loadRecipes } from "./editor-tools/recipes.js";
+import { readFile, readdir, stat } from "node:fs/promises";
+import path from "node:path";
+//#region src/ai-files.ts
+async function entriesOf(dir, prefix) {
+	const dirents = await readdir(dir, { withFileTypes: true }).catch((err) => {
+		if (err.code === "ENOENT") return [];
+		throw err;
+	});
+	const entries = [];
+	for (const d of dirents) {
+		const rel = prefix + d.name;
+		const kind = d.isFile() ? "file" : d.isDirectory() ? "dir" : "other";
+		const bytes = kind === "file" ? (await stat(path.join(dir, d.name))).size : 0;
+		entries.push({
+			path: rel,
+			kind,
+			bytes
+		});
+	}
+	return entries;
+}
+/** Every entry `aiManifest` judges: the top level, and `recipes/` when it is
+*  a directory. Nothing deeper is listed: a subdir is refused as itself. */
+async function listAiDir(dir) {
+	const top = await entriesOf(dir, "");
+	const recipes = top.some((e) => e.path === "recipes" && e.kind === "dir") ? await entriesOf(path.join(dir, "recipes"), "recipes/") : [];
+	return [...top, ...recipes];
+}
+async function readThemeAiDir(dir) {
+	const manifest = aiManifest(await listAiDir(dir));
+	const read = (rel) => readFile(path.join(dir, rel), "utf-8");
+	const [guide, bodies] = await Promise.all([manifest.guide ? read(manifest.guide.path) : "", Promise.all(manifest.recipes.map((e) => read(e.path)))]);
+	const files = Object.fromEntries(manifest.recipes.map((e, i) => [e.path.slice(8), bodies[i]]));
+	const loaded = loadRecipes(files);
+	return {
+		guide,
+		recipes: loaded.recipes,
+		skipped: [...manifest.refused, ...loaded.skipped.map(({ name, reason }) => ({
+			path: `recipes/${name}`,
+			reason: `recipes/${reason}`
+		}))],
+		bytes: Buffer.byteLength(guide) + bodies.reduce((n, b) => n + Buffer.byteLength(b), 0)
+	};
+}
+//#endregion
+export { listAiDir, readThemeAiDir };

package/dist/block-allowlist.d.ts

@@ -0,0 +1,27 @@
+//#region src/block-allowlist.d.ts
+type ContainerSchema = {
+  blocks?: {
+    type: string;
+    static?: boolean;
+  }[];
+} | undefined;
+/**
+ * The block types that may be inserted into a container: its schema's
+ * non-static `blocks`, without the `@app` wildcard. A container that lists
+ * `@app` at `depth` 0 (a section) or 1 (a block directly in a section) also
+ * takes every installed app block (the editor-loader serves those as
+ * `source:"app"` block schemas); deeper, `@app` means nothing, as publish lets
+ * no app block stand there.
+ *
+ * Every insert path (picker, paste, AI, the editor tools) goes through this,
+ * so none can offer a type publish would drop or the storefront would fail to
+ * render.
+ */
+export declare function allowedChildBlockTypes(containerSchema: ContainerSchema, blockSchemas: readonly {
+  type?: string;
+  source?: "app";
+}[], { depth }: {
+  depth: number;
+}): string[];
+//#endregion
+export {};

package/dist/block-allowlist.js

@@ -0,0 +1,21 @@
+import { acceptsAppBlocks } from "./document.js";
+//#region src/block-allowlist.ts
+/**
+* The block types that may be inserted into a container: its schema's
+* non-static `blocks`, without the `@app` wildcard. A container that lists
+* `@app` at `depth` 0 (a section) or 1 (a block directly in a section) also
+* takes every installed app block (the editor-loader serves those as
+* `source:"app"` block schemas); deeper, `@app` means nothing, as publish lets
+* no app block stand there.
+*
+* Every insert path (picker, paste, AI, the editor tools) goes through this,
+* so none can offer a type publish would drop or the storefront would fail to
+* render.
+*/
+function allowedChildBlockTypes(containerSchema, blockSchemas, { depth }) {
+	const types = (containerSchema?.blocks ?? []).filter((b) => !b.static && b.type !== "@app").map((b) => b.type);
+	if (depth > 1 || !containerSchema || !acceptsAppBlocks(containerSchema)) return types;
+	return [...types, ...blockSchemas.flatMap((b) => b.source === "app" && b.type ? [b.type] : [])];
+}
+//#endregion
+export { allowedChildBlockTypes };

package/dist/closest-scope.d.ts

@@ -0,0 +1,51 @@
+import { ClosestResource, Provides } from "./schemas.js";
+//#region src/closest-scope.d.ts
+/** A node's providers: single ones inferred from its pickers, list ones
+ * declared under `provides`. `each` absent ⇒ single. */
+export type Providers = Partial<Record<ClosestResource, {
+  from: string;
+  each?: readonly string[];
+}>>;
+/** One link of a root-first node chain: the node's providers and the id it
+ * hangs under in its parent (a section's instance id, a block's id). The
+ * root link stands for the route — its providers name the route resources
+ * the page has — and its key is never read. */
+export interface ScopeLink {
+  providers: Providers;
+  key: string;
+}
+export interface ClosestScope {
+  /** Index into the chain of the providing link; 0 is the route. */
+  index: number;
+  decl: {
+    from: string;
+    each?: readonly string[];
+  };
+}
+export declare const PICKER_RESOURCES: Readonly<Record<string, ClosestResource>>;
+/** The resources a schema provides: the FIRST picker of each resource type in
+ * schema order (Shopify's rule — `closest.product` is the nearest `product`
+ * setting), overridden per resource by an explicit `provides` entry. A second
+ * picker of the same type never provides; `provides` is how a schema says
+ * which one does. */
+export declare function providersOf(schema: {
+  settings?: ReadonlyArray<{
+    type?: string;
+    id?: string;
+  }>;
+  provides?: Provides;
+} | undefined): Providers;
+/** The nearest link that provides `resource` to the LAST link of `chain`,
+ * or null when none does (the binding keeps its literal; a token blanks).
+ *
+ *  - A single provider (a picker) scopes itself and every descendant.
+ *  - An `each` provider scopes only the subtrees rooted at the block ids it
+ *    names — never itself, never its other children.
+ *  - The nearest provider wins per resource, even when its picker is unset:
+ *    an empty `featured-product` shows literals rather than borrowing the
+ *    route product from further up.
+ *  - A mount carries ONE item id (the nearest `each`'s), so an `each` scope
+ *    for one resource that sits outside a nearer `each` for another cannot
+ *    be resolved per item: null, not the outer list's items. */
+export declare function closestScopeAt(chain: readonly ScopeLink[], resource: ClosestResource): ClosestScope | null;
+//#endregion

package/dist/closest-scope.js

@@ -0,0 +1,66 @@
+//#region src/closest-scope.ts
+const PICKER_RESOURCES = {
+	product: "product",
+	collection: "collection",
+	page: "page",
+	blog: "blog",
+	article: "article"
+};
+/** The resources a schema provides: the FIRST picker of each resource type in
+* schema order (Shopify's rule — `closest.product` is the nearest `product`
+* setting), overridden per resource by an explicit `provides` entry. A second
+* picker of the same type never provides; `provides` is how a schema says
+* which one does. */
+function providersOf(schema) {
+	const out = {};
+	for (const setting of schema?.settings ?? []) {
+		const resource = setting.type ? PICKER_RESOURCES[setting.type] : void 0;
+		if (resource && setting.id && !out[resource]) out[resource] = { from: setting.id };
+	}
+	for (const [resource, decl] of Object.entries(schema?.provides ?? {})) out[resource] = decl;
+	return out;
+}
+/** True when `link` (at chain index `i`) scopes the next link through an
+* `each` declaration for some resource — i.e. the next link is one of the
+* per-item subtrees the list renders. */
+function eachChildAt(chain, i) {
+	const next = chain[i + 1];
+	if (!next) return false;
+	for (const decl of Object.values(chain[i].providers)) if (decl?.each?.includes(next.key)) return true;
+	return false;
+}
+/** The nearest link that provides `resource` to the LAST link of `chain`,
+* or null when none does (the binding keeps its literal; a token blanks).
+*
+*  - A single provider (a picker) scopes itself and every descendant.
+*  - An `each` provider scopes only the subtrees rooted at the block ids it
+*    names — never itself, never its other children.
+*  - The nearest provider wins per resource, even when its picker is unset:
+*    an empty `featured-product` shows literals rather than borrowing the
+*    route product from further up.
+*  - A mount carries ONE item id (the nearest `each`'s), so an `each` scope
+*    for one resource that sits outside a nearer `each` for another cannot
+*    be resolved per item: null, not the outer list's items. */
+function closestScopeAt(chain, resource) {
+	const last = chain.length - 1;
+	let nearestEach = -1;
+	for (let i = last - 1; i >= 0; i--) if (eachChildAt(chain, i)) {
+		nearestEach = i;
+		break;
+	}
+	for (let i = last; i >= 0; i--) {
+		const decl = chain[i].providers[resource];
+		if (!decl) continue;
+		if (!decl.each) return {
+			index: i,
+			decl
+		};
+		if (i < last && decl.each.includes(chain[i + 1].key)) return i === nearestEach ? {
+			index: i,
+			decl
+		} : null;
+	}
+	return null;
+}
+//#endregion
+export { PICKER_RESOURCES, closestScopeAt, providersOf };

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/editor-tools/apply.d.ts

@@ -0,0 +1,85 @@
+import { BlockDefinition, SchemaSetting, TemplateSection } from "../schemas.js";
+import { Op, ThemeDocument } from "../ops.js";
+import { IdPolicy } from "./coerce.js";
+import { EditorScope } from "./digest.js";
+import { LoadedRecipe, Recipe } from "./recipes.js";
+//#region src/editor-tools/apply.d.ts
+type Placement = {
+  enabled_on?: {
+    groups?: string[];
+    templates?: string[];
+  };
+  disabled_on?: {
+    groups?: string[];
+    templates?: string[];
+  };
+};
+type AppFields = {
+  source?: "app";
+  appId?: string;
+  tag?: string;
+  scriptUrl?: string;
+};
+type Preset = {
+  settings?: Record<string, unknown>;
+  blocks?: BlockDefinition[];
+};
+export type EditorBlockSchema = AppFields & {
+  type: string;
+  name?: string;
+  settings?: SchemaSetting[];
+  blocks?: BlockDefinition[];
+  max_blocks?: number;
+  presets?: Preset[];
+};
+export type EditorSectionSchema = EditorBlockSchema & Placement;
+export interface EditorSchemas {
+  /** `config/settings-schema.json`, t: resolved. */
+  settingsSchema: readonly {
+    settings?: SchemaSetting[];
+  }[];
+  /** Theme and app sections, as the editor-loader lists them. */
+  sections: EditorSectionSchema[];
+  blocks: EditorBlockSchema[];
+}
+export interface EngineContext {
+  doc: ThemeDocument;
+  schemas: EditorSchemas;
+  recipes: LoadedRecipe[];
+  /** `config/ai/guide.md`; empty when the theme ships none. */
+  guide?: string;
+  sanitizeRichText: (html: string) => string;
+  images: IdPolicy;
+  fonts?: IdPolicy;
+  /** Mints a new instance id; `${type}_${8 hex}` when absent, as the editor does. */
+  idFor?: (type: string) => string;
+}
+export type EditorToolResult = {
+  ok: true;
+  ops: Op[];
+  result: Record<string, unknown>;
+} | {
+  ok: false;
+  reason: string;
+};
+/**
+ * A recipe's sections, built and coerced as `add_section` and
+ * `update_*_setting` would build and coerce them, keyed by their new ids in
+ * recipe order. Refuses the whole recipe at the first bad section, block,
+ * setting or param.
+ */
+export declare function expandRecipe(recipe: Recipe, params: Record<string, string | number>, ctx: EngineContext, scope?: EditorScope): {
+  ok: true;
+  sections: [string, TemplateSection][];
+} | {
+  ok: false;
+  reason: string;
+};
+/**
+ * Runs one editor tool against a document: the ops that make the edit (what
+ * the admin would have sent for it, via `diffDocument`) and the result the
+ * model sees, or a refusal. Pure: no I/O, and `ctx.doc` is never mutated.
+ */
+export declare function applyEditorTool(name: string, args: unknown, ctx: EngineContext): EditorToolResult;
+//#endregion
+export {};