@avocadostudio-ai/orchestrator-core 0.1.0 → 0.2.0

package/dist/http/telemetry-feedback-actions.js

@@ -0,0 +1,68 @@
+/**
+ * Thumbs-up / thumbs-down on a chat trace, as transport-agnostic actions.
+ *
+ * `POST /telemetry/chat/feedback` was written inline in
+ * `apps/orchestrator/src/index.ts` rather than in a route plugin, so library
+ * mode — `createOrchestrator()` in the site SDK, which reimplements by hand
+ * whichever routes somebody remembered to add — never got it. The editor sends
+ * the rating best-effort and ignores the response, so on a library-mode site
+ * every thumb the user clicked was answered "not handled by
+ * createOrchestrator()" and silently thrown away: the UI kept showing the
+ * button as accepted and no signal ever reached the store.
+ *
+ * A second hand-kept copy would drift the way the first one did, so the
+ * validation lives here and both transports call it. Each function returns the
+ * status code and body to send; neither Fastify nor `Response` appears in this
+ * file.
+ */
+import { randomUUID } from "node:crypto";
+const badRequest = (error) => ({ code: 400, body: { error } });
+/** Free-text notes are stored verbatim in an append-only file, so cap what one row can cost. */
+const NOTE_MAX_CHARS = 2000;
+/**
+ * Record one rating against a chat trace.
+ *
+ * The rating is compared against the two literals rather than merely checked
+ * for being a string: the store's readers filter and count by rating, and a
+ * third value would quietly split the totals. An unusable payload is rejected
+ * rather than stored partially, because the editor fires this and forgets it —
+ * a row nobody can attribute to a trace is worse than no row.
+ */
+export function telemetryFeedbackSubmitAction(raw, store) {
+    const body = (raw ?? {});
+    const traceId = typeof body.traceId === "string" ? body.traceId.trim() : "";
+    const session = typeof body.session === "string" ? body.session.trim() : "";
+    const rating = body.rating === "up" || body.rating === "down" ? body.rating : null;
+    const note = typeof body.note === "string" ? body.note.trim().slice(0, NOTE_MAX_CHARS) : undefined;
+    if (!traceId || !session || !rating) {
+        return badRequest("traceId, session, and rating ('up' | 'down') are required");
+    }
+    const entry = {
+        id: randomUUID(),
+        at: new Date().toISOString(),
+        traceId,
+        session,
+        rating,
+        ...(note ? { note } : {})
+    };
+    store.push(entry);
+    return { code: 200, body: { ok: true, id: entry.id } };
+}
+/**
+ * Read the ratings back, filtered.
+ *
+ * `limit` arrives as a query string over HTTP and as a number from anything
+ * calling this directly, so it is coerced here; the store clamps the range.
+ * Left absent rather than defaulted so the store's own default still applies.
+ */
+export function telemetryFeedbackListAction(query, store) {
+    return {
+        code: 200,
+        body: store.list({
+            session: query.session,
+            rating: query.rating,
+            traceId: query.traceId,
+            limit: query.limit !== undefined ? Number(query.limit) : undefined
+        })
+    };
+}

