@avocadostudio-ai/shared 0.1.0

package/dist/api-responses.d.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+export declare const assistantResponseSchema: z.ZodObject<{
+    status: z.ZodOptional<z.ZodString>;
+    summary: z.ZodOptional<z.ZodString>;
+    changes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    mentionedSlugs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    previewVersion: z.ZodOptional<z.ZodNumber>;
+    validationErrors: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodObject<{
+        fieldErrors: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+        formErrors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$loose>]>>;
+    modelUsed: z.ZodOptional<z.ZodString>;
+    modelKey: z.ZodOptional<z.ZodString>;
+    plannerSource: z.ZodOptional<z.ZodEnum<{
+        openai: "openai";
+        anthropic: "anthropic";
+        gemini: "gemini";
+        demo: "demo";
+    }>>;
+    pendingPlanId: z.ZodOptional<z.ZodString>;
+    destructiveReasons: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    continuation: z.ZodOptional<z.ZodObject<{
+        chainId: z.ZodString;
+        currentStep: z.ZodNumber;
+        totalSteps: z.ZodNumber;
+        nextStepLabel: z.ZodString;
+    }, z.core.$loose>>;
+    focusBlockId: z.ZodOptional<z.ZodString>;
+    updatedSlug: z.ZodOptional<z.ZodString>;
+    undoSlug: z.ZodOptional<z.ZodString>;
+    suggestions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    variations: z.ZodOptional<z.ZodObject<{
+        blockId: z.ZodString;
+        blockType: z.ZodString;
+        pageSlug: z.ZodString;
+        baseProps: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        options: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodString;
+            summary: z.ZodString;
+            patch: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            changedKeys: z.ZodArray<z.ZodString>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+    debug: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type AssistantResponseParsed = z.infer<typeof assistantResponseSchema>;
+export declare const chatStartResponseSchema: z.ZodObject<{
+    streamId: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export declare const slugsResponseSchema: z.ZodObject<{
+    slugs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+export declare const bootstrapResponseSchema: z.ZodObject<{
+    slugs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+export declare const cancelResponseSchema: z.ZodObject<{
+    status: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;

package/dist/api-responses.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Shared orchestrator API response schemas
+// Used by the editor to validate fetch() responses at runtime.
+// All schemas are lenient (passthrough extra fields) so they survive server
+// additions without requiring client deployments.
+// ---------------------------------------------------------------------------
+const continuationSchema = z.object({
+    chainId: z.string(),
+    currentStep: z.number(),
+    totalSteps: z.number(),
+    nextStepLabel: z.string(),
+}).passthrough();
+const variationOptionSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    summary: z.string(),
+    patch: z.record(z.string(), z.unknown()),
+    changedKeys: z.array(z.string()),
+}).passthrough();
+const variationsSchema = z.object({
+    blockId: z.string(),
+    blockType: z.string(),
+    pageSlug: z.string(),
+    baseProps: z.record(z.string(), z.unknown()),
+    options: z.array(variationOptionSchema),
+}).passthrough();
+export const assistantResponseSchema = z.object({
+    status: z.string().optional(),
+    summary: z.string().optional(),
+    changes: z.array(z.string()).optional(),
+    mentionedSlugs: z.array(z.string()).optional(),
+    previewVersion: z.number().optional(),
+    validationErrors: z.union([
+        z.array(z.string()),
+        z.object({
+            fieldErrors: z.record(z.string(), z.array(z.string())).optional(),
+            formErrors: z.array(z.string()).optional(),
+        }).passthrough(),
+    ]).optional(),
+    modelUsed: z.string().optional(),
+    modelKey: z.string().optional(),
+    plannerSource: z.enum(["openai", "anthropic", "gemini", "demo"]).optional(),
+    pendingPlanId: z.string().optional(),
+    destructiveReasons: z.array(z.string()).optional(),
+    continuation: continuationSchema.optional(),
+    focusBlockId: z.string().optional(),
+    updatedSlug: z.string().optional(),
+    undoSlug: z.string().optional(),
+    suggestions: z.array(z.string()).optional(),
+    variations: variationsSchema.optional(),
+    debug: z.record(z.string(), z.unknown()).optional(),
+    error: z.string().optional(),
+}).passthrough();
+export const chatStartResponseSchema = z.object({
+    streamId: z.string().optional(),
+    error: z.string().optional(),
+}).passthrough();
+export const slugsResponseSchema = z.object({
+    slugs: z.array(z.string()).optional(),
+}).passthrough();
+export const bootstrapResponseSchema = z.object({
+    slugs: z.array(z.string()).optional(),
+}).passthrough();
+export const cancelResponseSchema = z.object({
+    status: z.string().optional(),
+    error: z.string().optional(),
+}).passthrough();

package/dist/block-manifest.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import type { FieldMeta, ListFieldMeta } from "./blocks/_registry.ts";
+export declare const jsonSchemaLikeSchema: z.ZodType<Record<string, unknown>>;
+export declare const blockDefinitionSchema: z.ZodObject<{
+    type: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    editablePaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    propsSchema: z.ZodType<Record<string, unknown>, unknown, z.core.$ZodTypeInternals<Record<string, unknown>, unknown>>;
+    defaultProps: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const blockManifestSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    blocks: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        displayName: z.ZodOptional<z.ZodString>;
+        editablePaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        propsSchema: z.ZodType<Record<string, unknown>, unknown, z.core.$ZodTypeInternals<Record<string, unknown>, unknown>>;
+        defaultProps: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type BlockDefinition = z.infer<typeof blockDefinitionSchema>;
+export type BlockManifest = z.infer<typeof blockManifestSchema>;
+export declare function validateByJsonSchemaLike(schema: Record<string, unknown>, value: unknown): boolean;
+export declare function deriveFieldMetaFromSchema(propsSchema: Record<string, unknown>): {
+    fields: Record<string, FieldMeta>;
+    listFields: Record<string, ListFieldMeta>;
+};
+export declare function validateManifestDefaultProps(blocks: BlockDefinition[]): string | null;

package/dist/block-manifest.js

@@ -0,0 +1,247 @@
+import { z } from "zod";
+export const jsonSchemaLikeSchema = z.lazy(() => z.object({
+    type: z.string().optional(),
+    properties: z.record(z.string(), jsonSchemaLikeSchema).optional(),
+    required: z.array(z.string()).optional(),
+    items: z.union([jsonSchemaLikeSchema, z.array(jsonSchemaLikeSchema)]).optional(),
+    enum: z.array(z.unknown()).optional(),
+    anyOf: z.array(jsonSchemaLikeSchema).optional(),
+    oneOf: z.array(jsonSchemaLikeSchema).optional(),
+    allOf: z.array(jsonSchemaLikeSchema).optional(),
+    additionalProperties: z.union([z.boolean(), jsonSchemaLikeSchema]).optional(),
+    description: z.string().optional()
+}).catchall(z.unknown()));
+export const blockDefinitionSchema = z.object({
+    type: z.string().min(1),
+    displayName: z.string().min(1).optional(),
+    editablePaths: z.array(z.string().min(1)).optional(),
+    propsSchema: jsonSchemaLikeSchema,
+    defaultProps: z.record(z.string(), z.unknown()).optional()
+});
+export const blockManifestSchema = z.object({
+    version: z.number().int().positive(),
+    blocks: z.array(blockDefinitionSchema)
+});
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function validateByJsonSchemaLike(schema, value) {
+    const type = typeof schema.type === "string" ? schema.type : undefined;
+    if (type === "object") {
+        if (!isObject(value))
+            return false;
+        const props = isObject(schema.properties) ? schema.properties : {};
+        const required = Array.isArray(schema.required) ? schema.required.filter((item) => typeof item === "string") : [];
+        for (const key of required) {
+            if (!(key in value))
+                return false;
+        }
+        for (const [key, propSchema] of Object.entries(props)) {
+            if (!(key in value))
+                continue;
+            if (!isObject(propSchema))
+                continue;
+            if (!validateByJsonSchemaLike(propSchema, value[key]))
+                return false;
+        }
+        return true;
+    }
+    if (type === "array") {
+        if (!Array.isArray(value))
+            return false;
+        const items = schema.items;
+        if (isObject(items))
+            return value.every((item) => validateByJsonSchemaLike(items, item));
+        return true;
+    }
+    if (type === "string")
+        return typeof value === "string";
+    if (type === "number" || type === "integer")
+        return typeof value === "number" && Number.isFinite(value);
+    if (type === "boolean")
+        return typeof value === "boolean";
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Derive FieldMeta from JSON Schema — fallback for custom blocks not in the
+// shared registry. Heuristics map schema types and prop key patterns to the
+// FieldKind enum so the PropertyPanel can render appropriate controls.
+// ---------------------------------------------------------------------------
+const IMAGE_KEY_RE = /(?:image|img)(?:Url|Src)?$|^(?:src|imageUrl|logoUrl|heroImage)$/i;
+const IMAGE_ALT_KEY_RE = /(?:Alt)$/;
+function labelFromKey(key) {
+    // ctaText → "CTA text", imageUrl → "Image", logoAlt → "Logo alt",
+    // background_image → "Background image", video_url → "Video", src → "Src"
+    const spaced = key
+        .replace(/[_-]+/g, " ")
+        .replace(/([a-z])([A-Z])/g, "$1 $2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2");
+    const label = spaced.charAt(0).toUpperCase() + spaced.slice(1);
+    // Strip trailing "Url"/"Src" for image fields, but keep the original label if
+    // stripping would leave nothing (e.g. a field literally named "src").
+    const stripped = label.replace(/\s*(?:Url|Src)$/i, "").trim();
+    return stripped || label;
+}
+function inferFieldKind(key, schema) {
+    const type = typeof schema.type === "string" ? schema.type : undefined;
+    if (isProseMirrorDocSchema(schema))
+        return "richtext";
+    if (type === "boolean")
+        return "boolean";
+    if (type !== "string" && type !== "number" && type !== "integer")
+        return "text";
+    if (type === "number" || type === "integer")
+        return "number";
+    if (Array.isArray(schema.enum) && schema.enum.length > 0)
+        return "enum";
+    if (IMAGE_ALT_KEY_RE.test(key))
+        return "imageAlt";
+    if (IMAGE_KEY_RE.test(key))
+        return "image";
+    return "text";
+}
+function deriveItemFields(itemSchema) {
+    const fields = {};
+    const props = isObject(itemSchema.properties) ? itemSchema.properties : {};
+    for (const [key, propSchema] of Object.entries(props)) {
+        if (!isObject(propSchema))
+            continue;
+        // Skip opaque object/array props (they'd render as "[object Object]"), but
+        // keep richtext docs — those self-identify and get the richtext editor.
+        const t = typeof propSchema.type === "string" ? propSchema.type : undefined;
+        if ((t === "object" || t === "array") && !isProseMirrorDocSchema(propSchema))
+            continue;
+        const kind = inferFieldKind(key, propSchema);
+        const fm = { kind, label: labelFromKey(key) };
+        if (kind === "enum" && Array.isArray(propSchema.enum)) {
+            fm.options = propSchema.enum.filter((v) => typeof v === "string");
+        }
+        fields[key] = fm;
+    }
+    return fields;
+}
+/**
+ * A ProseMirror/Tiptap richtext document self-identifies: it is an object whose
+ * `type` is pinned to the literal `"doc"`. We key off that signature (rather
+ * than a CMS-specific annotation) so any block declaring a `{type:"doc",content}`
+ * field gets the richtext editor — and the underlying document is edited as-is,
+ * not flattened to a string.
+ */
+function isProseMirrorDocSchema(schema) {
+    if (!isObject(schema) || schema.type !== "object" || !isObject(schema.properties))
+        return false;
+    return constValue(schema.properties.type) === "doc";
+}
+/** Read a string-literal discriminant value (`const`, or a single-value `enum`) from a prop schema. */
+function constValue(schema) {
+    if (!isObject(schema))
+        return undefined;
+    if (typeof schema.const === "string")
+        return schema.const;
+    if (Array.isArray(schema.enum) && schema.enum.length === 1 && typeof schema.enum[0] === "string")
+        return schema.enum[0];
+    return undefined;
+}
+/**
+ * Detect an array whose items are a discriminated union (oneOf/anyOf of object
+ * branches, each pinning one property to a string literal). Produces a
+ * polymorphic ListFieldMeta: a per-branch field set keyed by the discriminant
+ * value, plus a merged `itemFields` fallback. Returns undefined if the items
+ * are not such a union (caller falls back to the uniform-object path).
+ */
+function derivePolymorphicListField(key, itemSchema) {
+    const branchesRaw = Array.isArray(itemSchema.oneOf)
+        ? itemSchema.oneOf
+        : Array.isArray(itemSchema.anyOf)
+            ? itemSchema.anyOf
+            : undefined;
+    if (!branchesRaw)
+        return undefined;
+    const branches = branchesRaw.filter((b) => isObject(b) && isObject(b.properties));
+    if (branches.length < 2)
+        return undefined;
+    // The discriminator is a property that carries a distinct string literal on
+    // every branch. Prefer "component"; otherwise pick the first key that qualifies.
+    const candidateKeys = Object.keys(branches[0].properties ?? {});
+    const orderedKeys = candidateKeys.includes("component")
+        ? ["component", ...candidateKeys.filter((k) => k !== "component")]
+        : candidateKeys;
+    let discriminator;
+    for (const cand of orderedKeys) {
+        if (branches.every((b) => constValue(b.properties[cand]) !== undefined)) {
+            discriminator = cand;
+            break;
+        }
+    }
+    if (!discriminator)
+        return undefined;
+    const itemFieldsByType = {};
+    const merged = {};
+    for (const branch of branches) {
+        const disc = constValue(branch.properties[discriminator]);
+        if (disc === undefined)
+            continue;
+        const fields = deriveItemFields(branch);
+        delete fields[discriminator]; // the discriminant itself is not an editable field
+        itemFieldsByType[disc] = fields;
+        for (const [fk, fm] of Object.entries(fields))
+            if (!(fk in merged))
+                merged[fk] = fm;
+    }
+    if (Object.keys(itemFieldsByType).length === 0)
+        return undefined;
+    return { label: labelFromKey(key), itemFields: merged, discriminator, itemFieldsByType };
+}
+export function deriveFieldMetaFromSchema(propsSchema) {
+    const fields = {};
+    const listFields = {};
+    const props = isObject(propsSchema.properties) ? propsSchema.properties : {};
+    for (const [key, propSchema] of Object.entries(props)) {
+        if (!isObject(propSchema))
+            continue;
+        const type = typeof propSchema.type === "string" ? propSchema.type : undefined;
+        // Array of a discriminated union (oneOf/anyOf of object branches) →
+        // polymorphic list field: per-branch fields keyed by the discriminant value.
+        if (type === "array" && isObject(propSchema.items)) {
+            const polymorphic = derivePolymorphicListField(key, propSchema.items);
+            if (polymorphic) {
+                listFields[key] = polymorphic;
+                continue;
+            }
+        }
+        // Array with object items → listFields
+        if (type === "array" && isObject(propSchema.items) && propSchema.items.type === "object") {
+            const itemFields = deriveItemFields(propSchema.items);
+            if (Object.keys(itemFields).length > 0) {
+                listFields[key] = { label: labelFromKey(key), itemFields };
+                continue;
+            }
+        }
+        // Structural props (an object, or an array whose items we couldn't turn
+        // into a list field above) have no meaningful single-control affordance —
+        // a text input over them renders "[object Object]" and corrupts the value
+        // on edit. Skip them rather than emit a broken field; the ops-engine
+        // passthrough preserves the underlying data untouched. A richtext document
+        // is the exception — it self-identifies and gets the richtext editor.
+        if ((type === "object" || type === "array") && !isProseMirrorDocSchema(propSchema))
+            continue;
+        // Scalar field (or richtext document)
+        const kind = inferFieldKind(key, propSchema);
+        const fm = { kind, label: labelFromKey(key) };
+        if (kind === "enum" && Array.isArray(propSchema.enum)) {
+            fm.options = propSchema.enum.filter((v) => typeof v === "string");
+        }
+        fields[key] = fm;
+    }
+    return { fields, listFields };
+}
+export function validateManifestDefaultProps(blocks) {
+    for (const block of blocks) {
+        if (!block.defaultProps)
+            continue;
+        if (!validateByJsonSchemaLike(block.propsSchema, block.defaultProps)) {
+            return `defaultProps do not match propsSchema for block "${block.type}"`;
+        }
+    }
+    return null;
+}

package/dist/block-names.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Block type name mapping utilities.
+ *
+ * The block registry uses PascalCase (e.g. "FAQAccordion", "CTA", "CardGrid").
+ * Different CMSs use different conventions:
+ *   - Sanity: camelCase ("faqAccordion", "cta", "cardGrid")
+ *   - Strapi/Contentful: lowercase ("faqaccordion", "cta", "cardgrid")
+ *
+ * These helpers provide canonical lookups so each CMS integration
+ * doesn't need to maintain its own reverse map.
+ */
+/** Convert PascalCase block type to camelCase: CTA → cta, FAQAccordion → faqAccordion */
+export declare function blockTypeToCamel(pascalCase: string): string;
+/** Reverse lookup: camelCase → PascalCase (faqAccordion → FAQAccordion). Sanity convention. */
+export declare function camelToBlockType(camelName: string): string;
+/** Reverse lookup: lowercase → PascalCase (faqaccordion → FAQAccordion). Strapi/Contentful convention. */
+export declare function lowerToBlockType(lowerName: string): string;
+/** Convert PascalCase to lowercase: FAQAccordion → faqaccordion */
+export declare function blockTypeToLower(pascalCase: string): string;

package/dist/block-names.js

@@ -0,0 +1,52 @@
+import { getAllBlockMeta } from "./blocks/_registry.js";
+/**
+ * Block type name mapping utilities.
+ *
+ * The block registry uses PascalCase (e.g. "FAQAccordion", "CTA", "CardGrid").
+ * Different CMSs use different conventions:
+ *   - Sanity: camelCase ("faqAccordion", "cta", "cardGrid")
+ *   - Strapi/Contentful: lowercase ("faqaccordion", "cta", "cardgrid")
+ *
+ * These helpers provide canonical lookups so each CMS integration
+ * doesn't need to maintain its own reverse map.
+ */
+// ── PascalCase → camelCase (Sanity convention) ─────────────────────────
+/** Convert PascalCase block type to camelCase: CTA → cta, FAQAccordion → faqAccordion */
+export function blockTypeToCamel(pascalCase) {
+    // All-uppercase acronyms: CTA → cta
+    if (pascalCase === pascalCase.toUpperCase())
+        return pascalCase.toLowerCase();
+    // Leading acronym: FAQAccordion → faqAccordion
+    const match = pascalCase.match(/^([A-Z]+)([A-Z][a-z].*)$/);
+    if (match)
+        return match[1].toLowerCase() + match[2];
+    // Normal PascalCase: CardGrid → cardGrid
+    return pascalCase.charAt(0).toLowerCase() + pascalCase.slice(1);
+}
+// ── Reverse lookup maps (built lazily from registry) ────────────────────
+let _camelMap = null;
+let _lowerMap = null;
+function ensureMaps() {
+    if (_camelMap)
+        return;
+    _camelMap = new Map();
+    _lowerMap = new Map();
+    for (const blockType of Object.keys(getAllBlockMeta())) {
+        _camelMap.set(blockTypeToCamel(blockType), blockType);
+        _lowerMap.set(blockType.toLowerCase(), blockType);
+    }
+}
+/** Reverse lookup: camelCase → PascalCase (faqAccordion → FAQAccordion). Sanity convention. */
+export function camelToBlockType(camelName) {
+    ensureMaps();
+    return _camelMap.get(camelName) ?? camelName.charAt(0).toUpperCase() + camelName.slice(1);
+}
+/** Reverse lookup: lowercase → PascalCase (faqaccordion → FAQAccordion). Strapi/Contentful convention. */
+export function lowerToBlockType(lowerName) {
+    ensureMaps();
+    return _lowerMap.get(lowerName) ?? lowerName.charAt(0).toUpperCase() + lowerName.slice(1);
+}
+/** Convert PascalCase to lowercase: FAQAccordion → faqaccordion */
+export function blockTypeToLower(pascalCase) {
+    return pascalCase.toLowerCase();
+}

package/dist/blocks/_helpers.d.ts

@@ -0,0 +1,14 @@
+import type { FieldMeta, ImageSpec } from "./_registry.ts";
+export declare const f: {
+    readonly text: (label?: string) => FieldMeta;
+    readonly longtext: (label?: string) => FieldMeta;
+    readonly richtext: (label?: string) => FieldMeta;
+    readonly url: (label?: string) => FieldMeta;
+    readonly image: (label?: string, imageSpec?: ImageSpec) => FieldMeta;
+    readonly imageAlt: (label?: string) => FieldMeta;
+    readonly headingLevel: () => FieldMeta;
+};
+export declare const DEFAULT_HEADING_LEVELS: Record<string, string>;
+export declare function resolveHeadingTag(blockType: string, props: Record<string, unknown>): string;
+/** Resolve the heading tag one level below the section heading (for child items). */
+export declare function resolveItemHeadingTag(blockType: string, props: Record<string, unknown>): string;

package/dist/blocks/_helpers.js

@@ -0,0 +1,26 @@
+export const f = {
+    text: (label) => ({ kind: "text", label }),
+    longtext: (label) => ({ kind: "text", label, multiline: true }),
+    richtext: (label) => ({ kind: "richtext", label }),
+    url: (label) => ({ kind: "url", label, inlineEditable: false }),
+    image: (label, imageSpec) => ({ kind: "image", label, inlineEditable: false, ...(imageSpec ? { imageSpec } : {}) }),
+    imageAlt: (label) => ({ kind: "imageAlt", label }),
+    headingLevel: () => ({ kind: "headingLevel", label: "Heading type", inlineEditable: false }),
+};
+export const DEFAULT_HEADING_LEVELS = {
+    Hero: "h1", FeatureGrid: "h2", Testimonials: "h2", FAQAccordion: "h2",
+    CTA: "h2", Card: "h3", CardGrid: "h2", RichText: "h2",
+    Stats: "h2", TwoColumn: "h2", Footer: "h4", Gallery: "h2",
+    Carousel: "h2", Tabs: "h2",
+};
+export function resolveHeadingTag(blockType, props) {
+    const v = props.headingLevel;
+    if (typeof v === "string" && /^h[1-6]$/.test(v))
+        return v;
+    return DEFAULT_HEADING_LEVELS[blockType] ?? "h2";
+}
+/** Resolve the heading tag one level below the section heading (for child items). */
+export function resolveItemHeadingTag(blockType, props) {
+    const level = parseInt(resolveHeadingTag(blockType, props)[1]);
+    return `h${Math.min(6, level + 1)}`;
+}

package/dist/blocks/_registry.d.ts

@@ -0,0 +1,116 @@
+import { z } from "zod";
+export declare const IMAGE_PLACEHOLDER = "/hero-generated.svg";
+export declare function isImagePlaceholder(url: string | undefined | null): boolean;
+/** Semantic kind for a block prop field. */
+export type FieldKind = "text" | "richtext" | "url" | "image" | "imageAlt" | "enum" | "color" | "number" | "boolean" | "headingLevel";
+/** Recommended image dimensions for an image field. */
+export type ImageSpec = {
+    aspectRatio: "landscape" | "square" | "portrait";
+    width: number;
+    height: number;
+    format?: "png" | "webp" | "jpeg";
+};
+/** Metadata for a single prop field on a block. */
+export type FieldMeta = {
+    kind: FieldKind;
+    /** Human-readable label (e.g. "Heading text"). Falls back to prop key. */
+    label?: string;
+    /** Whether this field supports inline editing in the preview. Defaults based on kind. */
+    inlineEditable?: boolean;
+    /** For enum kind: the allowed values. */
+    options?: string[];
+    /** For image kind: recommended dimensions and aspect ratio. */
+    imageSpec?: ImageSpec;
+    /** Render as a textarea in the PropertyPanel instead of a single-line input. */
+    multiline?: boolean;
+    /** Whether the field is required. Auto-derived from Zod schema at registration. */
+    required?: boolean;
+};
+/** Metadata for list-type props (features, items, cards). */
+export type ListFieldMeta = {
+    /** Display label for the list (e.g. "Features"). */
+    label?: string;
+    /** Field metadata for each item in the list. For polymorphic lists this is the
+     * union of all branch fields, used as a fallback when an item's discriminant
+     * value has no matching entry in `itemFieldsByType`. */
+    itemFields: Record<string, FieldMeta>;
+    /** For polymorphic (discriminated-union) lists: the item property whose value
+     * selects which field set to render (e.g. "component"). */
+    discriminator?: string;
+    /** For polymorphic lists: field metadata per discriminant value, so each item
+     * renders only the fields for its own type. */
+    itemFieldsByType?: Record<string, Record<string, FieldMeta>>;
+};
+/** Full metadata for a registered block type. */
+export type BlockMeta = {
+    displayName: string;
+    description?: string;
+    category?: "content" | "media" | "navigation" | "conversion" | "layout";
+    /** Chrome blocks (header/footer) are structurally pinned — not addable, movable, or removable. Editable via props only. */
+    chrome?: boolean;
+    /** Metadata for scalar (non-list) props. */
+    fields: Record<string, FieldMeta>;
+    /** Metadata for array/list props. */
+    listFields?: Record<string, ListFieldMeta>;
+};
+export type BlockType = string & {};
+export type BlockInstance = {
+    id: string;
+    type: BlockType;
+    props: Record<string, unknown>;
+};
+export type BlockRegistration = {
+    schema: z.ZodObject<any>;
+    meta: BlockMeta;
+};
+/**
+ * Register a block type. Can be called at module load time.
+ * Re-registering the same type overwrites the previous registration.
+ */
+export declare function registerBlock(type: string, config: BlockRegistration): void;
+/** Get metadata for a registered block type, or undefined. */
+export declare function getBlockMeta(type: string): BlockMeta | undefined;
+/** Get all registered block metadata. */
+export declare function getAllBlockMeta(): Readonly<Record<string, BlockMeta>>;
+/** Get the set of prop keys that are image fields for a block type. */
+export declare function getImageFields(blockType: string): Set<string>;
+/** Get list props that contain image fields: Map<listKey, Set<imageFieldKey>>. */
+export declare function getListImageFields(blockType: string): Map<string, Set<string>>;
+/** Check if a block type is a chrome block (structurally pinned). */
+export declare function isChrome(type: string): boolean;
+/** Get all registered chrome block type names. */
+export declare function getChromeTypes(): string[];
+/** Check if a field is inline-editable based on its metadata kind. */
+export declare function isFieldInlineEditable(type: string, fieldPath: string): boolean;
+/** Resolve the ImageSpec for a block field, handling both scalar and list item paths. */
+export declare function getImageSpec(blockType: string, fieldPath: string): ImageSpec | undefined;
+/**
+ * Block schemas keyed by type name.
+ * Prefer `registerBlock()` for new blocks; this object is kept for backwards compat.
+ */
+export declare const blockSchemas: Record<string, z.ZodObject<any, z.core.$strip>>;
+export declare const allowedBlockTypes: string[];
+export declare function getPropDisplayName(blockType: string | undefined, propKey: string): string;
+export declare function defaultListItemForBlock(type: BlockType, listKey: string): Record<string, unknown> | null;
+/** Base schema — accepts any block type. Used for ingesting external site content with custom blocks. */
+export declare const blockInstanceSchemaLenient: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+    props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+/** Strict variant — rejects block types not in the shared registry. */
+export declare const blockInstanceSchema: z.ZodObject<{
+    id: z.ZodString;
+    props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    type: z.ZodString;
+}, z.core.$strip>;
+export declare function validateBlockProps(type: string, props: unknown): z.ZodSafeParseSuccess<Record<string, unknown>> | {
+    success: false;
+    error: z.ZodError<unknown>;
+};
+/**
+ * Get a structural JSON schema for a registered block type.
+ * Strips validation constraints (minLength, etc.) — the editor only needs
+ * the shape to know which fields exist and their types.
+ */
+export declare function getBlockJsonSchema(type: string): Record<string, unknown> | undefined;