@avocadostudio-ai/site-sdk 0.2.3 → 0.3.1

package/README.md

@@ -169,10 +169,23 @@ none of them.
 | `.../navigation` | `buildNavItems`, `buildSiteHeaderBlock` |
 | `.../seo` | `buildPageMetadata` and the title/description derivation |
 
-`useLivePreviewBlocks` — the hook that reads `LivePreviewProvider`, and the only
-way to render a live draft through **your own** components rather than Avocado's
-— is not here. It lives in `@avocadostudio-ai/preview-adapter`, which you have to
-install directly.
+`useLivePreviewBlocks` is not here. It lives in
+`@avocadostudio-ai/preview-adapter`, which you must depend on directly to import
+from it (`LivePreviewProvider` itself is re-exported above, the hook is not).
+
+It is worth being precise about what it is for, because an earlier version of
+this paragraph was not. Rendering a live draft through **your own** components
+does not require it — that is the default, and it is what an existing site
+should do: skip `createSitePage`, skip `@avocadostudio-ai/blocks/styles.css`,
+render the draft page with your own components, and mount `EditorOverlay`.
+Streamed edits reach the page as DOM writes keyed on `data-editable-target`.
+
+What the hook buys is having those edits arrive as **React state** instead, so
+components that own their own markup are not fighting an `innerHTML` write. It
+is the newer and less exercised of the two paths, and it re-renders on the
+client — anything resolved from a server-only registry blanks. Take the default
+path first. See
+[Existing sites keep their own components](https://docs.avocadostudio.dev/integration/nextjs-integration#existing-sites-keep-their-own-components).
 
 ## API Contract
 
@@ -213,6 +226,29 @@ site's own origin** for `/api/editor/blocks` and `/api/editor/pages`. Mount only
 the orchestrator and the editor loads, connects, and answers four requests with
 `net::ERR_FAILED` in a console you have to open to see.
 
+### And then run the editor
+
+The two handlers above are the whole backend. The editor UI itself is a
+prebuilt SPA that ships inside `@avocadostudio-ai/cli`, so there is nothing to
+clone and no third service to deploy:
+
+```bash
+npx @avocadostudio-ai/cli start \
+  --orchestrator http://localhost:3000/api/avocado \
+  --preview      http://localhost:3000
+```
+
+That serves the editor on `http://localhost:4100`, pointed at the orchestrator
+you just mounted. `--preview` is the origin the editor frames, so it is your
+site's dev server — **your** port, which is only 3000 if that is where your
+`dev` script runs.
+
+This line is here because the composition is not obvious from either package on
+its own: the CLI's own README says it does not bundle an orchestrator and
+points at one you deploy separately, which is true and reads as "you need a
+third service". You do not. `createOrchestrator` above *is* the orchestrator,
+and the CLI is the other half of it.
+
 ## The adapter contract
 
 `createOrchestrator({ adapter })` is the whole of library mode: SQLite is the
@@ -241,8 +277,14 @@ const myAdapter: CmsAdapter = {
     return { ok: true, unsupported: [] }
   },
 
+  /** Optional. Fills the editor's image picker from your media library. */
+  async getMedia({ query, page, limit }) {
+    const res = await searchAssets(query, page, limit)
+    return { items: res.assets, totalPages: res.pageCount, label: "Sanity" }
+  },
+
   /** Static, because /whoami must answer it with the CMS unreachable. */
-  capabilities: { createPage: false },
+  capabilities: { createPages: false },
 }
 ```
 
@@ -260,10 +302,76 @@ the projection back destroys what it was projected from. `context.published` is
 the baseline; `undefined` means *no baseline available*, never *the site was
 empty*. See [Publishing back to a real CMS](#publishing-back-to-a-real-cms).
 
+It survives a process restart: a restart reloads the draft from SQLite without
+re-seeding it, and the baseline used to be dropped on that path, so a publisher
+written the way this section recommends — diff against the baseline, refuse when
+there is none — could never publish again afterwards. The orchestrator now
+re-reads the adapter for the baseline alone in that case. It can still be
+`undefined` if that read fails, so keep the refusal.
+
 `CmsAdapter`, `CmsCapabilities`, `CmsPublishContext`, `CmsPerspective` and
 `CreateOrchestratorConfig` are all exported from
 `@avocadostudio-ai/site-sdk/server`.
 
+### Filling the image picker
+
+`getMedia` is optional and silent by default: implement it and the editor's
+asset picker grows a CMS tab, leave it off and it does not. `/status/planner`
+reports `features.cmsMedia` and `/whoami` reports `capabilities.readsMedia`,
+both derived from whether the method exists — an adapter cannot claim a media
+library it did not implement.
+
+If your CMS is Contentful, Sanity or Strapi, `cmsMediaSource` writes the method
+for you:
+
+```ts
+import { cmsMediaSource, type CmsAdapter } from "@avocadostudio-ai/site-sdk/server"
+
+export function sanityAdapter(): CmsAdapter {
+  return {
+    id: "sanity",
+    getPages: (options) => getSanityPages(options?.perspective),
+    getMedia: cmsMediaSource({
+      provider: "sanity",
+      projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID!,
+      dataset: process.env.NEXT_PUBLIC_SANITY_DATASET,
+      token: process.env.SANITY_API_TOKEN
+    })
+  }
+}
+```
+
+It is a convenience, not the contract. Any other CMS returns the same shape
+itself:
+
+```ts
+getMedia: async ({ query, page, limit }) => {
+  const res = await myCms.assets.search({ q: query, page, perPage: limit })
+  return {
+    items: res.assets.map((a) => ({
+      id: a.id,
+      name: a.filename,
+      imageUrl: a.url,
+      thumbUrl: a.thumb ?? a.url,
+      alt: a.altText
+    })),
+    totalPages: res.pageCount,
+    label: "My CMS"
+  }
+}
+```
+
+`query` is a free-text filter and may be absent; `page` is 1-based and `limit`
+is clamped to 50 before it reaches you. Return an empty page rather than
+throwing when the upstream call fails — the picker renders an empty grid, and a
+rejected promise inside a modal shows the user nothing at all.
+
+The credentials stay on the server. Before this method existed the picker
+called Contentful, Sanity and Strapi from the browser, over a union of exactly
+those three compiled into the editor — which is why a fourth CMS could bring
+its own adapter, blocks and publish handler and still had no way to bring its
+own images.
+
 ## Library mode needs a credential
 
 `createOrchestrator()` mounts on your own domain and can edit and publish your
@@ -344,6 +452,62 @@ A workspace link to `@avocadostudio-ai/orchestrator-core` is **not** enough. A
 linked package's own dependencies are never materialised in the host's tree, and
 a native module has to be resolvable from there.
 
+## The editor frames your page, not the preview route
+
+The iframe's `src` is your site's own URL with a query parameter added:
+
+```
+http://localhost:3000/de?__editor=1&session=dev&siteId=my-site
+```
+
+`createEditorProxy` then rewrites that request onto the preview route. **The
+rewrite does not re-run Next's header matching**, so `headers()` was already
+evaluated against `/de` — the public path — and the preview HTML comes back
+wearing the public site's headers.
+
+That matters for exactly one thing, and it is the first thing an adopter sees
+after wiring everything up correctly: **a site that sends `frame-ancestors` or
+`X-Frame-Options` cannot be framed**, and the failure is a blank rectangle. The
+response is correct, the render is correct, and the browser refuses to display
+it.
+
+Scope the exception to the query parameter, which is the only part of the
+request Next sees before the rewrite:
+
+```js
+async headers() {
+  const editor = "http://localhost:4100 http://127.0.0.1:4100"
+  return [
+    {
+      source: "/:path*",
+      has: [{ type: "query", key: "__editor" }],
+      headers: [{ key: "Content-Security-Policy", value: `frame-ancestors 'self' ${editor};` }]
+    },
+    {
+      source: "/:path*",
+      missing: [{ type: "query", key: "__editor" }],
+      headers: [
+        { key: "Content-Security-Policy", value: "frame-ancestors 'self';" },
+        { key: "X-Frame-Options", value: "SAMEORIGIN" }
+      ]
+    }
+  ]
+}
+```
+
+Two things that are easy to get wrong here:
+
+**The `missing:` on the public rule is load-bearing.** Without it both rules
+match an editor request and the browser gets two `Content-Security-Policy`
+headers — which it reads as their *intersection*, putting `frame-ancestors
+'self'` back and blocking the frame again.
+
+**Name both spellings of the loopback address.** The CLI binds `127.0.0.1` and
+prints that; everything written down says `localhost`. `frame-ancestors` and
+CORS both compare origins as strings, so a rule copied from this page and an
+editor opened at the URL the CLI printed will never match. The SDK's own
+development CORS default now accepts both; your CSP has to say both too.
+
 ## Telling the orchestrator where your site is
 
 An agent's only way to see what it just edited is `POST /preview/screenshot`,
@@ -421,9 +585,14 @@ Two things worth knowing before you write one.
 
 **List items match on their own key, not their position.** An index-addressed
 patch lands on the wrong row the moment anything reorders the array upstream.
-`sanityPaths` (the default) addresses `field[_key=="…"]`; `indexPaths` exists for
-stores with no element identity and is only correct when your publish is the
-only writer.
+`sanityPaths` addresses `field[_key=="…"]`; `indexPaths` exists for stores with
+no element identity and is only correct when your publish is the only writer.
+
+`paths` is a **required** argument to both `diffFields` and `diffPage`. It used
+to default to `sanityPaths`, which meant a Contentful or Strapi publisher that
+never mentioned it emitted `_key` patches against a store that has no `_key` —
+the wrong answer, arrived at quietly. Nothing can infer which CMS you are
+writing to, so it asks.
 
 **Refusing is a result, not an error.** Four things a field diff cannot express
 — a replaced image, a retyped link, a list item added or removed, a new block —
@@ -548,6 +717,71 @@ Declaring a type you never registered is not silently dropped: it has no schema
 to describe, so it cannot reach the manifest, and the orchestrator logs a warning
 naming it the first time the manifest is served.
 
+## Mounting the overlay
+
+Nothing on the page is clickable until `EditorOverlay` is on it. It is the whole
+of the selection UI — the block outline, the type badge, the field pills, the
+postMessage channel back to the editor — and a preview route without it renders
+correctly, frames correctly, and does not respond to a click.
+
+It takes two required props, and the second one is not guessable:
+
+```tsx
+// app/preview-draft/[[...slug]]/page.tsx
+import { resolveEditorContext } from "@avocadostudio-ai/site-sdk/draft"
+import { EditorOverlay } from "@avocadostudio-ai/site-sdk/editor"
+import { buildSlug } from "@avocadostudio-ai/site-sdk"
+
+export default async function PreviewPage({ params, searchParams }) {
+  const { slug } = await params
+  const ctx = await resolveEditorContext(await searchParams)
+  const path = buildSlug(slug)          // ["fr","pricing"] -> "/fr/pricing"
+
+  return (
+    <>
+      <MyPage slug={path} />
+      {ctx && <EditorOverlay slug={path} editorOrigin={ctx.editorOrigin} />}
+    </>
+  )
+}
+```
+
+- **`slug`** is the page's slug as the orchestrator knows it — the same
+  leading-slash path `getPages()` returned, not the URL the visitor typed. Build
+  it with `buildSlug` rather than joining segments by hand.
+- **`editorOrigin`** is the origin the overlay will `postMessage` to, and every
+  message is scoped to it. `resolveEditorContext` already returns it as its
+  third field; there is no need to plumb an env var through for this.
+
+The component renders `null` outside an iframe, so it is inert on a normal page
+load and safe to mount unconditionally within the preview route.
+
+### Then turn selection on in the editor
+
+Mounting the overlay is necessary and not sufficient. Clicking is gated on
+`data-editor-selection-mode`, which the bridge sets only when the editor sends
+`setSelectionMode {enabled: true}` — and the editor's own default is **off**.
+
+So a correctly-wired integration's first browser session looks like this: the
+site frames, renders, and does not respond to a click. Nothing is broken; the
+picker is not on. Turn it on with the crosshair button in the chat composer
+("Select element"), or press Esc to leave it again.
+
+Check this before debugging anything else — an integrator who assumes their
+markup is wrong can spend an afternoon proving that it isn't. In the iframe's
+console:
+
+```js
+document.documentElement.hasAttribute("data-editor-active")          // overlay mounted
+document.documentElement.hasAttribute("data-editor-selection-mode")  // picker on
+```
+
+Both true and clicks still doing nothing is a real bug. The first true and the
+second false is the default.
+
+Once the picker is on, blocks are selectable. Individual *fields* are not,
+until:
+
 ## Making fields editable
 
 The manifest tells the editor which blocks exist and what props they take. It

package/dist/editor-cors.d.ts

@@ -1,7 +1,8 @@
 /**
  * CORS for the editor API routes a host app mounts.
  *
- * The dev editor runs on its own origin (`localhost:4100`), so the routes have
+ * The dev editor runs on its own origin (`localhost:4100`, or the `127.0.0.1`
+ * spelling the CLI prints), so the routes have
  * to answer cross-origin requests from it. That default used to be added
  * unconditionally, which meant a deployed site kept answering CORS-approved
  * requests to a `localhost` origin: any page a visitor had open could read that

package/dist/editor-cors.js

@@ -1,14 +1,27 @@
 /**
  * CORS for the editor API routes a host app mounts.
  *
- * The dev editor runs on its own origin (`localhost:4100`), so the routes have
+ * The dev editor runs on its own origin (`localhost:4100`, or the `127.0.0.1`
+ * spelling the CLI prints), so the routes have
  * to answer cross-origin requests from it. That default used to be added
  * unconditionally, which meant a deployed site kept answering CORS-approved
  * requests to a `localhost` origin: any page a visitor had open could read that
  * site's draft content out of its own browser. Now the development default is
  * only assumed in development, and a deployment says what it allows.
  */
-const DEV_EDITOR_ORIGIN = "http://localhost:4100";
+/*
+ * Both spellings of the same loopback address, because the product uses both.
+ *
+ * The CLI binds `127.0.0.1` and prints `http://127.0.0.1:4100`; every README,
+ * env table and example says `http://localhost:4100`. CORS and
+ * `frame-ancestors` compare origins as strings, so an editor started by our own
+ * CLI, opened at the URL our own CLI printed, was rejected by our own default —
+ * and the symptom is a blank iframe with a console message naming an origin
+ * that looks like it should have matched.
+ *
+ * Development only, as below: a deployment still has to name its editor.
+ */
+const DEV_EDITOR_ORIGINS = ["http://localhost:4100", "http://127.0.0.1:4100"];
 let cachedOrigins;
 function parseOrigins(value) {
     return (value ?? "")
@@ -27,7 +40,7 @@ export function getEditorCorsOrigins() {
      */
     const declaredEditor = parseOrigins(process.env.NEXT_PUBLIC_EDITOR_ORIGIN);
     const isProduction = process.env.NODE_ENV === "production";
-    const defaults = isProduction ? [] : [DEV_EDITOR_ORIGIN];
+    const defaults = isProduction ? [] : DEV_EDITOR_ORIGINS;
     cachedOrigins = new Set([...defaults, ...declaredEditor, ...configured]);
     return cachedOrigins;
 }

package/dist/editor-cors.test.js

@@ -64,3 +64,22 @@ test("an allowed origin gets the CORS headers and a disallowed one does not", ()
         assert.equal(denied.headers.get("Vary"), "Origin");
     });
 });
