@avocadostudio-ai/shared 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,7 +1,16 @@
 export { EDITOR_PROTOCOL_VERSION } from "./protocol.js";
 export { getConfiguredDraftSecret, getSafeInternalRedirectPath, validateDraftSecret } from "./draft-mode.js";
 export { isImagePath, toAltPath, setPropAtPath } from "./editable-path.js";
-export { blockDefinitionSchema, blockManifestSchema, jsonSchemaLikeSchema, validateByJsonSchemaLike, validateManifestDefaultProps, deriveFieldMetaFromSchema } from "./block-manifest.js";
+/*
+ * The rich-text grammar lives in `@avocadostudio-ai/richtext`, which owns the
+ * parser and every CMS converter and has no dependencies of its own. It is
+ * re-exported here because the renderers, the overlay and the Puck adapter all
+ * already import it from `shared` — moving the source should not move every
+ * call site. New code that only needs the grammar should depend on the
+ * richtext package directly.
+ */
+export { parseInline, parseRichText, parseRichTextBlocks, normalizeRichTextBody, resolveRichTextHeadingLevel, clampMarkdownHeadings, unescapeMarkdownText, isRichTextDoc, fromMarkdown, toMarkdown, mergeRichTextDoc, NODE, MARK } from "@avocadostudio-ai/richtext";
+export { blockDefinitionSchema, blockManifestSchema, buildBlockManifest, jsonSchemaLikeSchema, validateByJsonSchemaLike, findManifestSchemaIssue, validateManifestDefaultProps, deriveFieldMetaFromSchema, resolveManifestFieldMeta, isProseMirrorDocSchema } from "./block-manifest.js";
 export { 
 // Constants & helpers
 IMAGE_PLACEHOLDER, isImagePlaceholder, 
@@ -9,11 +18,13 @@ IMAGE_PLACEHOLDER, isImagePlaceholder,
 registerBlock, getBlockMeta, getAllBlockMeta, getImageFields, getListImageFields, isFieldInlineEditable, getImageSpec, isChrome, getChromeTypes, 
 // Backwards-compatible exports
 blockSchemas, allowedBlockTypes, 
+// The catalogue a site actually renders — see `declareBlockCatalogue`
+declareBlockCatalogue, getBlockCatalogue, isInBlockCatalogue, catalogueBlockTypes, undeclaredBlockTypes, 
 // Utility functions
 getPropDisplayName, defaultListItemForBlock, 
 // Schemas & validation
 blockInstanceSchema, blockInstanceSchemaLenient, validateBlockProps, getBlockJsonSchema, } from "./blocks/_registry.js";
-export { defaultPropsForType, resolveHeadingTag, resolveItemHeadingTag, DEFAULT_HEADING_LEVELS, } from "./blocks/index.js";
+export { defaultPropsForType, declaredDefaultPropsForType, resolveHeadingTag, resolveItemHeadingTag, DEFAULT_HEADING_LEVELS, } from "./blocks/index.js";
 export { blockTypeToCamel, camelToBlockType, blockTypeToLower, lowerToBlockType, } from "./block-names.js";
 export { makeAddBlock, generateBlockId, makeAddItem, generateItemId, ensureItemIds, } from "./ops/builders.js";
 export { THEME_TOKEN_TO_CSS_VARS, themeTokenKeys, semanticThemeTokensSchema, mapSemanticThemeTokens, } from "./ops/theme-tokens.js";

package/dist/ops/builders.d.ts