package/dist/http/unsplash-actions.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The Unsplash search proxy behind the editor's image picker, as a
+ * transport-agnostic action.
+ *
+ * It lived only in `apps/orchestrator/src/routes/media.ts`, wired straight into
+ * Fastify. Library mode — `createOrchestrator()` in the site SDK — serves the
+ * same editor from a plain `Request`/`Response` handler and reimplements
+ * whichever routes somebody remembered to add. It never had this one, so the
+ * picker's Unsplash tab, which `/status/planner` advertises from the very same
+ * `UNSPLASH_ACCESS_KEY`, rendered and then answered "not handled by
+ * createOrchestrator()".
+ *
+ * The route is entirely session-free: no SQLite, no runtime, nothing from
+ * `session-state.js`. That is why it can be dispatched before a host's
+ * orchestrator runtime is ready, and why this file needs no collaborators
+ * beyond an access key and a `fetch`.
+ */
+import type { Logger } from "../logger.js";
+import type { ActionResult } from "./history-actions.js";
+export type { ActionResult };
+/**
+ * Raw query values, straight off the wire.
+ *
+ * Fastify hands these over as strings; `Object.fromEntries(url.searchParams)`
+ * does the same. Numbers are accepted too so a direct caller (a test, an MCP
+ * tool) doesn't have to stringify first.
+ */
+export type UnsplashSearchQuery = {
+    q?: string;
+    limit?: string | number;
+    page?: string | number;
+};
+export type UnsplashSearchDeps = {
+    /** Overrides `process.env.UNSPLASH_ACCESS_KEY`. An empty string means "not configured". */
+    accessKey?: string;
+    /** Seam for tests: the whole point of this action is that it can be exercised without the network. */
+    fetchImpl?: typeof fetch;
+    log?: Logger;
+};
+/** One picker row. `thumbUrl` falls back to the full image when Unsplash omits the small variant. */
+export type UnsplashSearchItem = {
+    id: string;
+    imageUrl: string;
+    thumbUrl: string;
+    alt: string;
+    author: string;
+};
+export type UnsplashSearchBody = {
+    items: UnsplashSearchItem[];
+    totalPages: number;
+};
+/**
+ * Search Unsplash for picker candidates.
+ *
+ * Every failure that isn't "no key at all" answers 200 with an empty result
+ * set. That is deliberately preserved: both clients — the editor's
+ * ImagePickerModal and the immersive widget's — read `{ items, totalPages }`
+ * off a successful response and treat a non-ok status as a hard error banner,
+ * so promoting an upstream 403 to a 5xx here would turn a rate limit into a
+ * broken tab. The cost is that a revoked key looks exactly like "no photos
+ * match", which is invisible in both transports — hence the `log.warn`, the one
+ * thing this action adds over the Fastify original.
+ */
+export declare function unsplashSearchAction(query: UnsplashSearchQuery, deps?: UnsplashSearchDeps): Promise<ActionResult>;

package/dist/http/unsplash-actions.js

