@zalify/storefront-kit 0.1.0

package/dist/schemas/bridge.d.ts

@@ -0,0 +1,98 @@
+/**
+ * L3 — Canvas-editor bridge protocol.
+ *
+ * postMessage contract between the Zalify canvas editor (host) and a
+ * theme preview running on another origin inside an iframe (frame).
+ * Both sides validate `event.origin` and the message envelope before
+ * acting; versions negotiate on CONTRACT_VERSION's major component.
+ */
+import type { SectionGroupData, SettingsBag, TemplateData } from './data.ts';
+import type { ThemeEditorManifest } from './manifest.ts';
+export declare const BRIDGE_NAMESPACE = "zalify-editor-bridge";
+/** Query param that switches a theme preview into editor mode. */
+export declare const EDITOR_MODE_PARAM = "zalify-editor";
+/** DOM attribute carrying a node's theme-JSON path (wire format). */
+export declare const DATA_PATH_ATTR = "data-z-path";
+/** DOM attribute the bridge sets on the selected node. */
+export declare const DATA_SELECTED_ATTR = "data-z-selected";
+export type Device = 'desktop' | 'mobile';
+export interface DOMRectLike {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Locates a section or block inside a template or section group. */
+export interface ThemeJsonPath {
+    scope: {
+        kind: 'template' | 'group';
+        name: string;
+    };
+    sectionKey: string;
+    /** Nested block keys, outermost first; empty = the section itself. */
+    blockKeys: string[];
+}
+/**
+ * Wire format: "template:index/hero/slide/box", "group:header-group/header".
+ * Every segment is URI-component-encoded so names containing "/" stay
+ * unambiguous (customer templates are named "customers/login").
+ */
+export declare function formatThemePath(path: ThemeJsonPath): string;
+export declare function parseThemePath(wire: string): ThemeJsonPath | null;
+export interface BridgeEnvelope<TType extends string, TPayload> {
+    z: typeof BRIDGE_NAMESPACE;
+    /** CONTRACT_VERSION of the sender. */
+    v: string;
+    type: TType;
+    payload: TPayload;
+}
+export type HostMessage = BridgeEnvelope<'bridge:init', {
+    editorOrigin: string;
+    device: Device;
+    selectedPath: string | null;
+}> | BridgeEnvelope<'block:select', {
+    path: string | null;
+}> | BridgeEnvelope<'block:hover', {
+    path: string | null;
+}> | BridgeEnvelope<'block:scroll-to', {
+    path: string;
+}> | BridgeEnvelope<'template:apply', {
+    templateName: string;
+    template: TemplateData;
+    groups?: Record<string, SectionGroupData>;
+    settingsData?: SettingsBag;
+}> | BridgeEnvelope<'device:set', {
+    device: Device;
+}> | BridgeEnvelope<'manifest:request', Record<string, never>>;
+export type FrameMessage = BridgeEnvelope<'bridge:ready', {
+    contractVersion: string;
+    templateName: string;
+    hash: string;
+}> | BridgeEnvelope<'block:clicked', {
+    path: string;
+    rect: DOMRectLike;
+}> | BridgeEnvelope<'block:hovered', {
+    path: string | null;
+    rect?: DOMRectLike;
+}> | BridgeEnvelope<'block:rects', {
+    rects: Array<{
+        path: string;
+        rect: DOMRectLike;
+    }>;
+}> | BridgeEnvelope<'manifest:response', {
+    manifest: ThemeEditorManifest;
+}> | BridgeEnvelope<'template:synced', {
+    hash: string;
+}> | BridgeEnvelope<'height:changed', {
+    height: number;
+}> | BridgeEnvelope<'navigation', {
+    templateName: string;
+    url: string;
+}> | BridgeEnvelope<'bridge:error', {
+    code: string;
+    message: string;
+}>;
+export type BridgeMessage = HostMessage | FrameMessage;
+export declare function isBridgeMessage(data: unknown): data is BridgeMessage;
+/** Same-major = compatible; anything else degrades to read-only preview. */
+export declare function isCompatibleVersion(mine: string, theirs: string): boolean;

package/dist/schemas/bridge.js

@@ -0,0 +1,50 @@
+export const BRIDGE_NAMESPACE = 'zalify-editor-bridge';
+/** Query param that switches a theme preview into editor mode. */
+export const EDITOR_MODE_PARAM = 'zalify-editor';
+/** DOM attribute carrying a node's theme-JSON path (wire format). */
+export const DATA_PATH_ATTR = 'data-z-path';
+/** DOM attribute the bridge sets on the selected node. */
+export const DATA_SELECTED_ATTR = 'data-z-selected';
+/**
+ * Wire format: "template:index/hero/slide/box", "group:header-group/header".
+ * Every segment is URI-component-encoded so names containing "/" stay
+ * unambiguous (customer templates are named "customers/login").
+ */
+export function formatThemePath(path) {
+    return [
+        `${path.scope.kind}:${encodeURIComponent(path.scope.name)}`,
+        encodeURIComponent(path.sectionKey),
+        ...path.blockKeys.map(encodeURIComponent),
+    ].join('/');
+}
+export function parseThemePath(wire) {
+    const [scopePart, sectionKey, ...blockKeys] = wire.split('/');
+    if (!scopePart || !sectionKey)
+        return null;
+    const colon = scopePart.indexOf(':');
+    if (colon === -1)
+        return null;
+    const kind = scopePart.slice(0, colon);
+    const name = scopePart.slice(colon + 1);
+    if ((kind !== 'template' && kind !== 'group') || !name)
+        return null;
+    return {
+        scope: { kind, name: decodeURIComponent(name) },
+        sectionKey: decodeURIComponent(sectionKey),
+        blockKeys: blockKeys.map(decodeURIComponent),
+    };
+}
+/* ----------------------------- guards ------------------------------- */
+export function isBridgeMessage(data) {
+    return (typeof data === 'object' &&
+        data !== null &&
+        data.z === BRIDGE_NAMESPACE &&
+        typeof data.v === 'string' &&
+        typeof data.type === 'string' &&
+        typeof data.payload === 'object' &&
+        data.payload !== null);
+}
+/** Same-major = compatible; anything else degrades to read-only preview. */
+export function isCompatibleVersion(mine, theirs) {
+    return mine.split('.')[0] === theirs.split('.')[0];
+}

package/dist/schemas/data.d.ts

@@ -0,0 +1,54 @@
+/**
+ * L1 — Theme data contract.
+ *
+ * The runtime JSON shapes of a Zalify theme, byte-compatible with
+ * Shopify OS 2.0 theme JSON (templates/*.json, sections/*-group.json,
+ * config/settings_data.json). These are the canonical definitions;
+ * @zalify/storefront-kit/react's engine types mirror them and will re-export from
+ * here as the packages converge.
+ */
+/** A section's or block's settings: setting id -> value. */
+export type SettingsBag = Record<string, unknown>;
+/** A block instance inside a section (or nested inside another block). */
+export interface BlockData {
+    type: string;
+    settings?: SettingsBag;
+    /** Nested blocks keyed by their stable key. */
+    blocks?: Record<string, BlockData>;
+    /** Render order of `blocks` keys. */
+    block_order?: string[];
+    disabled?: boolean;
+}
+/** A section instance inside a template or section group. */
+export interface SectionData {
+    type: string;
+    settings?: SettingsBag;
+    blocks?: Record<string, BlockData>;
+    block_order?: string[];
+    disabled?: boolean;
+    custom_css?: string[];
+}
+/** templates/*.json — a page template. */
+export interface TemplateData {
+    layout?: string | false;
+    wrapper?: string;
+    /** Sections keyed by their stable key. */
+    sections: Record<string, SectionData>;
+    /** Render order of `sections` keys. */
+    order: string[];
+}
+/** sections/*-group.json — header/footer/overlay section groups. */
+export interface SectionGroupData extends TemplateData {
+    type: string;
+    name: string;
+}
+/** config/settings_data.json — current values for global theme settings. */
+export interface SettingsData {
+    current: string | Record<string, unknown>;
+    presets?: Record<string, Record<string, unknown>>;
+}
+/**
+ * Parse theme JSON that may carry Shopify's leading block comment
+ * (the theme editor writes templates/*.json with a header comment).
+ */
+export declare function parseThemeJson<T>(raw: string, name?: string): T;

package/dist/schemas/data.js

@@ -0,0 +1,22 @@
+/**
+ * L1 — Theme data contract.
+ *
+ * The runtime JSON shapes of a Zalify theme, byte-compatible with
+ * Shopify OS 2.0 theme JSON (templates/*.json, sections/*-group.json,
+ * config/settings_data.json). These are the canonical definitions;
+ * @zalify/storefront-kit/react's engine types mirror them and will re-export from
+ * here as the packages converge.
+ */
+/**
+ * Parse theme JSON that may carry Shopify's leading block comment
+ * (the theme editor writes templates/*.json with a header comment).
+ */
+export function parseThemeJson(raw, name = 'theme JSON') {
+    const stripped = raw.replace(/^\s*\/\*[\s\S]*?\*\//, '').trim();
+    try {
+        return JSON.parse(stripped);
+    }
+    catch (error) {
+        throw new Error(`[storefront-kit] Failed to parse ${name}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/schemas/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @zalify/storefront-kit/schemas — the Zalify theme contract.
+ *
+ * L1 (data.ts):     runtime theme JSON shapes, = Shopify OS 2.0.
+ * L2 (schema.ts):   section/block schema types, = `{% schema %}` semantics.
+ *    (manifest.ts): the generated editor manifest tying L2 together.
+ * L3 (bridge.ts):   the canvas-editor postMessage protocol.
+ * validate.ts:      structural + schema-aware validators.
+ */
+export * from './data.ts';
+export * from './schema.ts';
+export * from './manifest.ts';
+export * from './bridge.ts';
+export * from './validate.ts';

package/dist/schemas/index.js

@@ -0,0 +1,14 @@
+/**
+ * @zalify/storefront-kit/schemas — the Zalify theme contract.
+ *
+ * L1 (data.ts):     runtime theme JSON shapes, = Shopify OS 2.0.
+ * L2 (schema.ts):   section/block schema types, = `{% schema %}` semantics.
+ *    (manifest.ts): the generated editor manifest tying L2 together.
+ * L3 (bridge.ts):   the canvas-editor postMessage protocol.
+ * validate.ts:      structural + schema-aware validators.
+ */
+export * from "./data.js";
+export * from "./schema.js";
+export * from "./manifest.js";
+export * from "./bridge.js";
+export * from "./validate.js";

package/dist/schemas/manifest.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The editor manifest: everything the canvas editor needs to drive its
+ * Insert/Layers/Config panels without executing theme code. Generated
+ * into the theme (and every scaffolded project) by `pnpm sync` as
+ * config/editor-manifest.generated.json; served live by the editor
+ * bridge as `manifest:response`.
+ */
+import type { SectionSchema, SettingDefinition, ThemeBlockSchema } from './schema.ts';
+/**
+ * Contract version spoken by this package. Bumped with the package;
+ * editors negotiate compatibility on the major component.
+ */
+export declare const CONTRACT_VERSION = "0.1.0";
+/** Repo-relative path of the generated manifest inside a theme/project. */
+export declare const EDITOR_MANIFEST_PATH = "config/editor-manifest.generated.json";
+export interface SectionManifestEntry extends SectionSchema {
+    /**
+     * True when the section has a server-side data loader; settings
+     * changes may render stale until the file write round-trips.
+     * Enriched at runtime by the bridge (sync.mjs cannot know).
+     */
+    hasLoader?: boolean;
+}
+export interface ThemeEditorManifest {
+    /** Provenance note ("scripts/sync.mjs — do not edit…"). */
+    generatedBy?: string;
+    contractVersion: string;
+    theme: {
+        name: string;
+        version: string;
+    };
+    /** Section schemas keyed by section type. */
+    sections: Record<string, SectionManifestEntry>;
+    /** Theme block schemas keyed by block type (includes "_" private blocks). */
+    blocks: Record<string, ThemeBlockSchema>;
+    /** = config/settings_schema.json (global theme settings). */
+    settingsSchema: Array<{
+        name: string;
+        theme_name?: string;
+        theme_version?: string;
+        settings?: SettingDefinition[];
+        [key: string]: unknown;
+    }>;
+    /** Editable template names ("index", "product", "customers/login", …). */
+    templates: string[];
+    /** Section group names ("header-group", "footer-group", …). */
+    sectionGroups: string[];
+    /** Flattened "t:" key -> display copy for the editor's locale. */
+    locales: Record<string, string>;
+    /** Content hash of everything above, for snapshot/bridge consistency. */
+    hash: string;
+}
+/**
+ * Resolve a "t:"-prefixed locale key against the manifest's flattened
+ * locales; plain strings pass through.
+ */
+export declare function resolveLocale(value: string, locales: Record<string, string>): string;
+/**
+ * Flatten a nested locale-schema object ({labels: {text: "Text"}}) into
+ * "labels.text" -> "Text" pairs, the form `ThemeEditorManifest.locales`
+ * carries.
+ */
+export declare function flattenLocales(tree: Record<string, unknown>, prefix?: string, out?: Record<string, string>): Record<string, string>;

package/dist/schemas/manifest.js

@@ -0,0 +1,32 @@
+/**
+ * Contract version spoken by this package. Bumped with the package;
+ * editors negotiate compatibility on the major component.
+ */
+export const CONTRACT_VERSION = '0.1.0';
+/** Repo-relative path of the generated manifest inside a theme/project. */
+export const EDITOR_MANIFEST_PATH = 'config/editor-manifest.generated.json';
+/**
+ * Resolve a "t:"-prefixed locale key against the manifest's flattened
+ * locales; plain strings pass through.
+ */
+export function resolveLocale(value, locales) {
+    if (!value.startsWith('t:'))
+        return value;
+    return locales[value.slice(2)] ?? value;
+}
+/**
+ * Flatten a nested locale-schema object ({labels: {text: "Text"}}) into
+ * "labels.text" -> "Text" pairs, the form `ThemeEditorManifest.locales`
+ * carries.
+ */
+export function flattenLocales(tree, prefix = '', out = {}) {
+    for (const [key, value] of Object.entries(tree)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (typeof value === 'string')
+            out[path] = value;
+        else if (value && typeof value === 'object') {
+            flattenLocales(value, path, out);
+        }
+    }
+    return out;
+}

package/dist/schemas/schema.d.ts

@@ -0,0 +1,159 @@
+/**
+ * L2 — Theme schema contract.
+ *
+ * The editor-facing description of sections and blocks: what Shopify
+ * carries in a section's `{% schema %}` tag. Field semantics follow
+ * Shopify OS 2.0 exactly; this file only gives them an explicit,
+ * React-side home (components export these objects, and sync.mjs
+ * mirrors them out of the Liquid theme's `{% schema %}` tags).
+ */
+import type { BlockData, SectionData, SettingsBag } from './data.ts';
+/**
+ * Shopify input setting types, grouped by the tier in which the Zalify
+ * canvas editor implements them. Unknown/future types must degrade to a
+ * read-only display in the editor — never an error, never value loss.
+ */
+export declare const SETTING_TYPE_TIERS: {
+    /** Phase 1 — must render as editable fields. */
+    readonly t0: readonly ["text", "textarea", "richtext", "inline_richtext", "number", "range", "checkbox", "select", "radio", "color", "image_picker", "url", "text_alignment"];
+    /** Phase 1.5 — theme-level pickers. */
+    readonly t1: readonly ["font_picker", "color_background", "color_scheme", "color_scheme_group", "video_url", "html", "link_list"];
+    /** Phase 2 — resource pickers backed by storefront data. */
+    readonly t2: readonly ["product", "product_list", "collection", "collection_list", "blog", "article", "page", "metaobject", "video"];
+    /** Liquid-only; React themes preserve the value but never render it. */
+    readonly notApplicable: readonly ["liquid"];
+};
+export type KnownInputSettingType = (typeof SETTING_TYPE_TIERS.t0)[number] | (typeof SETTING_TYPE_TIERS.t1)[number] | (typeof SETTING_TYPE_TIERS.t2)[number] | (typeof SETTING_TYPE_TIERS.notApplicable)[number];
+export declare const SIDEBAR_SETTING_TYPES: readonly ["header", "paragraph"];
+export type SidebarSettingType = (typeof SIDEBAR_SETTING_TYPES)[number];
+/** Non-input schema entries (group headers / help copy). */
+export interface SidebarSetting {
+    type: SidebarSettingType;
+    content: string;
+    /** Shopify conditional-visibility expression. */
+    visible_if?: string;
+}
+export interface SettingOption {
+    value: string;
+    label: string;
+    group?: string;
+}
+/**
+ * An input setting definition. One open shape rather than a closed
+ * discriminated union: this mirrors the JSON reality (Shopify adds
+ * setting types over time) and keeps older editors forward-compatible.
+ * Type-specific fields are optional and only meaningful for the types
+ * that define them (`options` for select/radio, `min`/`max`/`step`/
+ * `unit` for range, `placeholder` for text-likes, …).
+ */
+export interface InputSetting {
+    type: KnownInputSettingType | (string & {});
+    /** Key in the instance's settings bag. */
+    id: string;
+    /** Supports "t:" locale keys. */
+    label: string;
+    info?: string;
+    default?: unknown;
+    visible_if?: string;
+    placeholder?: string;
+    options?: SettingOption[];
+    min?: number;
+    max?: number;
+    step?: number;
+    unit?: string;
+    /** range-style sliders on newer setting types. */
+    accept?: string[];
+}
+export type SettingDefinition = InputSetting | SidebarSetting;
+export declare function isSidebarSetting(setting: SettingDefinition): setting is SidebarSetting;
+export declare function isInputSetting(setting: SettingDefinition): setting is InputSetting;
+/** Which block types a section (or block) accepts as children. */
+export interface BlockRule {
+    /**
+     * A concrete block type, or a wildcard: "@theme" (all public theme
+     * blocks — types not starting with "_"), "@app" (app blocks).
+     */
+    type: string;
+    limit?: number;
+}
+/**
+ * A section-local block defined inline in the section's schema
+ * (Shopify OS 2.0 "section blocks"): the entry carries `name` (and
+ * usually `settings`) instead of referencing a theme block. Local
+ * blocks cannot nest further blocks.
+ */
+export interface LocalBlockDefinition extends BlockRule {
+    name: string;
+    settings?: SettingDefinition[];
+}
+/** An entry in a section schema's `blocks` array: reference or inline. */
+export type SectionBlockEntry = BlockRule | LocalBlockDefinition;
+export declare function isLocalBlockDefinition(entry: SectionBlockEntry): entry is LocalBlockDefinition;
+export interface PresetBlock {
+    type: string;
+    settings?: SettingsBag;
+    blocks?: PresetBlock[];
+    /** Static preset blocks may pin their key (Shopify allows both forms). */
+    id?: string;
+}
+/** An "add section" catalog entry in the editor. */
+export interface SectionPreset {
+    name: string;
+    settings?: SettingsBag;
+    blocks?: PresetBlock[];
+    /** Zalify extension: insert-panel grouping. */
+    category?: string;
+}
+export interface TemplateAvailability {
+    templates?: string[];
+    groups?: string[];
+}
+/**
+ * = Shopify OS 2.0 section schema, minus Liquid-rendering concerns
+ * (tag/class/javascript/stylesheet stay in the Liquid theme).
+ */
+export interface SectionSchema {
+    /** Supports "t:" locale keys. */
+    name: string;
+    settings?: SettingDefinition[];
+    /** Allowed child blocks (references or local definitions); absent = none. */
+    blocks?: SectionBlockEntry[];
+    /** Defaults to Shopify's cap of 50 when blocks are allowed. */
+    max_blocks?: number;
+    /** Per-template instance cap (e.g. 1 for header-like sections). */
+    limit?: number;
+    /** No presets = not manually insertable (main-* sections). */
+    presets?: SectionPreset[];
+    default?: Pick<SectionData, 'settings' | 'blocks' | 'block_order'>;
+    enabled_on?: TemplateAvailability;
+    disabled_on?: TemplateAvailability;
+}
+/** = Shopify OS 2.0 theme block schema (blocks/*.liquid `{% schema %}`). */
+export interface ThemeBlockSchema {
+    name: string;
+    settings?: SettingDefinition[];
+    /** Theme blocks may nest blocks themselves. */
+    blocks?: BlockRule[];
+    presets?: Array<{
+        name: string;
+        settings?: SettingsBag;
+        blocks?: PresetBlock[];
+    }>;
+}
+/** Shopify's default max_blocks when a section allows blocks. */
+export declare const DEFAULT_MAX_BLOCKS = 50;
+/** Block types starting with "_" are private to their section. */
+export declare function isPrivateBlockType(type: string): boolean;
+/**
+ * Resolve a parent's block rules against the full block registry:
+ * which concrete child types may be inserted?
+ */
+export declare function allowedChildTypes(rules: SectionBlockEntry[] | undefined, allBlockTypes: string[]): string[];
+/** Instantiate a preset's block list into named-map + order form. */
+export declare function instantiatePresetBlocks(presetBlocks: PresetBlock[] | undefined): Pick<BlockData, 'blocks' | 'block_order'>;
+/**
+ * Generate a stable, non-colliding key for a newly inserted
+ * section/block, following Shopify's editor convention
+ * (type with private prefix stripped + counter).
+ */
+export declare function generateKey(type: string, siblings: string[]): string;

package/dist/schemas/schema.js

@@ -0,0 +1,129 @@
+/* ------------------------- setting definitions ------------------------- */
+/**
+ * Shopify input setting types, grouped by the tier in which the Zalify
+ * canvas editor implements them. Unknown/future types must degrade to a
+ * read-only display in the editor — never an error, never value loss.
+ */
+export const SETTING_TYPE_TIERS = {
+    /** Phase 1 — must render as editable fields. */
+    t0: [
+        'text',
+        'textarea',
+        'richtext',
+        'inline_richtext',
+        'number',
+        'range',
+        'checkbox',
+        'select',
+        'radio',
+        'color',
+        'image_picker',
+        'url',
+        'text_alignment',
+    ],
+    /** Phase 1.5 — theme-level pickers. */
+    t1: [
+        'font_picker',
+        'color_background',
+        'color_scheme',
+        'color_scheme_group',
+        'video_url',
+        'html',
+        'link_list',
+    ],
+    /** Phase 2 — resource pickers backed by storefront data. */
+    t2: [
+        'product',
+        'product_list',
+        'collection',
+        'collection_list',
+        'blog',
+        'article',
+        'page',
+        'metaobject',
+        'video',
+    ],
+    /** Liquid-only; React themes preserve the value but never render it. */
+    notApplicable: ['liquid'],
+};
+export const SIDEBAR_SETTING_TYPES = ['header', 'paragraph'];
+export function isSidebarSetting(setting) {
+    return SIDEBAR_SETTING_TYPES.includes(setting.type);
+}
+export function isInputSetting(setting) {
+    return !isSidebarSetting(setting);
+}
+export function isLocalBlockDefinition(entry) {
+    return 'name' in entry && typeof entry.name === 'string';
+}
+/** Shopify's default max_blocks when a section allows blocks. */
+export const DEFAULT_MAX_BLOCKS = 50;
+/** Block types starting with "_" are private to their section. */
+export function isPrivateBlockType(type) {
+    return type.startsWith('_');
+}
+/**
+ * Resolve a parent's block rules against the full block registry:
+ * which concrete child types may be inserted?
+ */
+export function allowedChildTypes(rules, allBlockTypes) {
+    if (!rules?.length)
+        return [];
+    const allowed = new Set();
+    for (const rule of rules) {
+        if (rule.type === '@theme') {
+            for (const type of allBlockTypes) {
+                if (!isPrivateBlockType(type))
+                    allowed.add(type);
+            }
+        }
+        else if (rule.type !== '@app') {
+            allowed.add(rule.type);
+        }
+    }
+    return [...allowed];
+}
+/** Instantiate a preset's block list into named-map + order form. */
+export function instantiatePresetBlocks(presetBlocks) {
+    if (!presetBlocks?.length)
+        return {};
+    const blocks = {};
+    const order = [];
+    const counters = new Map();
+    for (const preset of presetBlocks) {
+        let key = preset.id;
+        if (!key || key in blocks) {
+            const base = preset.type.replace(/^_/, '');
+            const next = (counters.get(base) ?? 0) + 1;
+            counters.set(base, next);
+            key = `${base}-${next}`;
+            while (key in blocks) {
+                const bumped = (counters.get(base) ?? 0) + 1;
+                counters.set(base, bumped);
+                key = `${base}-${bumped}`;
+            }
+        }
+        const nested = instantiatePresetBlocks(preset.blocks);
+        blocks[key] = {
+            type: preset.type,
+            settings: preset.settings ? { ...preset.settings } : {},
+            ...nested,
+        };
+        order.push(key);
+    }
+    return { blocks, block_order: order };
+}
+/**
+ * Generate a stable, non-colliding key for a newly inserted
+ * section/block, following Shopify's editor convention
+ * (type with private prefix stripped + counter).
+ */
+export function generateKey(type, siblings) {
+    const base = type.replace(/^_/, '');
+    if (!siblings.includes(base))
+        return base;
+    let index = 1;
+    while (siblings.includes(`${base}-${index}`))
+        index += 1;
+    return `${base}-${index}`;
+}

package/dist/schemas/validate.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Contract validators. Pure functions returning issue lists (never
+ * throwing): callers decide whether an issue is fatal. Structural
+ * invariants always run; schema-aware checks (block whitelists,
+ * max_blocks) run only when a manifest is provided, so templates can
+ * be validated before the component registry is known.
+ */
+import type { SectionGroupData, TemplateData } from './data.ts';
+import type { ThemeEditorManifest } from './manifest.ts';
+export interface ValidationIssue {
+    /** JSON-pointer-ish location, e.g. "sections.hero.blocks.slide". */
+    path: string;
+    code: 'order-unknown-key' | 'order-duplicate-key' | 'unknown-type' | 'block-not-allowed' | 'max-blocks-exceeded' | 'setting-missing-id' | 'setting-duplicate-id' | 'manifest-missing-field';
+    message: string;
+}
+/**
+ * Validate a template (or section group) against the L1 invariants,
+ * and — when a manifest is given — against the section/block schemas.
+ */
+export declare function validateTemplate(template: TemplateData | SectionGroupData, manifest?: ThemeEditorManifest): ValidationIssue[];
+/** Validate a manifest's own consistency. */
+export declare function validateManifest(manifest: ThemeEditorManifest): ValidationIssue[];