@@ -12,9 +12,14 @@ export type MakeAddBlockOptions = {
 /**
  * Build a canonical `add_block` op from a block type and partial props.
  *
- * The returned op's `block` merges `defaultPropsForType(type)` with `partialProps`
- * (partial wins) and carries a generated id, so it is valid against the strict
- * operation schema and ready to send to the orchestrator.
+ * The returned op's `block` merges the type's declared defaults with
+ * `partialProps` (partial wins) and carries a generated id, so it is valid
+ * against the strict operation schema and ready to send to the orchestrator.
+ *
+ * A type that declares no defaults — every block a site registers itself —
+ * contributes nothing, so the op carries exactly the props the caller passed.
+ * The alternative is worse than empty: the generic fallback would add a
+ * `title`, `description` and CTA the site's block has no field for.
  *
  * @example
  * makeAddBlock("/", "Hero", { heading: "Welcome" })

package/dist/ops/builders.js

@@ -8,20 +8,25 @@
 // must mint an id and supply a full prop set.
 //
 // `makeAddBlock` closes that gap without denormalizing the op: it generates a
-// collision-resistant id and fills `defaultPropsForType(type)` under any
+// collision-resistant id and fills the type's declared defaults under any
 // partial props you pass, returning a canonical, schema-valid `add_block`.
 //
 // External integrators: prefer this over hand-constructing the op (and never
 // hand-write the `Operation` union — import it from this package, or validate
 // against `contract/operation.schema.json`).
 import { getBlockMeta } from "./../blocks/_registry.js";
-import { defaultPropsForType } from "../blocks/index.js";
+import { declaredDefaultPropsForType } from "../blocks/index.js";
 /**
  * Build a canonical `add_block` op from a block type and partial props.
  *
- * The returned op's `block` merges `defaultPropsForType(type)` with `partialProps`
- * (partial wins) and carries a generated id, so it is valid against the strict
- * operation schema and ready to send to the orchestrator.
+ * The returned op's `block` merges the type's declared defaults with
+ * `partialProps` (partial wins) and carries a generated id, so it is valid
+ * against the strict operation schema and ready to send to the orchestrator.
+ *
+ * A type that declares no defaults — every block a site registers itself —
+ * contributes nothing, so the op carries exactly the props the caller passed.
+ * The alternative is worse than empty: the generic fallback would add a
+ * `title`, `description` and CTA the site's block has no field for.
  *
  * @example
  * makeAddBlock("/", "Hero", { heading: "Welcome" })
@@ -31,7 +36,7 @@ export function makeAddBlock(pageSlug, type, partialProps = {}, options = {}) {
     const block = {
         id: options.id ?? generateBlockId(type),
         type,
-        props: { ...defaultPropsForType(type), ...partialProps },
+        props: { ...declaredDefaultPropsForType(type), ...partialProps },
     };
     return options.afterBlockId
         ? { op: "add_block", pageSlug, afterBlockId: options.afterBlockId, block }

package/dist/schemas.d.ts

@@ -15,6 +15,8 @@ export type PageMeta = {
     title?: string;
     description?: string;
     ogImage?: string;
+    /** The public URL path, when it differs from the slug. See `pageMetaSchema`. */
+    path?: string;
 };
 export type PageDoc = {
     id: string;
@@ -28,6 +30,7 @@ export declare const pageMetaSchema: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
     ogImage: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 /** Lenient — accepts any block type (for ingesting content from sites with custom blocks). */
 export declare const pageDocSchemaLenient: z.ZodType<PageDoc>;
@@ -133,7 +136,7 @@ export declare const operationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         title: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
         ogImage: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>;
+    }, z.core.$strict>;
 }, z.core.$strip>, z.ZodObject<{
     op: z.ZodLiteral<"update_site_config">;
     patch: z.ZodObject<{
@@ -267,7 +270,7 @@ export declare const editPlanSchema: z.ZodObject<{
             title: z.ZodOptional<z.ZodString>;
             description: z.ZodOptional<z.ZodString>;
             ogImage: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>;
+        }, z.core.$strict>;
     }, z.core.$strip>, z.ZodObject<{
         op: z.ZodLiteral<"update_site_config">;
         patch: z.ZodObject<{

package/dist/schemas.js

@@ -18,7 +18,22 @@ export const siteConfigSchema = z.object({
 export const pageMetaSchema = z.object({
     title: z.string().optional(),
     description: z.string().optional(),
-    ogImage: z.string().optional()
+    ogImage: z.string().optional(),
+    /*
+     * The public path this page is served at, when that differs from its slug.
+     *
+     * Avocado has always treated the slug as the URL, which holds only while a
+     * site's routing is Avocado's. It is not for anything with a locale prefix,
+     * a basePath, or a CMS that owns its own routes: Paintball Arena Bern keeps
+     * one editable page per (document x language), so `/de/events` is a page
+     * identity, while the site serves German at the root and answers 404 for
+     * that path. An agent given the slug and told to open it goes to a 404 and
+     * has no way to know it was handed an id rather than a URL.
+     *
+     * Optional, and absent means "the slug is the path" — which stays true for
+     * every site whose routing Avocado does own.
+     */
+    path: z.string().optional()
 });
 const pageDocFields = {
     id: z.string().min(1),
@@ -165,13 +180,42 @@ const duplicatePageSchema = z.object({
     newTitle: z.string().min(1).optional(),
     afterPageSlug: z.string().min(1).optional()
 });
+const UPDATE_PAGE_META_KEYS = ["title", "description", "ogImage"];
+// The patch is strict, and carries its own wording, because stripping is what
+// made this unreadable. An agent that sent `path` here had the key dropped by
+// Zod before validation returned; the engine then reported a patch with no
+// defined keys and listed the three fields the caller had *not* sent, so the
+// only conclusion available was "path is unsettable for some other reason".
+//
+// `path` stays unsettable on purpose — it is the adapter's report of where the
+// site already serves a page, and Avocado cannot move a route it does not own
+// (see docs/ideas/page-identity-punch-list.md, PI-03/PI-07). What changes here
+// is that the refusal says so.
+//
+// The message must keep the word "invalid" and must avoid "not found",
+// "ambiguous", "unclear" and "no effective … change": classifyGuardrailError
+// (ops-engine.ts) matches on those keywords, and Zod's own "Unrecognized key"
+// text classifies as internal_error, which the planner's repair pass does not
+// retry. Only unrecognized keys are reworded — every other issue keeps Zod's
+// default, so a non-object patch still reads as a type error.
 const updatePageMetaSchema = z.object({
     op: z.literal("update_page_meta"),
     pageSlug: z.string().min(1),
-    patch: z.object({
+    patch: z.strictObject({
         title: z.string().optional(),
         description: z.string().optional(),
         ogImage: z.string().optional()
+    }, {
+        error: (issue) => {
+            if (issue.code !== "unrecognized_keys")
+                return undefined;
+            const keys = issue.keys;
+            const named = keys.map((key) => `\`${key}\``).join(", ");
+            const why = keys.includes("path")
+                ? " `path` reports where the site already serves this page and is supplied by the site's adapter, so Avocado cannot reassign it here."
+                : "";
+            return `Invalid update_page_meta patch: unrecognized key ${named}. This patch accepts ${UPDATE_PAGE_META_KEYS.join(", ")}.${why}`;
+        }
     })
 });
 const updateSiteConfigSchema = z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/shared",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,7 +18,8 @@
     "contract"
   ],
   "dependencies": {
-    "zod": "^4.3.6"
+    "zod": "^4.3.6",
+    "@avocadostudio-ai/richtext": "0.2.0"
   },
   "devDependencies": {
     "tsx": "^4.21.0",
@@ -33,7 +34,8 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
     "./contract/*": "./contract/*",
     "./package.json": "./package.json"
@@ -41,7 +43,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
-    "test": "NODE_ENV=test tsx --test src/**/*.test.ts",
+    "test": "NODE_ENV=test node ../../scripts/run-tests.mjs",
     "gen:contract": "tsx scripts/gen-contract.ts",
     "gen:contract:check": "tsx scripts/gen-contract.ts --check"
   }