+/*
+ * The CLI binds `127.0.0.1` and prints that URL; the docs all say `localhost`.
+ * Origins compare as strings, so the editor our own CLI starts has to be
+ * allowed under the spelling our own CLI printed.
+ */
+test("development allows both spellings of the loopback editor origin", () => {
+    withEnv({ ...CLEAN, NODE_ENV: "development" }, () => {
+        const origins = getEditorCorsOrigins();
+        assert.ok(origins.has("http://localhost:4100"), "the spelling the docs use");
+        assert.ok(origins.has("http://127.0.0.1:4100"), "the spelling the CLI prints");
+    });
+});
+test("production still allows neither by default", () => {
+    withEnv({ ...CLEAN, NODE_ENV: "production" }, () => {
+        const origins = getEditorCorsOrigins();
+        assert.equal(origins.has("http://localhost:4100"), false);
+        assert.equal(origins.has("http://127.0.0.1:4100"), false);
+    });
+});

package/dist/editor-overlay.d.ts

@@ -1,3 +1,20 @@
+/**
+ * The selection UI: block outlines, the type badge, the field pills, and the
+ * postMessage channel the editor talks to.
+ *
+ * Mount it inside the preview route. A preview page without it renders and
+ * frames correctly and simply does not respond to a click — which is a hard
+ * failure to diagnose, because nothing is broken, something is absent.
+ *
+ * @param slug The page's slug **as the orchestrator knows it**: the same
+ *   leading-slash path `getPages()` returned, not the URL the visitor typed.
+ *   `buildSlug(segments)` produces it from a catch-all route's params.
+ * @param editorOrigin The origin every message is scoped to. It is the third
+ *   field of what `resolveEditorContext()` already returns — there is nothing
+ *   to plumb through for it.
+ *
+ * Renders `null` outside an iframe, so it is inert on an ordinary page load.
+ */
 export declare function EditorOverlay({ slug, editorOrigin }: {
     slug: string;
     editorOrigin: string;

package/dist/editor-overlay.js

@@ -3,6 +3,23 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import dynamic from "next/dynamic";
 import { useState, useEffect } from "react";
 const PreviewBridgeLoader = dynamic(() => import("./editor-overlay-inner.js").then((m) => ({ default: m.EditorOverlayInner })), { ssr: false });
+/**
+ * The selection UI: block outlines, the type badge, the field pills, and the
+ * postMessage channel the editor talks to.
+ *
+ * Mount it inside the preview route. A preview page without it renders and
+ * frames correctly and simply does not respond to a click — which is a hard
+ * failure to diagnose, because nothing is broken, something is absent.
+ *
+ * @param slug The page's slug **as the orchestrator knows it**: the same
+ *   leading-slash path `getPages()` returned, not the URL the visitor typed.
+ *   `buildSlug(segments)` produces it from a catch-all route's params.
+ * @param editorOrigin The origin every message is scoped to. It is the third
+ *   field of what `resolveEditorContext()` already returns — there is nothing
+ *   to plumb through for it.
+ *
+ * Renders `null` outside an iframe, so it is inert on an ordinary page load.
+ */
 export function EditorOverlay({ slug, editorOrigin }) {
     const [inIframe, setInIframe] = useState(false);
     useEffect(() => {

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

@@ -124,7 +124,15 @@ export declare function diffFields<Ctx>(args: {
     /** Path prefix this object sits at, e.g. `pageBuilder[_key=="b1"].`. */
     prefix?: string;
     where: string;
-    paths?: PathSyntax;
+    /**
+     * How this CMS addresses one element of a list. Required, and deliberately
+     * so: it used to default to `sanityPaths`, which meant a Contentful or
+     * Strapi publisher that never mentioned it emitted `field[_key=="…"]`
+     * patches against a store with no `_key`. The wrong answer was the quiet
+     * one — a default cannot know which CMS it is writing to, and the cost of
+     * guessing wrong is a patch applied to the wrong row.
+     */
+    paths: PathSyntax;
 }): FieldDiff;
 /**
  * Fold a flat patch list into one `set` object per document.
@@ -180,7 +188,8 @@ export declare function diffPage<Ctx>(args: {
         type: string;
         props: Record<string, unknown>;
     }): BlockTarget<Ctx> | BlockTarget<Ctx>[] | null;
-    paths?: PathSyntax;
+    /** How this CMS addresses one element of a list. See `diffFields`. */
+    paths: PathSyntax;
     /** How a block is named in a report. Defaults to `"/slug → type"`. */
     where?(pageSlug: string, block: {
         id: string;

package/dist/publish/field-diff.js

@@ -71,7 +71,11 @@ function defaultItemKey(item) {
  * cannot make a patch land on the wrong row.
  */
 export function diffFields(args) {
-    const paths = args.paths ?? sanityPaths;
+    /* A JS caller gets no compile error, so say it loudly rather than picking
+     * one. Silently choosing a syntax is the bug this parameter exists to stop. */
+    if (!args.paths)
+        throw new TypeError("diffFields: `paths` is required — pass sanityPaths or indexPaths");
+    const paths = args.paths;
     const prefix = args.prefix ?? "";
     const patches = [];
     const unsupported = [];

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

@@ -14,7 +14,8 @@ test("an unchanged field emits nothing", () => {
         source: { heading: "Same" },
         ctx,
         documentId: "doc1",
-        where: "/ → hero"
+        where: "/ → hero",
+        paths: sanityPaths
     });
     assert.deepEqual(diff.patches, []);
     assert.deepEqual(diff.unsupported, []);
@@ -27,7 +28,8 @@ test("a changed field is set at the path that owns it", () => {
         ctx,
         documentId: "doc1",
         prefix: 'pageBuilder[_key=="b1"].',
-        where: "/ → hero"
+        where: "/ → hero",
+        paths: sanityPaths
     });
     assert.deepEqual(diff.patches, [
         { documentId: "doc1", path: 'pageBuilder[_key=="b1"].heading', value: "After" }
@@ -40,7 +42,8 @@ test("cmsKey writes to the field the CMS actually has", () => {
         source: { heading: "Before" },
         ctx,
         documentId: "doc1",
-        where: "/ → hero"
+        where: "/ → hero",
+        paths: sanityPaths
     });
     assert.equal(diff.patches[0].path, "headingOverride");
 });
@@ -62,7 +65,8 @@ test("rehydrate receives the stored value, so an inversion can be partial", () =
         source: { image: { _type: "image", asset: { _ref: "image-abc" }, alt: "Old alt" } },
         ctx,
         documentId: "doc1",
-        where: "/ → hero"
+        where: "/ → hero",
+        paths: sanityPaths
     });
     assert.deepEqual(diff.patches[0].value, {
         _type: "image",
@@ -94,7 +98,8 @@ test("refusal 1 — a projection that cannot be inverted is reported, not guesse
         source: { image: { url: "https://cdn.example.com/old.png", alt: "Old" } },
         ctx,
         documentId: "doc1",
-        where: "/ → hero"
+        where: "/ → hero",
+        paths: sanityPaths
     });
     assert.deepEqual(diff.patches, [], "nothing may be written for a value that cannot be expressed");
     assert.equal(diff.unsupported.length, 1);
@@ -114,7 +119,8 @@ test("refusal 2 — adding or removing list items is a document-shaped change",
         source: { cards: [{ _key: "k1", title: "One" }] },
         ctx,
         documentId: "doc1",
-        where: "/ → cardGrid"
+        where: "/ → cardGrid",
+        paths: sanityPaths
     });
     assert.ok(diff.unsupported.some((u) => /added to or removed/.test(u.change)));
 });
@@ -131,7 +137,8 @@ test("refusal 3 — an item the CMS has never seen has no path to patch", () =>
         source: { cards: [{ _key: "k1", title: "One" }, { _key: "k2", title: "Two" }] },
         ctx,
         documentId: "doc1",
-        where: "/ → cardGrid"
+        where: "/ → cardGrid",
+        paths: sanityPaths
     });
     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");
@@ -143,6 +150,7 @@ test("refusal 4 — a block with no upstream document is reported, never skipped
             blocks: [{ id: "b_new", type: "pba_pricingSection", props: { heading: "Hi" } }]
         },
         ctx,
+        paths: sanityPaths,
         locate: () => null
     });
     assert.deepEqual(diff.patches, []);
@@ -168,7 +176,8 @@ test("a list item is patched at its own key, not at its position", () => {
         source: { cards: [{ _key: "k1", title: "One" }, { _key: "k2", title: "Two" }] },
         ctx,
         documentId: "doc1",
-        where: "/ → cardGrid"
+        where: "/ → cardGrid",
+        paths: sanityPaths
     });
     assert.deepEqual(diff.patches, [
         { documentId: "doc1", path: 'cards[_key=="k2"].title', value: "Renamed" }
@@ -226,6 +235,7 @@ test("one block can write to two documents", () => {
             blocks: [{ id: "b1", type: "sharedSection", props: { heading: "Page heading", body: "Shared body" } }]
         },
         ctx,
+        paths: sanityPaths,
         locate: () => [
             {
                 documentId: "page-1",
@@ -250,6 +260,7 @@ 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,
+        paths: sanityPaths,
         locate: () => ({
             documentId: "page-1",
             prefix: "",

package/dist/server/orchestrator.d.ts

@@ -1 +1 @@
-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";
+export { createOrchestrator, jsonFileAdapter, editorApiAdapter, resolveCapabilities, cmsMediaSource, cmsMediaLabel, type CreateOrchestratorConfig, type OrchestratorHandler, type OrchestratorAuth, type AuthContext, type CmsAdapter, type CmsCapabilities, type CmsInlineAsset, type CmsPublishContext, type CmsPublishResult, type CmsPerspective, type CmsReadOptions, type CmsMediaItem, type CmsMediaPage, type CmsMediaQuery, type CmsMediaSource, type CmsMediaSourceConfig, type ResolvedCapabilities } from "@avocadostudio-ai/orchestrator-core";

package/dist/server/orchestrator.js

@@ -11,4 +11,4 @@
 //
 // This file stays so `@avocadostudio-ai/site-sdk/server` — the entry point
 // every example, README and docs page uses — keeps resolving unchanged.
-export { createOrchestrator, jsonFileAdapter, editorApiAdapter, resolveCapabilities } from "@avocadostudio-ai/orchestrator-core";
+export { createOrchestrator, jsonFileAdapter, editorApiAdapter, resolveCapabilities, cmsMediaSource, cmsMediaLabel } from "@avocadostudio-ai/orchestrator-core";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/site-sdk",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -107,16 +107,16 @@
   ],
   "dependencies": {
     "zod": "^4.3.6",
-    "@avocadostudio-ai/blocks": "0.2.3",
-    "@avocadostudio-ai/shared": "0.2.3",
-    "@avocadostudio-ai/preview-adapter": "0.2.3"
+    "@avocadostudio-ai/blocks": "^0.3.1",
+    "@avocadostudio-ai/preview-adapter": "^0.3.1",
+    "@avocadostudio-ai/shared": "^0.3.1"
   },
   "peerDependencies": {
     "next": ">=15.0.0",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
     "better-sqlite3": ">=12.0.0",
-    "@avocadostudio-ai/orchestrator-core": "^0.2.3"
+    "@avocadostudio-ai/orchestrator-core": "^0.3.1"
   },
   "peerDependenciesMeta": {
     "@avocadostudio-ai/orchestrator-core": {
@@ -144,7 +144,7 @@
     "draft-mode"
   ],
   "license": "Apache-2.0",
-  "homepage": "https://github.com/avocadostudio-ai/avocado/tree/main/packages/site-sdk#readme",
+  "homepage": "https://docs.avocadostudio.dev",
   "bugs": {
     "url": "https://github.com/avocadostudio-ai/avocado/issues"
   },