@@ -0,0 +1,81 @@
+/**
+ * The Unsplash search proxy behind the editor's image picker, as a
+ * transport-agnostic action.
+ *
+ * It lived only in `apps/orchestrator/src/routes/media.ts`, wired straight into
+ * Fastify. Library mode — `createOrchestrator()` in the site SDK — serves the
+ * same editor from a plain `Request`/`Response` handler and reimplements
+ * whichever routes somebody remembered to add. It never had this one, so the
+ * picker's Unsplash tab, which `/status/planner` advertises from the very same
+ * `UNSPLASH_ACCESS_KEY`, rendered and then answered "not handled by
+ * createOrchestrator()".
+ *
+ * The route is entirely session-free: no SQLite, no runtime, nothing from
+ * `session-state.js`. That is why it can be dispatched before a host's
+ * orchestrator runtime is ready, and why this file needs no collaborators
+ * beyond an access key and a `fetch`.
+ */
+// A fresh object each time: a single shared literal would let one caller's
+// mutation of the response body leak into every later empty result.
+const empty = () => ({ code: 200, body: { items: [], totalPages: 0 } });
+/**
+ * Search Unsplash for picker candidates.
+ *
+ * Every failure that isn't "no key at all" answers 200 with an empty result
+ * set. That is deliberately preserved: both clients — the editor's
+ * ImagePickerModal and the immersive widget's — read `{ items, totalPages }`
+ * off a successful response and treat a non-ok status as a hard error banner,
+ * so promoting an upstream 403 to a 5xx here would turn a rate limit into a
+ * broken tab. The cost is that a revoked key looks exactly like "no photos
+ * match", which is invisible in both transports — hence the `log.warn`, the one
+ * thing this action adds over the Fastify original.
+ */
+export async function unsplashSearchAction(query, deps = {}) {
+    const accessKey = (deps.accessKey ?? process.env.UNSPLASH_ACCESS_KEY)?.trim();
+    if (!accessKey)
+        return { code: 404, body: { error: "Unsplash not configured" } };
+    const q = typeof query.q === "string" ? query.q.trim() : "";
+    if (!q)
+        return empty();
+    // `Number("") || 8` is why an absent or unparseable value lands on the
+    // default rather than on NaN; the clamp then keeps a hand-edited URL from
+    // asking Unsplash for a page size it will reject outright.
+    const limit = Math.min(20, Math.max(1, Number(query.limit) || 8));
+    const page = Math.max(1, Math.trunc(Number(query.page) || 1));
+    const doFetch = deps.fetchImpl ?? fetch;
+    try {
+        const endpoint = `https://api.unsplash.com/search/photos?query=${encodeURIComponent(q)}&orientation=landscape&per_page=${limit}&page=${page}&content_filter=high`;
+        const res = await doFetch(endpoint, {
+            headers: { Authorization: `Client-ID ${accessKey}`, "Accept-Version": "v1" }
+        });
+        if (!res.ok) {
+            deps.log?.warn({ status: res.status, q }, "unsplash search failed; returning an empty result set");
+            return empty();
+        }
+        const payload = (await res.json());
+        const items = (payload.results ?? [])
+            .map((r) => {
+            const imageUrl = typeof r.urls?.regular === "string" ? r.urls.regular : "";
+            const thumbUrl = typeof r.urls?.small === "string" ? r.urls.small : imageUrl;
+            return {
+                id: r.id ?? "",
+                imageUrl,
+                thumbUrl,
+                alt: typeof r.alt_description === "string"
+                    ? r.alt_description
+                    : typeof r.description === "string"
+                        ? r.description
+                        : "",
+                author: r.user?.name ?? "Unsplash"
+            };
+        })
+            // A row with no id or no URL cannot be selected or rendered, so it would
+            // only ever show up as a broken tile.
+            .filter((item) => item.id && item.imageUrl);
+        return { code: 200, body: { items, totalPages: payload.total_pages ?? 0 } };
+    }
+    catch (err) {
+        deps.log?.warn({ err, q }, "unsplash search threw; returning an empty result set");
+        return empty();
+    }
+}

package/dist/http/variations-actions.d.ts

