@avocadostudio-ai/site-sdk 0.1.0 → 0.2.1

package/dist/publish/field-diff.js

@@ -0,0 +1,252 @@
+/**
+ * Publishing an edited page back to a CMS, as a field-level diff.
+ *
+ * `onPublish(pages, config)` means "here are the full PageDocs, store them".
+ * That is implementable when the CMS shape *is* the editor shape — a JSON file
+ * — and not otherwise. Every real CMS read is a projection: an asset reference
+ * flattened to a URL string, a document reference resolved to an href for one
+ * language, a rich-text tree flattened to markdown. Writing the projection back
+ * replaces the reference with the flattening and destroys the document.
+ *
+ * So a real integration publishes a diff: walk the same field specs used to
+ * project, compare each field against the value it was projected from, and emit
+ * a set at the key-addressed path that owns it. The first integration to do
+ * this hand-wrote about 230 lines of it. This is that shape, generalised, so
+ * the next one does not.
+ *
+ * **What is here and what is not.** The mechanism is general: the walk, the
+ * unchanged-field skip, list items matched on a stable key rather than an
+ * index, routing a block's patches to a document other than the page's, and the
+ * vocabulary for reporting a change that cannot be expressed. The *inversions*
+ * are not, and cannot be — `rehydrate` undoes a projection only the integration
+ * knows it made. Neither is uploading an asset or re-resolving a reference;
+ * those are per-CMS capabilities, and until an integration has them the honest
+ * answer is `unsupported`, which is why that is a first-class result here
+ * rather than a thrown error.
+ */
+/**
+ * Sanity addresses array elements by `_key`, never by index — an index-addressed
+ * patch races any concurrent edit that reorders the array.
+ */
+export const sanityPaths = {
+    field: (prefix, field) => `${prefix}${field}`,
+    item: (prefix, field, key) => `${prefix}${field}[_key=="${key}"]`
+};
+/**
+ * Index addressing, for stores that have no element identity (Strapi component
+ * lists, a plain JSON array). Correct only when the publish is the only writer:
+ * anything that reorders between read and write silently patches the wrong row,
+ * which is exactly what `_key` exists to prevent.
+ */
+export const indexPaths = {
+    field: (prefix, field) => `${prefix}${field}`,
+    item: (prefix, field, _key, index) => `${prefix}${field}[${index}]`
+};
+/** Structural equality, for "did this field actually change". */
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || a === undefined || b === null || b === undefined) {
+        return (a === null || a === undefined) && (b === null || b === undefined);
+    }
+    if (typeof a !== "object" || typeof b !== "object")
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    const ak = Object.keys(a);
+    const bk = Object.keys(b);
+    if (ak.length !== bk.length)
+        return false;
+    return ak.every((k) => deepEqual(a[k], b[k]));
+}
+function defaultItemKey(item) {
+    const key = item._key ?? item._id ?? item.id;
+    return typeof key === "string" && key.length > 0 ? key : undefined;
+}
+/**
+ * Diff one object's fields against the source it was projected from.
+ *
+ * `props` is what the editor holds; `source` is what the CMS holds. Recurses
+ * into list fields, matching items on their own key so a reorder upstream
+ * cannot make a patch land on the wrong row.
+ */
+export function diffFields(args) {
+    const paths = args.paths ?? sanityPaths;
+    const prefix = args.prefix ?? "";
+    const patches = [];
+    const unsupported = [];
+    const emit = (path, value) => patches.push({ documentId: args.documentId, path, value });
+    const reject = (where) => (change, remedy) => unsupported.push({ where, change, ...(remedy ? { remedy } : {}) });
+    for (const [name, spec] of Object.entries(args.specs)) {
+        const field = spec.cmsKey ?? name;
+        const before = args.source?.[name];
+        const after = spec.rehydrate(args.props, before, args.ctx);
+        if (deepEqual(before, after))
+            continue;
+        const path = paths.field(prefix, field);
+        if (spec.itemFields) {
+            const nested = diffList({
+                spec,
+                before,
+                after,
+                rows: args.props[name],
+                ctx: args.ctx,
+                documentId: args.documentId,
+                prefix,
+                field,
+                name,
+                where: args.where,
+                paths
+            });
+            patches.push(...nested.patches);
+            unsupported.push(...nested.unsupported);
+            continue;
+        }
+        if (typeof spec.write === "function") {
+            spec.write({ before, after, path, where: args.where, ctx: args.ctx, emit, reject: reject(args.where) });
+            continue;
+        }
+        emit(path, after);
+    }
+    return { patches, unsupported };
+}
+/**
+ * Cards, tiers, accordion rows — recursed into and matched on the item's own
+ * key.
+ *
+ * An item without one cannot be addressed, which is exactly the case of a row
+ * the editor added: the CMS has never seen it and has no key to patch. Adding
+ * and removing rows is a document-shaped write, not a field-shaped one, so it
+ * is reported rather than attempted.
+ */
+function diffList(args) {
+    const itemFields = args.spec.itemFields;
+    if (!itemFields)
+        return { patches: [], unsupported: [] };
+    const previous = Array.isArray(args.before) ? args.before : [];
+    const next = Array.isArray(args.after) ? args.after : [];
+    const rows = Array.isArray(args.rows) ? args.rows : [];
+    const keyOf = args.spec.itemKey ?? defaultItemKey;
+    const patches = [];
+    const unsupported = [];
+    if (previous.length !== next.length) {
+        unsupported.push({
+            where: args.where,
+            change: `items were added to or removed from "${args.name}"`,
+            remedy: "Only edits to existing items publish as a field diff; the list's length is a document-level change."
+        });
+    }
+    const byKey = new Map();
+    for (const entry of previous) {
+        const key = keyOf(entry);
+        if (key)
+            byKey.set(key, entry);
+    }
+    next.forEach((entry, index) => {
+        const key = keyOf(entry);
+        const was = key ? byKey.get(key) : undefined;
+        if (!key || !was) {
+            unsupported.push({
+                where: args.where,
+                change: `a new item in "${args.name}" cannot be published`,
+                remedy: "It has no upstream key, so there is no path to patch. Create it in the CMS first."
+            });
+            return;
+        }
+        const nested = diffFields({
+            specs: itemFields,
+            props: rows[index] ?? {},
+            source: was,
+            ctx: args.ctx,
+            documentId: args.documentId,
+            prefix: `${args.paths.item(args.prefix, args.field, key, index)}.`,
+            where: args.where,
+            paths: args.paths
+        });
+        patches.push(...nested.patches);
+        unsupported.push(...nested.unsupported);
+    });
+    return { patches, unsupported };
+}
+/**
+ * Fold a flat patch list into one `set` object per document.
+ *
+ * Most CMS clients take a single patch per document rather than one per field,
+ * and a caller that concatenates diffs from several blocks will have several
+ * entries for the same document. Documents with nothing to set are dropped, so
+ * an unchanged page issues no write at all.
+ */
+export function groupPatches(patches) {
+    const byDocument = new Map();
+    for (const patch of patches) {
+        let set = byDocument.get(patch.documentId);
+        if (!set) {
+            set = {};
+            byDocument.set(patch.documentId, set);
+        }
+        set[patch.path] = patch.value;
+    }
+    return [...byDocument.entries()]
+        .filter(([, set]) => Object.keys(set).length > 0)
+        .map(([documentId, set]) => ({ documentId, set }));
+}
+/** Merge diffs from several blocks or pages into one. */
+export function mergeDiffs(diffs) {
+    return {
+        patches: diffs.flatMap((d) => d.patches),
+        unsupported: diffs.flatMap((d) => d.unsupported)
+    };
+}
+/**
+ * Diff every block on a page.
+ *
+ * The routing decision stays with the integration — `locate` is where a block
+ * placed by a shared section writes to the *section* document rather than the
+ * page, and where a per-placement heading override stays page-local. Only the
+ * integration knows its own document graph. What is owned here is the loop, the
+ * report for a block with nowhere to write, and the `where` string a person has
+ * to be able to recognise.
+ *
+ * Returning `null` from `locate` reports the block as unpublishable rather than
+ * skipping it silently. That is almost always a block the editor added: the CMS
+ * has no document behind it, so there is no path to patch, and a publisher that
+ * quietly dropped it would report success for content the site will never show.
+ */
+export function diffPage(args) {
+    const nameOf = args.where ?? ((slug, block) => `${slug} → ${block.type}`);
+    const diffs = [];
+    for (const block of args.page.blocks) {
+        const where = nameOf(args.page.slug, block);
+        const located = args.locate(block);
+        if (!located) {
+            diffs.push({
+                patches: [],
+                unsupported: [
+                    {
+                        where,
+                        change: `a new "${block.type}" block was added`,
+                        remedy: "There is no upstream document behind it to patch. Create the block in the CMS first."
+                    }
+                ]
+            });
+            continue;
+        }
+        for (const target of Array.isArray(located) ? located : [located]) {
+            diffs.push(diffFields({
+                specs: target.specs,
+                props: block.props ?? {},
+                source: target.source,
+                ctx: args.ctx,
+                documentId: target.documentId,
+                prefix: target.prefix,
+                where,
+                paths: args.paths
+            }));
+        }
+    }
+    return mergeDiffs(diffs);
+}
+/** One line per refusal, in the editor's terms. For surfacing to a person. */
+export function describeUnsupported(unsupported) {
+    return unsupported.map((u) => `${u.where}: ${u.change}${u.remedy ? ` — ${u.remedy}` : ""}`);
+}

