@avocadostudio-ai/shared 0.1.0 → 0.2.1

package/contract/operation.schema.json

@@ -41,6 +41,9 @@
                 },
                 "ogImage": {
                   "type": "string"
+                },
+                "path": {
+                  "type": "string"
                 }
               },
               "additionalProperties": false

package/dist/block-manifest.d.ts

@@ -1,12 +1,261 @@
 import { z } from "zod";
 import type { FieldMeta, ListFieldMeta } from "./blocks/_registry.ts";
 export declare const jsonSchemaLikeSchema: z.ZodType<Record<string, unknown>>;
+/**
+ * Field metadata a site may declare alongside the JSON schema.
+ *
+ * JSON Schema describes what a value *is*; this describes how a person edits
+ * it, and the two are not the same question. A one-word headline and a six
+ * sentence body are both `{"type":"string"}`, so a manifest carrying only the
+ * schema gives them the same one-line input — which is exactly what happened to
+ * every integration with a real prose field. `kind` and `multiline` have no
+ * JSON Schema spelling, so they have to travel beside it.
+ */
+export declare const fieldMetaSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        number: "number";
+        boolean: "boolean";
+        enum: "enum";
+        text: "text";
+        richtext: "richtext";
+        url: "url";
+        image: "image";
+        imageAlt: "imageAlt";
+        color: "color";
+        headingLevel: "headingLevel";
+    }>;
+    label: z.ZodOptional<z.ZodString>;
+    inlineEditable: z.ZodOptional<z.ZodBoolean>;
+    options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    imageSpec: z.ZodOptional<z.ZodObject<{
+        aspectRatio: z.ZodEnum<{
+            landscape: "landscape";
+            square: "square";
+            portrait: "portrait";
+        }>;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        format: z.ZodOptional<z.ZodEnum<{
+            png: "png";
+            webp: "webp";
+            jpeg: "jpeg";
+        }>>;
+    }, z.core.$strip>>;
+    multiline: z.ZodOptional<z.ZodBoolean>;
+    inline: z.ZodOptional<z.ZodBoolean>;
+    decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    required: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const listFieldMetaSchema: z.ZodObject<{
+    label: z.ZodOptional<z.ZodString>;
+    itemFields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        kind: z.ZodEnum<{
+            number: "number";
+            boolean: "boolean";
+            enum: "enum";
+            text: "text";
+            richtext: "richtext";
+            url: "url";
+            image: "image";
+            imageAlt: "imageAlt";
+            color: "color";
+            headingLevel: "headingLevel";
+        }>;
+        label: z.ZodOptional<z.ZodString>;
+        inlineEditable: z.ZodOptional<z.ZodBoolean>;
+        options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        imageSpec: z.ZodOptional<z.ZodObject<{
+            aspectRatio: z.ZodEnum<{
+                landscape: "landscape";
+                square: "square";
+                portrait: "portrait";
+            }>;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            format: z.ZodOptional<z.ZodEnum<{
+                png: "png";
+                webp: "webp";
+                jpeg: "jpeg";
+            }>>;
+        }, z.core.$strip>>;
+        multiline: z.ZodOptional<z.ZodBoolean>;
+        inline: z.ZodOptional<z.ZodBoolean>;
+        decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            title: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        required: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    discriminator: z.ZodOptional<z.ZodString>;
+    itemFieldsByType: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodObject<{
+        kind: z.ZodEnum<{
+            number: "number";
+            boolean: "boolean";
+            enum: "enum";
+            text: "text";
+            richtext: "richtext";
+            url: "url";
+            image: "image";
+            imageAlt: "imageAlt";
+            color: "color";
+            headingLevel: "headingLevel";
+        }>;
+        label: z.ZodOptional<z.ZodString>;
+        inlineEditable: z.ZodOptional<z.ZodBoolean>;
+        options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        imageSpec: z.ZodOptional<z.ZodObject<{
+            aspectRatio: z.ZodEnum<{
+                landscape: "landscape";
+                square: "square";
+                portrait: "portrait";
+            }>;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            format: z.ZodOptional<z.ZodEnum<{
+                png: "png";
+                webp: "webp";
+                jpeg: "jpeg";
+            }>>;
+        }, z.core.$strip>>;
+        multiline: z.ZodOptional<z.ZodBoolean>;
+        inline: z.ZodOptional<z.ZodBoolean>;
+        decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            title: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        required: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>>;
+}, z.core.$strip>;
 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>>;
+    fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        kind: z.ZodEnum<{
+            number: "number";
+            boolean: "boolean";
+            enum: "enum";
+            text: "text";
+            richtext: "richtext";
+            url: "url";
+            image: "image";
+            imageAlt: "imageAlt";
+            color: "color";
+            headingLevel: "headingLevel";
+        }>;
+        label: z.ZodOptional<z.ZodString>;
+        inlineEditable: z.ZodOptional<z.ZodBoolean>;
+        options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        imageSpec: z.ZodOptional<z.ZodObject<{
+            aspectRatio: z.ZodEnum<{
+                landscape: "landscape";
+                square: "square";
+                portrait: "portrait";
+            }>;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            format: z.ZodOptional<z.ZodEnum<{
+                png: "png";
+                webp: "webp";
+                jpeg: "jpeg";
+            }>>;
+        }, z.core.$strip>>;
+        multiline: z.ZodOptional<z.ZodBoolean>;
+        inline: z.ZodOptional<z.ZodBoolean>;
+        decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            title: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        required: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    listFields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        label: z.ZodOptional<z.ZodString>;
+        itemFields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            kind: z.ZodEnum<{
+                number: "number";
+                boolean: "boolean";
+                enum: "enum";
+                text: "text";
+                richtext: "richtext";
+                url: "url";
+                image: "image";
+                imageAlt: "imageAlt";
+                color: "color";
+                headingLevel: "headingLevel";
+            }>;
+            label: z.ZodOptional<z.ZodString>;
+            inlineEditable: z.ZodOptional<z.ZodBoolean>;
+            options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            imageSpec: z.ZodOptional<z.ZodObject<{
+                aspectRatio: z.ZodEnum<{
+                    landscape: "landscape";
+                    square: "square";
+                    portrait: "portrait";
+                }>;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+                format: z.ZodOptional<z.ZodEnum<{
+                    png: "png";
+                    webp: "webp";
+                    jpeg: "jpeg";
+                }>>;
+            }, z.core.$strip>>;
+            multiline: z.ZodOptional<z.ZodBoolean>;
+            inline: z.ZodOptional<z.ZodBoolean>;
+            decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                title: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+            required: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+        discriminator: z.ZodOptional<z.ZodString>;
+        itemFieldsByType: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodObject<{
+            kind: z.ZodEnum<{
+                number: "number";
+                boolean: "boolean";
+                enum: "enum";
+                text: "text";
+                richtext: "richtext";
+                url: "url";
+                image: "image";
+                imageAlt: "imageAlt";
+                color: "color";
+                headingLevel: "headingLevel";
+            }>;
+            label: z.ZodOptional<z.ZodString>;
+            inlineEditable: z.ZodOptional<z.ZodBoolean>;
+            options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            imageSpec: z.ZodOptional<z.ZodObject<{
+                aspectRatio: z.ZodEnum<{
+                    landscape: "landscape";
+                    square: "square";
+                    portrait: "portrait";
+                }>;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+                format: z.ZodOptional<z.ZodEnum<{
+                    png: "png";
+                    webp: "webp";
+                    jpeg: "jpeg";
+                }>>;
+            }, z.core.$strip>>;
+            multiline: z.ZodOptional<z.ZodBoolean>;
+            inline: z.ZodOptional<z.ZodBoolean>;
+            decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                title: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+            required: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>>;
+    }, z.core.$strip>>>;
+    category: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    chrome: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export declare const blockManifestSchema: z.ZodObject<{
     version: z.ZodNumber;
@@ -16,13 +265,207 @@ export declare const blockManifestSchema: z.ZodObject<{
         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>>;
+        fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            kind: z.ZodEnum<{
+                number: "number";
+                boolean: "boolean";
+                enum: "enum";
+                text: "text";
+                richtext: "richtext";
+                url: "url";
+                image: "image";
+                imageAlt: "imageAlt";
+                color: "color";
+                headingLevel: "headingLevel";
+            }>;
+            label: z.ZodOptional<z.ZodString>;
+            inlineEditable: z.ZodOptional<z.ZodBoolean>;
+            options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            imageSpec: z.ZodOptional<z.ZodObject<{
+                aspectRatio: z.ZodEnum<{
+                    landscape: "landscape";
+                    square: "square";
+                    portrait: "portrait";
+                }>;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+                format: z.ZodOptional<z.ZodEnum<{
+                    png: "png";
+                    webp: "webp";
+                    jpeg: "jpeg";
+                }>>;
+            }, z.core.$strip>>;
+            multiline: z.ZodOptional<z.ZodBoolean>;
+            inline: z.ZodOptional<z.ZodBoolean>;
+            decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                title: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+            required: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+        listFields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            label: z.ZodOptional<z.ZodString>;
+            itemFields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                kind: z.ZodEnum<{
+                    number: "number";
+                    boolean: "boolean";
+                    enum: "enum";
+                    text: "text";
+                    richtext: "richtext";
+                    url: "url";
+                    image: "image";
+                    imageAlt: "imageAlt";
+                    color: "color";
+                    headingLevel: "headingLevel";
+                }>;
+                label: z.ZodOptional<z.ZodString>;
+                inlineEditable: z.ZodOptional<z.ZodBoolean>;
+                options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                imageSpec: z.ZodOptional<z.ZodObject<{
+                    aspectRatio: z.ZodEnum<{
+                        landscape: "landscape";
+                        square: "square";
+                        portrait: "portrait";
+                    }>;
+                    width: z.ZodNumber;
+                    height: z.ZodNumber;
+                    format: z.ZodOptional<z.ZodEnum<{
+                        png: "png";
+                        webp: "webp";
+                        jpeg: "jpeg";
+                    }>>;
+                }, z.core.$strip>>;
+                multiline: z.ZodOptional<z.ZodBoolean>;
+                inline: z.ZodOptional<z.ZodBoolean>;
+                decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    name: z.ZodString;
+                    title: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>>;
+                required: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>>;
+            discriminator: z.ZodOptional<z.ZodString>;
+            itemFieldsByType: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodObject<{
+                kind: z.ZodEnum<{
+                    number: "number";
+                    boolean: "boolean";
+                    enum: "enum";
+                    text: "text";
+                    richtext: "richtext";
+                    url: "url";
+                    image: "image";
+                    imageAlt: "imageAlt";
+                    color: "color";
+                    headingLevel: "headingLevel";
+                }>;
+                label: z.ZodOptional<z.ZodString>;
+                inlineEditable: z.ZodOptional<z.ZodBoolean>;
+                options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                imageSpec: z.ZodOptional<z.ZodObject<{
+                    aspectRatio: z.ZodEnum<{
+                        landscape: "landscape";
+                        square: "square";
+                        portrait: "portrait";
+                    }>;
+                    width: z.ZodNumber;
+                    height: z.ZodNumber;
+                    format: z.ZodOptional<z.ZodEnum<{
+                        png: "png";
+                        webp: "webp";
+                        jpeg: "jpeg";
+                    }>>;
+                }, z.core.$strip>>;
+                multiline: z.ZodOptional<z.ZodBoolean>;
+                inline: z.ZodOptional<z.ZodBoolean>;
+                decorators: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    name: z.ZodString;
+                    title: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>>;
+                required: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>>>;
+        }, z.core.$strip>>>;
+        category: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        chrome: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type BlockDefinition = z.infer<typeof blockDefinitionSchema>;
 export type BlockManifest = z.infer<typeof blockManifestSchema>;
+/** Where a value stopped matching its schema, and why. */
+export type ManifestSchemaIssue = {
+    path: string;
+    message: string;
+};
+/**
+ * Validate, and say what went wrong.
+ *
+ * The boolean form below could only report "does not match block manifest
+ * schema" — which is what an integrator saw when a plan wrote one prop of the
+ * wrong type, on a block with a dozen of them. The same failing patch reported
+ * through the registered-schema path said "bullets: expected string, received
+ * array". Two validators, one useless message, and the useful one was the path
+ * NOT taken when a manifest was supplied — so custom blocks, the case that
+ * needs the detail most, got the least.
+ *
+ * Returns the first issue found, or null when the value matches. It reports on
+ * exactly the constraints the boolean form enforced, with one deliberate
+ * loosening since — a key holding `undefined` counts as absent, see below.
+ * Note that `enum` and `const` are among the constraints it does not enforce —
+ * a value outside a declared enum still passes here.
+ */
+export declare function findManifestSchemaIssue(schema: Record<string, unknown>, value: unknown, path?: string): ManifestSchemaIssue | null;
 export declare function validateByJsonSchemaLike(schema: Record<string, unknown>, value: unknown): boolean;
+/**
+ * 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.
+ */
+export declare function isProseMirrorDocSchema(schema: 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;
+/**
+ * The field metadata a manifest block should actually be edited with.
+ *
+ * Derived from the JSON schema, then refined by whatever the definition
+ * declared. Every surface that renders a manifest block — the property panel,
+ * the Puck adapter, the planner's block contracts, an integration's own
+ * boundary code — has to agree on this, so it lives here rather than being
+ * re-derived four times with four sets of assumptions.
+ *
+ * Two rules:
+ *
+ * - `propsSchema` decides *which* props exist. A declared entry for a key the
+ *   schema does not expose is ignored, not added — otherwise a stale manifest
+ *   would put a control on a prop the block cannot store.
+ * - A declared entry is merged *over* the derived one, key by key, so a site
+ *   can supply just `multiline` and keep the label and options that were
+ *   inferred for it.
+ */
+export declare function resolveManifestFieldMeta(definition: {
+    propsSchema: Record<string, unknown>;
+    fields?: Record<string, unknown>;
+    listFields?: Record<string, unknown>;
+}): {
+    fields: Record<string, FieldMeta>;
+    listFields: Record<string, ListFieldMeta>;
+};
+/**
+ * Build a manifest describing every block type registered in THIS process.
+ *
+ * Built fresh on every call rather than memoised, because the registry is not
+ * fixed at module load: a site's custom blocks call `registerBlock()` from its
+ * own `blocks/register.ts`, which may run after this module was first imported.
+ * A cached manifest is a manifest missing exactly the blocks the caller most
+ * needs to know about.
+ *
+ * This lives in `shared`, not in the SDK, because two very different consumers
+ * need the same answer. The editor asks the *site* for it over
+ * `/api/editor/blocks`; an MCP agent asks the *orchestrator*, which in library
+ * mode is mounted in that same site process and so shares its registry. Keeping
+ * one builder is what makes those two answers the same answer.
+ */
+export declare function buildBlockManifest(): BlockManifest;