@@ -0,0 +1,102 @@
+/**
+ * "Give me three ways to word this hero" — the variations endpoints, as
+ * transport-agnostic actions.
+ *
+ * The pipeline itself already lives in core and already speaks `{ code,
+ * payload }`. What was still duplicated is everything around it: the 400 body
+ * for a malformed request, and — worse — the SSE *frame vocabulary* of the
+ * streaming variant, which existed only inside the Fastify handler. Library
+ * mode (`createOrchestrator()` in the site SDK) answered "not handled" for both
+ * routes, so a second transport had to invent `variations_ready` /
+ * `image_resolved` / `done` / `error` from scratch and stay in step with a
+ * client that parses the frames by hand. Frame names drift silently: nothing
+ * type-checks a string written on one side of a socket against the string read
+ * on the other.
+ *
+ * So the frames are built here, once, and `formatVariationFrame` writes the
+ * wire bytes for callers that don't already have an SSE writer. Neither Fastify
+ * nor `Response` appears in this file.
+ */
+import { type VariationRequestBody, type VariationPipelineContext, type VariationResult, type VariationImageUpdate } from "../chat/variation-pipeline.js";
+import type { ActionResult } from "./history-actions.js";
+export type { ActionResult };
+export type { VariationRequestBody, VariationPipelineContext };
+export type ParsedVariationRequest = {
+    ok: true;
+    body: VariationRequestBody;
+} | {
+    ok: false;
+    result: ActionResult;
+};
+/**
+ * Validate a raw request body, kept deliberately separate from the actions.
+ *
+ * Both transports need to do work *between* parsing and running: library mode
+ * awaits its bootstrap cache so the adapter's pages are in session state before
+ * the pipeline reads them, and it can only do that once it knows the scoped
+ * session key. Folding the parse into the actions would either hide that step
+ * or force this file to know about an adapter it has no business knowing about.
+ */
+export declare function parseVariationRequest(raw: unknown): ParsedVariationRequest;
+/**
+ * The session key the pipeline should read and write under.
+ *
+ * Every route that touches session state scopes the raw `session` with the
+ * request's `siteId` before using it, and the variations routes are no
+ * exception: unscoped, a multi-site request reads a draft that belongs to
+ * nobody, so `getPage` misses and every variation request 404s. The
+ * normalization matters just as much — a request with no `session` at all
+ * becomes the default key here, where leaving it `undefined` would instead trip
+ * the pipeline's "session, slug, and message are required" guard and skip
+ * `rememberVariations`, so a follow-up "regenerate" would read an empty cache.
+ *
+ * `siteIdOverride` exists for library mode, which pins the site from
+ * `createOrchestrator()` config and deliberately ignores whatever `siteId` the
+ * body carries; scoping from the body there would address a different session
+ * than the one its bootstrap cache just filled.
+ */
+export declare function scopeVariationSession(body: VariationRequestBody, siteIdOverride?: string): string;
+/**
+ * Generate variations and return them in one response.
+ *
+ * `session` is a separate required argument rather than something read off
+ * `body` because the two transports derive it differently (see
+ * `scopeVariationSession`) and a body whose `session` was never scoped
+ * type-checks perfectly — the mistake would only ever show up as an empty
+ * draft at runtime. Making it explicit is what stops a future call site from
+ * silently reintroducing that.
+ */
+export declare function variationsAction(ctx: VariationPipelineContext, body: VariationRequestBody, session: string): Promise<ActionResult>;
+/**
+ * The SSE frames the streaming variant emits, in the order they can occur:
+ * one `variations_ready` (text-only variants, so the modal can open in ~1s),
+ * then one `image_resolved` per variant as its image finishes, then exactly one
+ * terminal `done` or `error`.
+ *
+ * The `event` name travels *inside* the JSON payload rather than as an SSE
+ * `event:` line, because the client reads this with fetch + `getReader()`
+ * rather than `EventSource` and would never see the line.
+ */
+export type VariationStreamFrame = ({
+    event: "variations_ready";
+    imagesPending: boolean;
+} & VariationResult) | ({
+    event: "image_resolved";
+} & VariationImageUpdate) | ({
+    event: "done";
+} & VariationResult) | {
+    event: "error";
+    error: string;
+};
+/** The wire encoding of one frame. Identical to what `sseWrite` produces. */
+export declare function formatVariationFrame(frame: VariationStreamFrame): string;
+/**
+ * Generate variations, emitting frames as they become available.
+ *
+ * Resolves once the terminal frame has been emitted; ending the stream stays
+ * with the transport, which owns the socket and has to close it on client
+ * disconnect too. A thrown pipeline is reported as an `error` frame rather than
+ * rethrown: the response status is long since committed by the time images
+ * resolve, so the only way to tell the client anything is in-band.
+ */
+export declare function variationsStreamAction(ctx: VariationPipelineContext, body: VariationRequestBody, session: string, emit: (frame: VariationStreamFrame) => void): Promise<void>;

package/dist/http/variations-actions.js