package/dist/publish/field-diff.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/publish/field-diff.test.js

@@ -0,0 +1,286 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { diffFields, diffPage, groupPatches, mergeDiffs, describeUnsupported, deepEqual, sanityPaths, indexPaths } from "./field-diff.js";
+const ctx = { lang: "de" };
+/** The common case: the prop is the field, and the value round-trips. */
+const plain = (key) => ({
+    rehydrate: (props) => props[key]
+});
+test("an unchanged field emits nothing", () => {
+    const specs = { heading: plain("heading") };
+    const diff = diffFields({
+        specs,
+        props: { heading: "Same" },
+        source: { heading: "Same" },
+        ctx,
+        documentId: "doc1",
+        where: "/ → hero"
+    });
+    assert.deepEqual(diff.patches, []);
+    assert.deepEqual(diff.unsupported, []);
+});
+test("a changed field is set at the path that owns it", () => {
+    const diff = diffFields({
+        specs: { heading: plain("heading") },
+        props: { heading: "After" },
+        source: { heading: "Before" },
+        ctx,
+        documentId: "doc1",
+        prefix: 'pageBuilder[_key=="b1"].',
+        where: "/ → hero"
+    });
+    assert.deepEqual(diff.patches, [
+        { documentId: "doc1", path: 'pageBuilder[_key=="b1"].heading', value: "After" }
+    ]);
+});
+test("cmsKey writes to the field the CMS actually has", () => {
+    const diff = diffFields({
+        specs: { heading: { ...plain("heading"), cmsKey: "headingOverride" } },
+        props: { heading: "After" },
+        source: { heading: "Before" },
+        ctx,
+        documentId: "doc1",
+        where: "/ → hero"
+    });
+    assert.equal(diff.patches[0].path, "headingOverride");
+});
+test("rehydrate receives the stored value, so an inversion can be partial", () => {
+    // The whole reason a snapshot contract cannot work: the editor saw
+    // `image.url`, the CMS holds an asset reference beside it, and only the
+    // integration knows how to put one back without destroying the other.
+    const specs = {
+        image: {
+            rehydrate: (props, before) => ({
+                ...before,
+                alt: props.imageAlt ?? undefined
+            })
+        }
+    };
+    const diff = diffFields({
+        specs,
+        props: { imageAlt: "New alt" },
+        source: { image: { _type: "image", asset: { _ref: "image-abc" }, alt: "Old alt" } },
+        ctx,
+        documentId: "doc1",
+        where: "/ → hero"
+    });
+    assert.deepEqual(diff.patches[0].value, {
+        _type: "image",
+        asset: { _ref: "image-abc" },
+        alt: "New alt"
+    });
+});
+// ---------------------------------------------------------------------------
+// The refusals
+// ---------------------------------------------------------------------------
+test("refusal 1 — a projection that cannot be inverted is reported, not guessed", () => {
+    const specs = {
+        image: {
+            rehydrate: (props, before) => ({ ...before, url: props.imageUrl }),
+            write: ({ before, after, emit, reject, path }) => {
+                const was = before;
+                const now = after;
+                if (was?.alt !== now.alt)
+                    emit(`${path}.alt`, now.alt);
+                if (was?.url !== now.url) {
+                    reject(`the image was replaced (${now.url})`, "The CMS stores an asset reference; the file has to be uploaded first.");
+                }
+            }
+        }
+    };
+    const diff = diffFields({
+        specs,
+        props: { imageUrl: "https://example.com/new.png" },
+        source: { image: { url: "https://cdn.example.com/old.png", alt: "Old" } },
+        ctx,
+        documentId: "doc1",
+        where: "/ → hero"
+    });
+    assert.deepEqual(diff.patches, [], "nothing may be written for a value that cannot be expressed");
+    assert.equal(diff.unsupported.length, 1);
+    assert.match(diff.unsupported[0].change, /image was replaced/);
+    assert.match(String(diff.unsupported[0].remedy), /uploaded first/);
+});
+test("refusal 2 — adding or removing list items is a document-shaped change", () => {
+    const specs = {
+        cards: {
+            rehydrate: (props) => props.cards,
+            itemFields: { title: plain("title") }
+        }
+    };
+    const diff = diffFields({
+        specs,
+        props: { cards: [{ _key: "k1", title: "One" }, { _key: "k2", title: "Two" }] },
+        source: { cards: [{ _key: "k1", title: "One" }] },
+        ctx,
+        documentId: "doc1",
+        where: "/ → cardGrid"
+    });
+    assert.ok(diff.unsupported.some((u) => /added to or removed/.test(u.change)));
+});
+test("refusal 3 — an item the CMS has never seen has no path to patch", () => {
+    const specs = {
+        cards: {
+            rehydrate: (props) => props.cards,
+            itemFields: { title: plain("title") }
+        }
+    };
+    const diff = diffFields({
+        specs,
+        props: { cards: [{ _key: "k1", title: "One" }, { title: "Brand new" }] },
+        source: { cards: [{ _key: "k1", title: "One" }, { _key: "k2", title: "Two" }] },
+        ctx,
+        documentId: "doc1",
+        where: "/ → cardGrid"
+    });
+    assert.ok(diff.unsupported.some((u) => /new item/.test(u.change)));
+    assert.ok(!diff.patches.some((p) => p.value === "Brand new"), "a keyless item must not be written to whatever path happens to be at its index");
+});
+test("refusal 4 — a block with no upstream document is reported, never skipped", () => {
+    const diff = diffPage({
+        page: {
+            slug: "/prices",
+            blocks: [{ id: "b_new", type: "pba_pricingSection", props: { heading: "Hi" } }]
+        },
+        ctx,
+        locate: () => null
+    });
+    assert.deepEqual(diff.patches, []);
+    assert.equal(diff.unsupported.length, 1);
+    assert.match(diff.unsupported[0].change, /new "pba_pricingSection" block/);
+    assert.equal(diff.unsupported[0].where, "/prices → pba_pricingSection");
+});
+// ---------------------------------------------------------------------------
+// Lists, keys, and the reason index addressing is not the default
+// ---------------------------------------------------------------------------
+test("a list item is patched at its own key, not at its position", () => {
+    const specs = {
+        cards: {
+            rehydrate: (props) => props.cards,
+            itemFields: { title: plain("title") }
+        }
+    };
+    // The upstream order is the reverse of the editor's. Index addressing would
+    // write "Renamed" onto the wrong card.
+    const diff = diffFields({
+        specs,
+        props: { cards: [{ _key: "k2", title: "Renamed" }, { _key: "k1", title: "One" }] },
+        source: { cards: [{ _key: "k1", title: "One" }, { _key: "k2", title: "Two" }] },
+        ctx,
+        documentId: "doc1",
+        where: "/ → cardGrid"
+    });
+    assert.deepEqual(diff.patches, [
+        { documentId: "doc1", path: 'cards[_key=="k2"].title', value: "Renamed" }
+    ]);
+});
+test("index addressing is available and says what it costs", () => {
+    const specs = {
+        rows: {
+            rehydrate: (props) => props.rows,
+            itemFields: { label: plain("label") },
+            itemKey: (item) => String(item.id)
+        }
+    };
+    const diff = diffFields({
+        specs,
+        props: { rows: [{ id: "7", label: "After" }] },
+        source: { rows: [{ id: "7", label: "Before" }] },
+        ctx,
+        documentId: "doc1",
+        where: "/ → table",
+        paths: indexPaths
+    });
+    assert.deepEqual(diff.patches, [{ documentId: "doc1", path: "rows[0].label", value: "After" }]);
+});
+test("a custom itemKey identifies items that have no _key", () => {
+    const specs = {
+        rows: {
+            rehydrate: (props) => props.rows,
+            itemFields: { label: plain("label") },
+            itemKey: (item) => (typeof item.id === "string" ? item.id : undefined)
+        }
+    };
+    const diff = diffFields({
+        specs,
+        props: { rows: [{ id: "r1", label: "After" }] },
+        source: { rows: [{ id: "r1", label: "Before" }] },
+        ctx,
+        documentId: "doc1",
+        where: "/ → table",
+        paths: sanityPaths
+    });
+    assert.deepEqual(diff.patches, [
+        { documentId: "doc1", path: 'rows[_key=="r1"].label', value: "After" }
+    ]);
+});
+// ---------------------------------------------------------------------------
+// Routing across documents
+// ---------------------------------------------------------------------------
+test("one block can write to two documents", () => {
+    // A block placed by a shared section: its heading override belongs to the
+    // page, the rest of it belongs to the section every page shares.
+    const diff = diffPage({
+        page: {
+            slug: "/",
+            blocks: [{ id: "b1", type: "sharedSection", props: { heading: "Page heading", body: "Shared body" } }]
+        },
+        ctx,
+        locate: () => [
+            {
+                documentId: "page-1",
+                prefix: 'pageBuilder[_key=="b1"].',
+                specs: { heading: { ...plain("heading"), cmsKey: "headingOverride" } },
+                source: { heading: "Old page heading" }
+            },
+            {
+                documentId: "section-9",
+                prefix: "content[0].",
+                specs: { body: plain("body") },
+                source: { body: "Old shared body" }
+            }
+        ]
+    });
+    assert.deepEqual(groupPatches(diff.patches), [
+        { documentId: "page-1", set: { 'pageBuilder[_key=="b1"].headingOverride': "Page heading" } },
+        { documentId: "section-9", set: { "content[0].body": "Shared body" } }
+    ]);
+});
+test("a page with nothing changed issues no write at all", () => {
+    const diff = diffPage({
+        page: { slug: "/", blocks: [{ id: "b1", type: "hero", props: { heading: "Same" } }] },
+        ctx,
+        locate: () => ({
+            documentId: "page-1",
+            prefix: "",
+            specs: { heading: plain("heading") },
+            source: { heading: "Same" }
+        })
+    });
+    assert.deepEqual(groupPatches(diff.patches), [], "an unchanged publish must not touch the CMS");
+});
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+test("deepEqual treats null and undefined as the same absence", () => {
+    // A CMS that omits an empty field and an editor that sends `undefined` are
+    // saying the same thing; treating them as a change rewrites every optional
+    // field on every publish.
+    assert.ok(deepEqual(null, undefined));
+    assert.ok(deepEqual({ a: [1, { b: "c" }] }, { a: [1, { b: "c" }] }));
+    assert.ok(!deepEqual({ a: 1 }, { a: 1, b: 2 }));
+    assert.ok(!deepEqual([1, 2], { 0: 1, 1: 2 }));
+});
+test("mergeDiffs and describeUnsupported produce something a person can read", () => {
+    const merged = mergeDiffs([
+        { patches: [{ documentId: "d", path: "a", value: 1 }], unsupported: [] },
+        {
+            patches: [],
+            unsupported: [{ where: "/ → hero", change: "the image was replaced", remedy: "Upload it first." }]
+        }
+    ]);
+    assert.equal(merged.patches.length, 1);
+    assert.deepEqual(describeUnsupported(merged.unsupported), [
+        "/ → hero: the image was replaced — Upload it first."
+    ]);
+});

