@avocadostudio-ai/site-sdk 0.3.0 → 0.3.2

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
@@ -266,6 +302,13 @@ 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`.
@@ -559,10 +602,15 @@ that guesses writes a URL where a reference belongs.
 
 If you did not embed your own source snapshot in block props, `onPublish`'s
 third argument carries `context.published` — the pages as your adapter last
-reported them. It is the copy taken at bootstrap, not a fresh read, so it is
-absent after a restart that reloaded the draft from storage. Treat `undefined`
-as "no baseline available", never as "the site was empty": publishing every
-field on that assumption is the overwrite all of this exists to prevent.
+reported them. It is the copy taken at bootstrap, not a fresh read, and it
+survives a restart that reloads the draft from storage: the orchestrator
+re-reads it on the next request, which is sound because nothing was published in
+between, so the CMS still holds exactly the content the lost copy was a copy of.
+
+It can still be `undefined` — the adapter read can fail, and baselines are
+evicted once enough sessions accumulate. Treat that as "no baseline available",
+never as "the site was empty": publishing every field on that assumption is the
+overwrite all of this exists to prevent.
 
 ## Registering your own block schemas
 
@@ -674,6 +722,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-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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/site-sdk",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -107,16 +107,16 @@
   ],
   "dependencies": {
     "zod": "^4.3.6",
-    "@avocadostudio-ai/preview-adapter": "^0.3.0",
-    "@avocadostudio-ai/blocks": "^0.3.0",
-    "@avocadostudio-ai/shared": "^0.3.0"
+    "@avocadostudio-ai/blocks": "^0.3.2",
+    "@avocadostudio-ai/preview-adapter": "^0.3.2",
+    "@avocadostudio-ai/shared": "^0.3.2"
   },
   "peerDependencies": {
     "next": ">=15.0.0",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
     "better-sqlite3": ">=12.0.0",
-    "@avocadostudio-ai/orchestrator-core": "^0.3.0"
+    "@avocadostudio-ai/orchestrator-core": "^0.3.2"
   },
   "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"
   },