@@ -0,0 +1,104 @@
+/**
+ * "Give me three ways to word this hero" — the variations endpoints, as
+ * transport-agnostic actions.
+ *
+ * The pipeline itself already lives in core and already speaks `{ code,
+ * payload }`. What was still duplicated is everything around it: the 400 body
+ * for a malformed request, and — worse — the SSE *frame vocabulary* of the
+ * streaming variant, which existed only inside the Fastify handler. Library
+ * mode (`createOrchestrator()` in the site SDK) answered "not handled" for both
+ * routes, so a second transport had to invent `variations_ready` /
+ * `image_resolved` / `done` / `error` from scratch and stay in step with a
+ * client that parses the frames by hand. Frame names drift silently: nothing
+ * type-checks a string written on one side of a socket against the string read
+ * on the other.
+ *
+ * So the frames are built here, once, and `formatVariationFrame` writes the
+ * wire bytes for callers that don't already have an SSE writer. Neither Fastify
+ * nor `Response` appears in this file.
+ */
+import { scopedSessionKey } from "../state/session-state.js";
+import { variationRequestBodySchema, runVariationPipeline, runVariationPipelineStreaming } from "../chat/variation-pipeline.js";
+/**
+ * Validate a raw request body, kept deliberately separate from the actions.
+ *
+ * Both transports need to do work *between* parsing and running: library mode
+ * awaits its bootstrap cache so the adapter's pages are in session state before
+ * the pipeline reads them, and it can only do that once it knows the scoped
+ * session key. Folding the parse into the actions would either hide that step
+ * or force this file to know about an adapter it has no business knowing about.
+ */
+export function parseVariationRequest(raw) {
+    const parsed = variationRequestBodySchema.safeParse(raw);
+    if (!parsed.success) {
+        return { ok: false, result: { code: 400, body: { error: "invalid request body", details: parsed.error.issues } } };
+    }
+    return { ok: true, body: parsed.data };
+}
+/**
+ * The session key the pipeline should read and write under.
+ *
+ * Every route that touches session state scopes the raw `session` with the
+ * request's `siteId` before using it, and the variations routes are no
+ * exception: unscoped, a multi-site request reads a draft that belongs to
+ * nobody, so `getPage` misses and every variation request 404s. The
+ * normalization matters just as much — a request with no `session` at all
+ * becomes the default key here, where leaving it `undefined` would instead trip
+ * the pipeline's "session, slug, and message are required" guard and skip
+ * `rememberVariations`, so a follow-up "regenerate" would read an empty cache.
+ *
+ * `siteIdOverride` exists for library mode, which pins the site from
+ * `createOrchestrator()` config and deliberately ignores whatever `siteId` the
+ * body carries; scoping from the body there would address a different session
+ * than the one its bootstrap cache just filled.
+ */
+export function scopeVariationSession(body, siteIdOverride) {
+    return scopedSessionKey(body.session, siteIdOverride ?? body.siteId);
+}
+/**
+ * Generate variations and return them in one response.
+ *
+ * `session` is a separate required argument rather than something read off
+ * `body` because the two transports derive it differently (see
+ * `scopeVariationSession`) and a body whose `session` was never scoped
+ * type-checks perfectly — the mistake would only ever show up as an empty
+ * draft at runtime. Making it explicit is what stops a future call site from
+ * silently reintroducing that.
+ */
+export async function variationsAction(ctx, body, session) {
+    const { code, payload } = await runVariationPipeline(ctx, { ...body, session });
+    return { code, body: payload };
+}
+/** The wire encoding of one frame. Identical to what `sseWrite` produces. */
+export function formatVariationFrame(frame) {
+    return `data: ${JSON.stringify(frame)}\n\n`;
+}
+/**
+ * Generate variations, emitting frames as they become available.
+ *
+ * Resolves once the terminal frame has been emitted; ending the stream stays
+ * with the transport, which owns the socket and has to close it on client
+ * disconnect too. A thrown pipeline is reported as an `error` frame rather than
+ * rethrown: the response status is long since committed by the time images
+ * resolve, so the only way to tell the client anything is in-band.
+ */
+export async function variationsStreamAction(ctx, body, session, emit) {
+    try {
+        const result = await runVariationPipelineStreaming(ctx, { ...body, session }, {
+            onInitial: (initial) => emit({ event: "variations_ready", ...initial }),
+            onImageResolved: (update) => emit({ event: "image_resolved", ...update })
+        });
+        // The `error` test is redundant with the status check — a 200 payload is
+        // always a VariationResult — but it is what narrows the union for the
+        // `done` spread below, so it stays.
+        if (result.code !== 200 || "error" in result.payload) {
+            emit({ event: "error", error: "error" in result.payload ? result.payload.error : "unknown" });
+            return;
+        }
+        emit({ event: "done", ...result.payload });
+    }
+    catch (err) {
+        ctx.log.warn({ err }, "variations stream failed");
+        emit({ event: "error", error: err instanceof Error ? err.message : "stream failed" });
+    }
+}

