@avocadostudio-ai/preview-adapter 0.2.1 → 0.2.3

package/README.md

@@ -0,0 +1,80 @@
+# @avocadostudio-ai/preview-adapter
+
+The bridge between a site rendering its own pages and the Avocado Studio editor
+framing it: the `postMessage` protocol (`site-editor/v1`), the selection and
+inline-editing overlay, and the live-draft store.
+
+Most integrations get this transitively through
+[`@avocadostudio-ai/site-sdk`](https://www.npmjs.com/package/@avocadostudio-ai/site-sdk)
+and never import it. **Install it directly if your site renders drafts with its
+own components** — see below.
+
+## Install
+
+```bash
+npm install @avocadostudio-ai/preview-adapter
+```
+
+## The one export you cannot get anywhere else
+
+`site-sdk/editor` re-exports `LivePreviewProvider` but **not**
+`useLivePreviewBlocks`, the hook that reads it. The SDK's own consumers of that
+hook (`RenderedBlocks`, `PreviewBlock`) render Avocado's built-in block library
+— which is exactly what a site with its own components cannot use.
+
+So rendering a live draft through your own renderer means reaching for this
+package:
+
+```tsx
+import { LivePreviewProvider, useLivePreviewBlocks } from "@avocadostudio-ai/preview-adapter"
+
+export function PreviewPage({ draft, ...rest }) {
+  return (
+    <LivePreviewProvider initialPage={draft}>
+      <PreviewBody draft={draft} {...rest} />
+    </LivePreviewProvider>
+  )
+}
+
+function PreviewBody({ draft, ...rest }) {
+  const live = useLivePreviewBlocks()          // streams as the user edits
+  return <MyPageBuilder blocks={live ?? draft.blocks} {...rest} />
+}
+```
+
+`useLivePreviewBridgeApi` gives you the bridge itself if you need to drive it.
+
+## Styles
+
+```tsx
+import "@avocadostudio-ai/preview-adapter/styles.css"
+```
+
+Required in the preview route. Without it the overlay's outlines, badges and
+field labels do not render, and a block that is genuinely selected looks like
+nothing happened.
+
+## Making fields editable
+
+The overlay finds a prop by the `data-editable-target="<propPath>"` attribute on
+the node that renders it — `heading`, `cards[0].title`, `cards[0].imageUrl`.
+Without those attributes you get block selection and no editable fields. This
+has to go inside your own components; nothing can add it from the outside. Full
+notes in
+[the site-sdk README](https://www.npmjs.com/package/@avocadostudio-ai/site-sdk#making-fields-editable).
+
+## Subpaths
+
+| Import | What it provides |
+|---|---|
+| `@avocadostudio-ai/preview-adapter` | `PreviewBridge`, `LivePreviewProvider`, `useLivePreviewBlocks`, `useLivePreviewBridgeApi`, `getPreviewWrapperProps`, and the bridge functions |
+| `.../core` | The same bridge without the Next-specific wrapper |
+| `.../styles.css` | The overlay stylesheet |
+
+## Peers
+
+`next >= 15`, `react >= 19`.
+
+## License
+
+Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/preview-adapter",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -32,7 +32,7 @@
     "src/styles.css"
   ],
   "dependencies": {
-    "@avocadostudio-ai/shared": "0.2.1"
+    "@avocadostudio-ai/shared": "0.2.3"
   },
   "peerDependencies": {
     "next": ">=15.0.0",
@@ -49,6 +49,15 @@
     "typescript": "^5.7.3"
   },
   "description": "Preview bridge and editor overlay for Avocado Studio live preview",
+  "keywords": [
+    "avocado",
+    "avocado-studio",
+    "nextjs",
+    "live-preview",
+    "visual-editing",
+    "postmessage",
+    "overlay"
+  ],
   "license": "Apache-2.0",
   "homepage": "https://github.com/avocadostudio-ai/avocado/tree/main/packages/preview-adapter#readme",
   "bugs": {