package/dist/server/orchestrator.d.ts

@@ -1,117 +1 @@
-import { type AIProvider, type ModelKey } from "@avocadostudio-ai/orchestrator-core/state/session-state.js";
-import { type Logger } from "@avocadostudio-ai/orchestrator-core/logger.js";
-import type { CmsAdapter } from "@avocadostudio-ai/orchestrator-core/cms/adapter.js";
-export interface CreateOrchestratorConfig {
-    /**
-     * Provider model overrides. Defaults to env vars (OPENAI_MODEL_*, ANTHROPIC_MODEL_*,
-     * GOOGLE_GENAI_MODEL_*). Pass an explicit object to override per-tier model names.
-     */
-    modelLookup?: Record<AIProvider, Record<ModelKey, string>>;
-    /**
-     * Override available providers. Defaults to whichever API keys are present in
-     * process.env (OPENAI_API_KEY / ANTHROPIC_API_KEY / GOOGLE_GENAI_API_KEY).
-     */
-    availableProviders?: AIProvider[];
-    /** Pino-shaped logger. Defaults to a console-backed implementation. */
-    logger?: Logger;
-    /**
-     * Allowed CORS origins. Defaults to "*". For production, pass an explicit
-     * allow-list (Next.js can also handle CORS via middleware — pass null here
-     * to disable the SDK's CORS handling entirely).
-     */
-    corsOrigins?: string[] | "*" | null;
-    /**
-     * Register the default builtin tools (unsplash-search, image-generate,
-     * gdrive-browse). Defaults to `false` — opt in only if you want those
-     * features, since registering them pulls in sharp + googleapis + image-gen
-     * SDKs at module load. Pass `true` for env-gated defaults, or an explicit
-     * subset like `["unsplash-search"]`.
-     */
-    builtinTools?: boolean | Array<"unsplash-search" | "image-generate" | "gdrive-browse">;
-    /**
-     * URL path prefix the handler is mounted under. Everything matching this
-     * prefix is stripped off `url.pathname` before route matching, so the rest
-     * of the handler can reason in terms of `/chat`, `/chat/stream`, etc.
-     *
-     * Defaults to `/api/avocado` (the catch-all path used in the Next.js
-     * example app). Set to `""` if you want to match against the full pathname
-     * yourself, or override to e.g. `/api/orchestrator` if you mount the
-     * catch-all there.
-     */
-    basePath?: string;
-    /**
-     * Source-of-truth adapter for the site's existing content. Called once per
-     * session on the first chat request to seed SQLite with the site's pages.
-     * Without an adapter the orchestrator starts with an empty draft, which
-     * means the planner has no pages to edit — every "edit the homepage" turn
-     * returns `page not found`.
-     *
-     * Provided implementations:
-     *  - `jsonFileAdapter({ path })` — read PageDoc[] from a JSON file
-     *  - `editorApiAdapter({ origin })` — fetch from `${origin}/api/editor/pages`
-     *
-     * Import from `@avocadostudio-ai/orchestrator-core/cms`.
-     */
-    adapter?: CmsAdapter;
-    /**
-     * Site identifier used to scope session state in SQLite. When `adapter` is
-     * set, defaults to `"library"` so the demo-content seed path is bypassed
-     * (an unscoped session falls back to the orchestrator's bundled demo pages).
-     * Override if you want to run multiple distinct sites against one process.
-     *
-     * Precedence on incoming requests:
-     *   - adapter configured: `siteId` (or its `"library"` default) ALWAYS wins
-     *     over `body.siteId`. The library-mode orchestrator owns its identity.
-     *   - no adapter: explicit `siteId` wins; otherwise `body.siteId` is used.
-     */
-    siteId?: string;
-    /**
-     * Register the site's block schemas before the orchestrator's first chat
-     * request. Use this instead of relying on side-effect import order: in
-     * library mode, the orchestrator's transitive imports of
-     * `@avocadostudio-ai/shared` re-register canonical Hero/CTA/etc. on the
-     * shared globalThis registry, often AFTER the host app's overrides.
-     *
-     * **Fires once per orchestrator runtime** — at `buildRuntime` time, not
-     * per-request. For long-lived production processes this is fine, but if
-     * the host re-builds the runtime on hot-reload, ensure the schemas survive
-     * (registerBlock is idempotent — calling again is safe). Pair this with
-     * the same `registerBlocks` passed to `createEditorApiHandler`, which
-     * re-runs on every `/blocks` request, to cover request-time too.
-     */
-    registerBlocks?: () => void;
-    /**
-     * Local directory where `POST /image/upload` writes uploaded files and
-     * `GET /generated-images/:fileName` reads them back. Defaults to
-     * `.data/generated-images` under the host process CWD.
-     *
-     * **POC-grade storage.** Files live on the orchestrator host's local disk
-     * with no CDN, no image transforms, and no durability guarantee — on an
-     * ephemeral filesystem (e.g. a container without a mounted volume) uploads
-     * vanish on redeploy. See `docs/image-storage-options.md` for the path to a
-     * blob/CDN backend; that swap is contained to these two routes.
-     */
-    imageDir?: string;
-}
-/**
- * A handler returned by {@link createOrchestrator}. Callable like the bare
- * Web `(Request) => Promise<Response>` it always was, with an extra
- * `dispose()` method to release the resumable-stream sweep timer (call this
- * during dev hot-reload or test teardown).
- */
-export type OrchestratorHandler = ((request: Request) => Promise<Response>) & {
-    dispose(): Promise<void>;
-};
-export type { CmsAdapter, CmsInlineAsset, CmsPublishContext, CmsPublishResult } from "@avocadostudio-ai/orchestrator-core/cms/adapter.js";
-export { jsonFileAdapter, editorApiAdapter } from "@avocadostudio-ai/orchestrator-core/cms/index.js";
-/**
- * Build a Web-standard request handler that wraps the orchestrator brain.
- *
- * Usage in Next.js App Router (`app/api/avocado/[[...path]]/route.ts`):
- *
- *     export const runtime = "nodejs"
- *     const handler = createOrchestrator()
- *     export const POST = handler
- *     export const OPTIONS = handler
- */
-export declare function createOrchestrator(config?: CreateOrchestratorConfig): OrchestratorHandler;
+export { createOrchestrator, jsonFileAdapter, editorApiAdapter, resolveCapabilities, type CreateOrchestratorConfig, type OrchestratorHandler, type OrchestratorAuth, type AuthContext, type CmsAdapter, type CmsCapabilities, type CmsInlineAsset, type CmsPublishContext, type CmsPublishResult, type CmsPerspective, type CmsReadOptions, type ResolvedCapabilities } from "@avocadostudio-ai/orchestrator-core";