package/dist/index.d.ts

@@ -1 +1,4 @@
-export {};
+export { createOrchestrator, type CreateOrchestratorConfig, type OrchestratorHandler } from "./handler/create-orchestrator.ts";
+export type { OrchestratorAuth, AuthContext } from "./handler/auth.ts";
+export type { CmsAdapter, CmsCapabilities, CmsInlineAsset, CmsPublishContext, CmsPublishResult, CmsPerspective, CmsReadOptions, ResolvedCapabilities } from "./cms/adapter.ts";
+export { jsonFileAdapter, editorApiAdapter, resolveCapabilities, type JsonFileAdapterOptions, type EditorApiAdapterOptions } from "./cms/index.ts";

package/dist/index.js

@@ -1 +1,21 @@
-export {};
+// @avocadostudio-ai/orchestrator-core
+//
+// Transport-agnostic "brain" of the orchestrator: planner, ops engine, session
+// state, NLP, publish helpers, image generation, tools, telemetry, eval — plus
+// `createOrchestrator`, the Web-standard handler that mounts all of it at a
+// route in someone else's Next.js app.
+//
+// THIS FILE IS THE PACKAGE'S PUBLIC API. If a symbol is not exported here it is
+// not part of the contract, and a consumer installing from the registry cannot
+// reach it: `publishConfig.exports` lists `.` and `./cms` and nothing else.
+//
+// The development `exports` map still carries `"./*": "./src/*.ts"` wildcards,
+// because apps/orchestrator (the Fastify host, never published) resolves 99
+// files through them. That asymmetry is deliberate and guarded — see
+// packages/shared/src/published-exports.test.ts, which fails the build if a
+// wildcard reappears in publishConfig or if a published package deep-imports
+// another published package outside its published subpaths.
+//
+// The Fastify HTTP wrapper lives in apps/orchestrator and imports from here.
+export { createOrchestrator } from "./handler/create-orchestrator.js";
+export { jsonFileAdapter, editorApiAdapter, resolveCapabilities } from "./cms/index.js";

package/dist/nlp/deterministic-planner-refs.d.ts

@@ -6,7 +6,7 @@ export declare function resolveBlockRef(args: {
     activeBlockId?: string;
     fallbackType?: BlockType | null;
 }): PageDoc["blocks"][number] | null;
