@bettercms-ai/astro 0.10.0 → 0.11.0

package/README.md

@@ -112,9 +112,58 @@ or on-demand-revalidation hook.
 | `@bettercms-ai/astro/components/BcmsBlocks.astro` | Render a page's `blockJson` — every block type the builder can author (heading, text/richtext, image, button, spacer, video, columns, form, section, navbar, footer, slider, tabs, component), with block style tokens applied. |
 | `@bettercms-ai/astro/components/BcmsForm.astro` | Render + submit a form (conditional fields, honeypot, Turnstile). |
 | `@bettercms-ai/astro/components/BcmsImage.astro` | Optimized image with a 1x/2x srcset via the media transform endpoint. |
+| `@bettercms-ai/astro/components/BcmsLiveBlocks.astro` | `BcmsBlocks` as a hydrated island that lets the Visual Editor re-render your DRAFTS with your own components and CSS. See below. |
 
 Markup is class-driven and unstyled — you own the CSS.
 
+## Live editing on a static site — `<BcmsLiveBlocks>`
+
+When the Visual Editor frames a static build it can only show what was built, so editing a
+draft falls back to the platform's approximate renderer and the canvas stops looking like your
+site. `<BcmsLiveBlocks>` fixes that for pages whose body is a block tree: it renders the same
+markup `<BcmsBlocks>` does, but as a `client:load` island that accepts draft documents from the
+editor over `postMessage` (same-origin, parent frame only, and only after the editor's own
+handshake — a third-party page that iframes your site is on a foreign origin and gets nothing).
+Nothing is fetched by the page and no credentials enter it.
+
+It needs a JSX renderer, which a component cannot add for you:
+
+```sh
+npm i @astrojs/preact preact
+```
+
+```js
+// astro.config.mjs
+import preact from "@astrojs/preact";
+export default defineConfig({ integrations: [bettercms(), preact({ compat: true })] });
+```
+
+```astro
+---
+import BcmsLiveBlocks from "@bettercms-ai/astro/components/BcmsLiveBlocks.astro";
+const page = await getPage(Astro.params.slug);
+const { forms } = await readForms();
+---
+<BcmsLiveBlocks slug={page.slug} blocks={page.blocks} forms={forms} />
+```
+
+`compat: true` is required — the island reuses the React `<BcmsDraftBridge>` from
+`@bettercms-ai/next` so both SDKs speak one protocol. Roughly 10 kB of Preact plus the block
+renderer; `@astrojs/react` works too if your project already uses it.
+
+⚠️ **It emits the React class names, not this package's.** `<BcmsBlocks>` from
+[`@bettercms-ai/next`](https://www.npmjs.com/package/@bettercms-ai/next) classes its output
+`bcms-block bcms-block--text`, `bcms-button--primary`, `bcms-column`; `BcmsBlocks.astro` above
+classes the same tree `bcms-text`, `bcms-btn-primary`, `bcms-cols`. They are NOT interchangeable: a
+stylesheet written for the `.astro` grammar styles nothing on this island, so swapping a page over
+unstyles it. Cover both spellings — the starters wrap them in one `:is()` selector for exactly this
+reason — or take the class list from `@bettercms-ai/next`'s `src/blocks.tsx`.
+
+**It only helps pages you render through `BcmsBlocks`.** A hand-written `.astro` layout, or
+content pulled into your own components, is invisible to the bridge — for those, structural
+draft preview needs a server-rendered draft route instead (`output: 'server'` + the draft-mode
+routes below).
+
 ## Draft mode
 
 The integration injects `/api/bcms/draft/enable?token=<jwt>&redirect=/path` and

package/components/BcmsBlocks.astro

@@ -448,7 +448,12 @@ const pass = { forms, components, turnstileSiteKey, nested: true, fieldAddresses
             blocks={resolved.blocks}
             depth={depth + 1}
             seen={[...seen, resolved.id]}
-            containerAttrs={blockAttrs}
+            containerAttrs={{
+              ...blockAttrs,
+              "data-bcms-component": resolved.id,
+              "data-bcms-variant": "base",
+              "data-bcms-instance": block.id,
+            }}
             {...pass}
             fieldAddresses={componentInstanceAddresses(block.id, resolved.props)}
           />

package/components/BcmsLiveBlocks.astro

@@ -0,0 +1,72 @@
+---
+/**
+ * <BcmsLiveBlocks> — <BcmsBlocks>, but as a hydrated island that speaks the visual editor's
+ * draft bridge (E5 / FLO-1178).
+ *
+ * WHY IT IS NOT A .astro RENDERER. An .astro component is server-only: once the page is built
+ * there is nothing on the client to hand a new document to, so an Astro site can only show the
+ * editor a STATIC build and the canvas falls back to the platform's approximate renderer for
+ * every draft. The bridge needs a live component tree, and the only one that already exists,
+ * is at parity with this package, and speaks the protocol is <BcmsDraftBridge> from
+ * @bettercms-ai/next — which imports nothing from `next/*` (React and @bettercms-ai/* only),
+ * so it mounts here unchanged. Reused rather than reimplemented: one protocol, one twin to
+ * keep in step instead of two.
+ *
+ * RUNTIME: Preact + `compat`, verified by the P2-1 spike (see ../SPIKE.md — SSR and hydration
+ * of a heading + PortableText richtext + BcmsForm tree, both clean). The cost is real and worth
+ * naming: preact plus its compat aliases on the island (~10 kB of runtime, so `react` itself is
+ * never bundled even though @bettercms-ai/ui declares React peers), and `@bettercms-ai/next` as a
+ * dependency of this package.
+ *
+ * 🔴 THE CLASS NAMES ARE THE REACT GRAMMAR, NOT THIS PACKAGE'S. <BcmsBlocks> in @bettercms-ai/next
+ * emits `bcms-block bcms-block--text`, `bcms-button--primary`, `bcms-column`; BcmsBlocks.astro
+ * emits `bcms-text`, `bcms-btn-primary`, `bcms-cols`. Same markup shape, different hooks — a
+ * stylesheet written against the .astro grammar styles NOTHING here, and swapping a page from
+ * <BcmsBlocks> to <BcmsLiveBlocks> unstyles it. Either cover both spellings (the starters use
+ * `:is()` for exactly this) or read the React classes off @bettercms-ai/next's src/blocks.tsx.
+ *
+ * The consumer supplies the renderer, because an integration cannot be added from a component:
+ *
+ *   // astro.config.mjs
+ *   import preact from "@astrojs/preact";
+ *   export default defineConfig({ integrations: [bettercms(), preact({ compat: true })] });
+ *
+ *   ---
+ *   import BcmsLiveBlocks from "@bettercms-ai/astro/components/BcmsLiveBlocks.astro";
+ *   const page = await getPage(Astro.params.slug);
+ *   ---
+ *   <BcmsLiveBlocks slug={page.slug} blocks={page.blocks} forms={forms} />
+ *
+ * Standalone the island renders exactly what <BcmsBlocks> renders (inside the
+ * `data-bcms-canvas="bridge"` marker <div> that <BcmsDraftBridge> emits); the bridge only
+ * wakes when the editor frames the page and pushes a draft. This only helps pages whose body
+ * IS a block tree — a hand-written .astro layout is unreachable from here by construction.
+ */
+import { BcmsDraftBridge } from "@bettercms-ai/next/draft-bridge";
+import type { ContentBlock } from "@bettercms-ai/types";
+import type { DeliveryComponent, DeliveryForm } from "@bettercms-ai/sdk";
+
+interface Props {
+  /** The page's slug. A pushed draft is applied only when its slug matches. */
+  slug: string;
+  blocks: ContentBlock[];
+  forms?: DeliveryForm[];
+  components?: DeliveryComponent[];
+  turnstileSiteKey?: string;
+  apiBase?: string;
+  class?: string;
+}
+
+const { slug, blocks, forms, components, turnstileSiteKey, apiBase, class: className } = Astro.props;
+---
+
+<BcmsDraftBridge
+  client:load
+  slug={slug}
+  blocks={blocks}
+  forms={forms}
+  components={components}
+  turnstileSiteKey={turnstileSiteKey}
+  apiBase={apiBase}
+  className={className}
+/>

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@bettercms-ai/astro",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
-  "description": "The BetterCMS adapter for Astro \u2014 a `bettercms()` integration, a `bettercms:client` virtual module, typed content loaders, draft preview, and native .astro rendering components.",
+  "description": "The BetterCMS adapter for Astro — a `bettercms()` integration, a `bettercms:client` virtual module, typed content loaders, draft preview, and native .astro rendering components.",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -31,6 +31,7 @@
     "./draft-enable": "./dist/routes/draft-enable.js",
     "./draft-disable": "./dist/routes/draft-disable.js",
     "./components/BcmsBlocks.astro": "./components/BcmsBlocks.astro",
+    "./components/BcmsLiveBlocks.astro": "./components/BcmsLiveBlocks.astro",
     "./components/BcmsField.astro": "./components/BcmsField.astro",
     "./components/BcmsForm.astro": "./components/BcmsForm.astro",
     "./components/BcmsSearch.astro": "./components/BcmsSearch.astro",
@@ -56,20 +57,28 @@
     "@bettercms-ai/sdk": "^1.14.0",
     "@bettercms-ai/types": "^1.11.0",
     "@bettercms-ai/ui": "^0.6.0",
-    "@bettercms-ai/richtext": "^0.1.0"
+    "@bettercms-ai/richtext": "^0.2.0",
+    "@bettercms-ai/next": "^0.11.2"
   },
   "peerDependencies": {
-    "astro": ">=4"
+    "astro": ">=4",
+    "@astrojs/preact": ">=4"
   },
   "devDependencies": {
     "@types/node": "^20",
     "astro": "^5.0.0",
     "tsup": "^8.5.1",
     "typescript": "^5",
-    "vitest": "^4.1.4"
+    "vitest": "^4.1.4",
+    "@types/react": "^19.0.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
+  },
+  "peerDependenciesMeta": {
+    "@astrojs/preact": {
+      "optional": true
+    }
   }
 }