-export declare function ordinalToIndex(value: string): 1 | 0 | -1 | 2 | 3 | 4 | null;
+export declare function ordinalToIndex(value: string): 2 | 0 | 1 | -1 | 3 | 4 | null;
 export declare function resolveByDescriptor(args: {
     descriptor: string;
     currentPage: PageDoc;

package/dist/nlp/deterministic-planner-suggestions.d.ts

@@ -34,6 +34,16 @@ type BlockContract = {
     allowedProps: string[];
     required: string[];
     optional?: string[];
+    /**
+     * Props whose value is rendered as markdown, as `key` or `listKey[].key`.
+     *
+     * Without this the planner cannot tell `RichText.body` from `Hero.heading`:
+     * the contract carries prop *names* and nothing else, so the whole rich-text
+     * capability was invisible to chat and only reachable by hand in the property
+     * panel. Derived from field metadata rather than written by hand, so a block
+     * that gains a richtext field announces it without anyone remembering to.
+     */
+    richTextProps?: string[];
     notes: string;
 };
 /**

package/dist/nlp/deterministic-planner-suggestions.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { allowedBlockTypes, blockSchemas, getAllBlockMeta, getBlockMeta, getPropDisplayName, deriveFieldMetaFromSchema } from "@avocadostudio-ai/shared";
+import { allowedBlockTypes, blockSchemas, getAllBlockMeta, getBlockMeta, getPropDisplayName, resolveManifestFieldMeta } from "@avocadostudio-ai/shared";
 export function editablePropsFromBlock(block) {
     if (!block || !block.props || typeof block.props !== "object")
         return [];
@@ -463,10 +463,25 @@ const _blockNotes = {
     CardGrid: "cards is a non-empty array of {title, description, ctaText, ctaHref, imageUrl?, imageAlt?}. columns controls the grid layout: '2', '3' (default), or '4'. cardVariant can be 'default' or 'full-bleed' — applies to all cards in the grid. Use 'full-bleed' for background images with dark overlay and white text (requires imageUrl on cards). subtitle is optional.",
     Tabs: "tabs is a non-empty array of {label, content}. content supports richtext markdown. title is an optional section heading above the tab bar.",
     Banner: "Full-width announcement bar. variant sets preset theme: 'info' (default blue), 'success' (green), or 'warning' (amber). For custom brand colors, set backgroundColor and/or textColor (CSS color strings, e.g. '#1a1a2e' or 'rgb(26,26,46)'). Custom colors override the variant background/text. ctaText/ctaHref are optional: set both to show a button.",
-    FAQAccordion: "items is a non-empty array of {q, a}. The answer (a) supports richtext: **bold**, *italic*, [link](url), lists (- item), and paragraph breaks (\\n\\n).",
-    TwoColumn: "Image + text side-by-side layout. imagePosition is 'left' or 'right' (default 'right'). body supports inline markdown (**bold**, *italic*, [link](url)). ctaText/ctaHref are optional: set both to show a CTA button. For imageUrl: use any placeholder value (the system resolves images separately).",
+    FAQAccordion: "items is a non-empty array of {q, a}. The question (q) is plain text; the answer (a) is a richtext prop.",
+    TwoColumn: "Image + text side-by-side layout. left and right are arrays of typed children; each child's `type` decides how its `text` is read — for type 'paragraph' the text is rendered as markdown, for type 'heading' it is plain text. (That is why `text` is not listed in richTextProps: it depends on the sibling `type`.) ctaText/ctaHref are optional: set both to show a CTA button. For imageUrl: use any placeholder value (the system resolves images separately).",
     Footer: "columns must be a non-empty array of {title, links}. links is a string with one 'Label|URL' per line (use \\n to separate). Example: 'Home|/\\nAbout|/about\\nBlog|/blog'."
 };
+/** Collect the markdown-bearing props of a block, flat and list-item alike. */
+function collectRichTextProps(fields, listFields) {
+    const props = [];
+    for (const [key, field] of Object.entries(fields ?? {})) {
+        if (field.kind === "richtext")
+            props.push(key);
+    }
+    for (const [listKey, listMeta] of Object.entries(listFields ?? {})) {
+        for (const [itemKey, itemMeta] of Object.entries(listMeta.itemFields)) {
+            if (itemMeta.kind === "richtext")
+                props.push(`${listKey}[].${itemKey}`);
+        }
+    }
+    return props;
+}
 /**
  * Derive block contracts from the registry so new blocks are automatically
  * included without maintaining a parallel hardcoded map.
@@ -479,13 +494,19 @@ const _blockNotes = {
 export function blockContractsSummary(manifest) {
     const allMeta = getAllBlockMeta();
     const result = {};
-    // Build a lookup of manifest block types → propsSchema properties
+    /*
+     * A lookup of manifest block types → the whole definition, not just its
+     * properties. The definition may carry the site's own field metadata, and
+     * `kind` is what decides whether a prop is described to the planner as rich
+     * text — dropping it here is how a site's prose field ended up presented as
+     * a plain string in the block contract.
+     */
     const manifestByType = new Map();
     if (manifest) {
         for (const def of manifest.blocks) {
             const props = def.propsSchema?.properties;
             if (props && typeof props === "object" && !Array.isArray(props)) {
-                manifestByType.set(def.type, props);
+                manifestByType.set(def.type, def);
             }
         }
     }
@@ -508,9 +529,9 @@ export function blockContractsSummary(manifest) {
             }
         }
         // Merge manifest-declared props that the shared Zod schema doesn't know about
-        const manifestProps = manifestByType.get(type);
-        if (manifestProps) {
-            for (const key of Object.keys(manifestProps)) {
+        const manifestDef = manifestByType.get(type);
+        if (manifestDef) {
+            for (const key of Object.keys(manifestDef.propsSchema.properties ?? {})) {
                 if (!allProps.includes(key)) {
                     allProps.push(key);
                     optional.push(key);
@@ -556,12 +577,15 @@ export function blockContractsSummary(manifest) {
         };
         if (optional.length > 0)
             entry.optional = optional;
+        const richTextProps = collectRichTextProps(meta.fields, meta.listFields);
+        if (richTextProps.length > 0)
+            entry.richTextProps = richTextProps;
         result[type] = entry;
     }
     // Add manifest-only blocks (not in shared registry) — derive contracts from JSON schema
-    for (const [type, manifestProps] of manifestByType) {
-        const derived = deriveFieldMetaFromSchema({ type: "object", properties: manifestProps });
-        const allProps = Object.keys(manifestProps);
+    for (const [type, manifestDef] of manifestByType) {
+        const derived = resolveManifestFieldMeta(manifestDef);
+        const allProps = Object.keys(manifestDef.propsSchema.properties ?? {});
         // Derive list-field notes
         const listParts = [];
         for (const [listKey, listMeta] of Object.entries(derived.listFields)) {
@@ -569,9 +593,11 @@ export function blockContractsSummary(manifest) {
             listParts.push(`${listKey} must be a non-empty array of {${itemKeys}}`);
         }
         const autoNotes = listParts.length > 0 ? listParts.join(". ") + "." : `${type} block. Never invent prop names.`;
+        const manifestRichText = collectRichTextProps(derived.fields, derived.listFields);
         result[type] = {
             allowedProps: allProps,
             required: allProps, // conservative: treat all as required
+            ...(manifestRichText.length > 0 ? { richTextProps: manifestRichText } : {}),
             notes: autoNotes
         };
     }

package/dist/nlp/plan-normalizer.js

@@ -1,4 +1,4 @@
-import { allowedBlockTypes, defaultPropsForType as sharedDefaultPropsForType } from "@avocadostudio-ai/shared";
+import { allowedBlockTypes, declaredDefaultPropsForType, defaultPropsForType as sharedDefaultPropsForType } from "@avocadostudio-ai/shared";
 import { extractRouteMentions, firstRouteMention, normalizeRouteCandidate, parseCreatePageRequest } from "./intent-helpers.js";
 // ---------------------------------------------------------------------------
 // Op reordering: create_page must precede ops targeting the same slug
@@ -459,8 +459,24 @@ export function nextBlockId(type, page) {
 // ---------------------------------------------------------------------------
 // Default block props
 // ---------------------------------------------------------------------------
+/*
+ * Defaults to seed a newly planned block with, before the plan's own props are
+ * merged over the top.
+ *
+ * A block type the registry knows but that declares no defaults is a site's own
+ * block, and it gets nothing. The generic CTA-shaped fallback underneath
+ * `defaultPropsForType` is for a type nobody has registered — where anything
+ * renderable beats an empty block — and applying it to a registered custom
+ * block put a `title`, a `description` and a CTA into props whose schema has no
+ * such fields. On a site that registers its blocks with a catchall (the way
+ * they must, so chat edits don't strip props Avocado doesn't declare) those
+ * four keys are not rejected: they are stored, and travel back to the CMS.
+ */
 export function defaultPropsForType(type) {
-    return sharedDefaultPropsForType(type);
+    const declared = declaredDefaultPropsForType(type);
+    if (declared)
+        return declared;
+    return allowedBlockTypes.includes(type) ? {} : sharedDefaultPropsForType(type);
 }
 // ---------------------------------------------------------------------------
 // Patch helpers