@bettercms-ai/mcp 0.83.0 → 0.83.2

package/dist/skills/bettercms/references/astro.md

@@ -1,148 +1,148 @@
----
-title: "Astro adapter"
-description: "The @bettercms-ai/astro integration: options and env precedence, draft preview, shipped components, bindings and Astro-specific traps."
----
-
-# @bettercms-ai/astro
-
-Read this when the repo has `astro.config.*`. Shared rules (hosting modes, env map, tags, value
-shapes) are in [frameworks.md](frameworks.md).
-
-## Integration
-
-Add `bettercms()` to `integrations` in `astro.config.*`. It:
-
-- adds the `@bettercms-ai/astro/middleware` middleware (order `pre`);
-- injects `/api/bcms/draft/enable` and `/api/bcms/draft/disable`;
-- sets a signed `bcms-draft` cookie when draft mode is enabled.
-
-Options win over env, env wins over the snapshot: `apiUrl` → `PUBLIC_BCMS_API_URL` → snapshot,
-`workspace` → `PUBLIC_BCMS_WORKSPACE` → snapshot, `projectId` → `PUBLIC_BCMS_PROJECT_ID`,
-`mediaUrl` → `PUBLIC_BCMS_MEDIA_URL` → the production CDN, `studioUrl` →
-`PUBLIC_BCMS_STUDIO_URL` (no default).
-
-`draft` defaults to `true`, which injects two ON-DEMAND routes (`/api/bcms/draft/{enable,disable}`).
-A static build with no server adapter then fails with `NoAdapterInstalled`. On a static site pass
-`bettercms({ draft: false })`; draft preview needs an adapter AND the Hosting page set to Run as a
-server app (see Hosting modes).
-
-`astro.config.*` runs before Astro loads `.env`, so `PUBLIC_BCMS_*` is empty there on a local
-build. Pass `apiUrl` and `workspace` as options, or let the snapshot supply them.
-
-## Draft preview
-
-- Set `BCMS_DRAFT_SECRET` on the server. Without it `/api/bcms/draft/enable` answers 500.
-- The draft routes run on request, so the site needs an on-demand adapter (node, vercel, netlify,
-  cloudflare). A fully static build serves the published snapshot only.
-
-## Components shipped
-
-| Import | Use |
-|---|---|
-| `@bettercms-ai/astro/components/BcmsBlocks.astro` | Server render of a block tree. Pass `components` or instances render nothing |
-| `@bettercms-ai/astro/components/BcmsSections.astro` | The page's own sections as named slots, drawn in the CMS page's order (below) |
-| `@bettercms-ai/astro/components/BcmsLiveBlocks.astro` | Same tree as a hydrated island that follows the editor's draft bridge |
-| `@bettercms-ai/astro/components/BcmsField.astro` | `path`, `kind` (`richtext`/`image`), `as`; emits `data-bcms-field` + `data-bcms-kind` on its single child element, with no wrapper ([animation.md](animation.md) §10) |
-| `@bettercms-ai/astro/components/BcmsButton.astro` | A `button` field: `path`, `value`, `class`. One `<a>` with the label bound, the href in `data-bcms-props` and `data-variant` / `data-size`. Style only the looks the site has ([components.md](components.md) §5); renders nothing without a label |
-| `@bettercms-ai/astro/components/BcmsForm.astro` | Renders a delivered form and submits it ([forms-and-interactions.md](forms-and-interactions.md)) |
-
-`BcmsLiveBlocks` rules:
-
-- It needs a React-compatible renderer: add `preact({ compat: true })` next to `bettercms()`.
-- Its CSS class names differ from `BcmsBlocks`. Swapping one for the other unstyles a page unless
-  your stylesheet covers both spellings.
-
-## Sections in the CMS order
-
-A page whose sections are written in its `.astro` file follows the CMS page's block list through
-`<BcmsSections>`. `bettercms init` writes this wrap (`npx @bettercms-ai/convert --sections`);
-write it by hand for a page the codemod refused ([componentize.md](componentize.md) §5):
-
-```astro
----
-import BcmsSections from "@bettercms-ai/astro/components/BcmsSections.astro";
----
-<Layout>
-  <BcmsSections page="home">
-    <Fragment slot="hero"><Hero title={title} /></Fragment>
-    <Fragment slot="code:sec1"><LogoStrip /></Fragment>
-    <Fragment slot="pricing">{plans.length > 0 && <Pricing plans={plans} />}</Fragment>
-  </BcmsSections>
-</Layout>
-```
-
-- `page` is the CMS page's slug. Each section is one `<Fragment slot="…">` around markup you do
-  not change. Anything with its own `slot="…"` (it targets the layout) stays outside.
-- A slot is named by its placement's bind: the family of the section's first bound field
-  (`pricing-title` → `pricing`), which is the `bind` on the page's `component` block.
-- A block bound to a slot renders it at the block's position. `data-bcms-block`, `data-bcms-style`
-  and the block's style go on the section's own root element; no element is added, so the stamp
-  never comes between a parent and a child a selector or an animation names
-  ([animation.md](animation.md) §10). A slot that renders several roots, or an island, is stamped
-  on a box: `display:contents` while its block has no style, one `display:flow-root` box once it
-  has. Give it one root element where the layout must not gain a box.
-- A section added in the editor (a block with no bind) is drawn by `BcmsBlocks`, which
-  `BcmsSections` imports itself: nothing to pass, and it builds whether or not `bettercms()` is
-  registered on that build (a config that adds it only with credentials still draws the section).
-- A slot no block names: `code:<bind>` always renders where it is written. A bare `<bind>` does
-  too until the list names one of the page's slots; from then on it is a removed section. Write
-  a slot bare only when the page already places that bind (`get_page`), otherwise `code:`.
-- No snapshot (a local build, the API down): every slot renders in source order, untouched.
-
-**A page that only draws a view.** Where the page file is a shell (`<HomeView locale="en" />`,
-alone or inside its layout) the sections are written in the view, and `--sections` wraps them
-there: it follows the import (relative, or a `paths` alias the repository's own tsconfig or
-jsconfig declares, index files included) up to three components down, to the first file that
-writes two or more sections or writes its run inside a layout. One view often serves several
-pages (`/` and `/fr`), so the view cannot name the page. Each page hands it down, and the view
-reads it:
-
-```astro
-<!-- src/pages/fr/index.astro -->
-<HomeView locale="fr" bcmsPage="fr" />
-
-<!-- src/views/HomeView.astro: `bcmsPage?: string` joins its Props -->
-<MainLayout>
-  <BcmsSections page={Astro.props.bcmsPage ?? ""}>
-    <Fragment slot="hero"><HeroSection title={copy.hero.title} /></Fragment>
-    …
-  </BcmsSections>
-</MainLayout>
-```
-
-Each page then follows its own CMS page's list through the one set of slots. A route that hands
-the view no page (the CMS has none for it yet) renders the source order. A slot is bare only
-when every page drawing the view places that bind. A dynamic route's view (`blog/[id].astro` →
-`BlogPostView`) is wrapped the same way with `template`. Write it by hand in this shape when the
-codemod refuses the view ([componentize.md](componentize.md) §5).
-- The list is the published snapshot's, or the draft's when the Visual Editor frames a
-  server-rendered page (`prerender = false`). `blocks={…}` gives it yourself.
-
-Check: build, then view source. `<!--bcms-sections:start page="home"-->` precedes the sections,
-and each placed section's root carries `data-bcms-block` and `data-bcms-style`.
-
-## Bindings
-
-A section root your own code renders spreads `sectionRootAttrs(block)` from `@bettercms-ai/astro`
-(`data-bcms-block`, `data-bcms-style` and the block's style), so the editor can move it and offer
-its spacing handles ([components.md](components.md) §5). It adds `data-bcms-hide` when `style.hideOn` is set: put `RESPONSIVE_CSS` (exported here) in your global CSS.
-
-`<BcmsBlocks>` does not render a block outside its `window`, read against the `now` prop (default:
-render time). Pass `showScheduled` on a draft preview to draw it, marked `data-bcms-window`
-([publishing.md](publishing.md) §6).
-
-`bind` and `bindProps` from `@bettercms-ai/astro/bindings` produce the same attributes as the Next
-helpers. Use them inside component instances so addresses resolve to the instance
-([bindings.md](bindings.md) §3).
-
-## Traps
-
-| Symptom | Cause | Rule |
-|---|---|---|
-| Resized images 404 on a non-production site | `mediaUrl` still the production default | Set `PUBLIC_BCMS_MEDIA_URL` to that rung's API origin |
-| Resized images still on the CDN after moving media | `mediaUrl` not changed | Set it to `mediaBaseUrl` from `get_project` |
-| Component instances empty | `components` prop missing | Pass definitions to `BcmsBlocks` |
-| A code section vanished after a build | Its slot is bare and the page's block list does not place its bind | Name it `code:<bind>`, or place the bind on the page |
-| Build fails on `bettercms:config` | A page imports `BcmsSearch` or the virtual module on a build where `bettercms()` is not registered | Register it unconditionally. `BcmsSections`, `BcmsBlocks`, `BcmsImage` and `BcmsForm` need no integration |
-| Draft link 500 | `BCMS_DRAFT_SECRET` unset | Set it on the server env, redeploy |
-| `ReferenceError: X is not defined` from a `[slug].astro` route | `getStaticPaths()` reads a `const` declared in the frontmatter; Astro runs it in its own scope, before the page, seeing only imports | Declare the client or reader call inside `getStaticPaths`, or import it from a module |
+---
+title: "Astro adapter"
+description: "The @bettercms-ai/astro integration: options and env precedence, draft preview, shipped components, bindings and Astro-specific traps."
+---
+
+# @bettercms-ai/astro
+
+Read this when the repo has `astro.config.*`. Shared rules (hosting modes, env map, tags, value
+shapes) are in [frameworks.md](frameworks.md).
+
+## Integration
+
+Add `bettercms()` to `integrations` in `astro.config.*`. It:
+
+- adds the `@bettercms-ai/astro/middleware` middleware (order `pre`);
+- injects `/api/bcms/draft/enable` and `/api/bcms/draft/disable`;
+- sets a signed `bcms-draft` cookie when draft mode is enabled.
+
+Options win over env, env wins over the snapshot: `apiUrl` → `PUBLIC_BCMS_API_URL` → snapshot,
+`workspace` → `PUBLIC_BCMS_WORKSPACE` → snapshot, `projectId` → `PUBLIC_BCMS_PROJECT_ID`,
+`mediaUrl` → `PUBLIC_BCMS_MEDIA_URL` → the production CDN, `studioUrl` →
+`PUBLIC_BCMS_STUDIO_URL` (no default).
+
+`draft` defaults to `true`, which injects two ON-DEMAND routes (`/api/bcms/draft/{enable,disable}`).
+A static build with no server adapter then fails with `NoAdapterInstalled`. On a static site pass
+`bettercms({ draft: false })`; draft preview needs an adapter AND the Hosting page set to Run as a
+server app (see Hosting modes).
+
+`astro.config.*` runs before Astro loads `.env`, so `PUBLIC_BCMS_*` is empty there on a local
+build. Pass `apiUrl` and `workspace` as options, or let the snapshot supply them.
+
+## Draft preview
+
+- Set `BCMS_DRAFT_SECRET` on the server. Without it `/api/bcms/draft/enable` answers 500.
+- The draft routes run on request, so the site needs an on-demand adapter (node, vercel, netlify,
+  cloudflare). A fully static build serves the published snapshot only.
+
+## Components shipped
+
+| Import | Use |
+|---|---|
+| `@bettercms-ai/astro/components/BcmsBlocks.astro` | Server render of a block tree. Pass `components` or instances render nothing |
+| `@bettercms-ai/astro/components/BcmsSections.astro` | The page's own sections as named slots, drawn in the CMS page's order (below) |
+| `@bettercms-ai/astro/components/BcmsLiveBlocks.astro` | Same tree as a hydrated island that follows the editor's draft bridge |
+| `@bettercms-ai/astro/components/BcmsField.astro` | `path`, `kind` (`richtext`/`image`), `as`; emits `data-bcms-field` + `data-bcms-kind` on its single child element, with no wrapper ([animation.md](animation.md) §10) |
+| `@bettercms-ai/astro/components/BcmsButton.astro` | A `button` field: `path`, `value`, `class`. One `<a>` with the label bound, the href in `data-bcms-props` and `data-variant` / `data-size`. Style only the looks the site has ([components.md](components.md) §5); renders nothing without a label |
+| `@bettercms-ai/astro/components/BcmsForm.astro` | Renders a delivered form and submits it ([forms-and-interactions.md](forms-and-interactions.md)) |
+
+`BcmsLiveBlocks` rules:
+
+- It needs a React-compatible renderer: add `preact({ compat: true })` next to `bettercms()`.
+- Its CSS class names differ from `BcmsBlocks`. Swapping one for the other unstyles a page unless
+  your stylesheet covers both spellings.
+
+## Sections in the CMS order
+
+A page whose sections are written in its `.astro` file follows the CMS page's block list through
+`<BcmsSections>`. `bettercms init` writes this wrap (`npx @bettercms-ai/convert --sections`);
+write it by hand for a page the codemod refused ([componentize.md](componentize.md) §5):
+
+```astro
+---
+import BcmsSections from "@bettercms-ai/astro/components/BcmsSections.astro";
+---
+<Layout>
+  <BcmsSections page="home">
+    <Fragment slot="hero"><Hero title={title} /></Fragment>
+    <Fragment slot="code:sec1"><LogoStrip /></Fragment>
+    <Fragment slot="pricing">{plans.length > 0 && <Pricing plans={plans} />}</Fragment>
+  </BcmsSections>
+</Layout>
+```
+
+- `page` is the CMS page's slug. Each section is one `<Fragment slot="…">` around markup you do
+  not change. Anything with its own `slot="…"` (it targets the layout) stays outside.
+- A slot is named by its placement's bind: the family of the section's first bound field
+  (`pricing-title` → `pricing`), which is the `bind` on the page's `component` block.
+- A block bound to a slot renders it at the block's position. `data-bcms-block`, `data-bcms-style`
+  and the block's style go on the section's own root element; no element is added, so the stamp
+  never comes between a parent and a child a selector or an animation names
+  ([animation.md](animation.md) §10). A slot that renders several roots, or an island, is stamped
+  on a box: `display:contents` while its block has no style, one `display:flow-root` box once it
+  has. Give it one root element where the layout must not gain a box.
+- A section added in the editor (a block with no bind) is drawn by `BcmsBlocks`, which
+  `BcmsSections` imports itself: nothing to pass, and it builds whether or not `bettercms()` is
+  registered on that build (a config that adds it only with credentials still draws the section).
+- A slot no block names: `code:<bind>` always renders where it is written. A bare `<bind>` does
+  too until the list names one of the page's slots; from then on it is a removed section. Write
+  a slot bare only when the page already places that bind (`get_page`), otherwise `code:`.
+- No snapshot (a local build, the API down): every slot renders in source order, untouched.
+
+**A page that only draws a view.** Where the page file is a shell (`<HomeView locale="en" />`,
+alone or inside its layout) the sections are written in the view, and `--sections` wraps them
+there: it follows the import (relative, or a `paths` alias the repository's own tsconfig or
+jsconfig declares, index files included) up to three components down, to the first file that
+writes two or more sections or writes its run inside a layout. One view often serves several
+pages (`/` and `/fr`), so the view cannot name the page. Each page hands it down, and the view
+reads it:
+
+```astro
+<!-- src/pages/fr/index.astro -->
+<HomeView locale="fr" bcmsPage="fr" />
+
+<!-- src/views/HomeView.astro: `bcmsPage?: string` joins its Props -->
+<MainLayout>
+  <BcmsSections page={Astro.props.bcmsPage ?? ""}>
+    <Fragment slot="hero"><HeroSection title={copy.hero.title} /></Fragment>
+    …
+  </BcmsSections>
+</MainLayout>
+```
+
+Each page then follows its own CMS page's list through the one set of slots. A route that hands
+the view no page (the CMS has none for it yet) renders the source order. A slot is bare only
+when every page drawing the view places that bind. A dynamic route's view (`blog/[id].astro` →
+`BlogPostView`) is wrapped the same way with `template`. Write it by hand in this shape when the
+codemod refuses the view ([componentize.md](componentize.md) §5).
+- The list is the published snapshot's, or the draft's when the Visual Editor frames a
+  server-rendered page (`prerender = false`). `blocks={…}` gives it yourself.
+
+Check: build, then view source. `<!--bcms-sections:start page="home"-->` precedes the sections,
+and each placed section's root carries `data-bcms-block` and `data-bcms-style`.
+
+## Bindings
+
+A section root your own code renders spreads `sectionRootAttrs(block)` from `@bettercms-ai/astro`
+(`data-bcms-block`, `data-bcms-style` and the block's style), so the editor can move it and offer
+its spacing handles ([components.md](components.md) §5). It adds `data-bcms-hide` when `style.hideOn` is set: put `RESPONSIVE_CSS` (exported here) in your global CSS.
+
+`<BcmsBlocks>` does not render a block outside its `window`, read against the `now` prop (default:
+render time). Pass `showScheduled` on a draft preview to draw it, marked `data-bcms-window`
+([publishing.md](publishing.md) §6).
+
+`bind` and `bindProps` from `@bettercms-ai/astro/bindings` produce the same attributes as the Next
+helpers. Use them inside component instances so addresses resolve to the instance
+([bindings.md](bindings.md) §3).
+
+## Traps
+
+| Symptom | Cause | Rule |
+|---|---|---|
+| Resized images 404 on a non-production site | `mediaUrl` still the production default | Set `PUBLIC_BCMS_MEDIA_URL` to that rung's API origin |
+| Resized images still on the CDN after moving media | `mediaUrl` not changed | Set it to `mediaBaseUrl` from `get_project` |
+| Component instances empty | `components` prop missing | Pass definitions to `BcmsBlocks` |
+| A code section vanished after a build | Its slot is bare and the page's block list does not place its bind | Name it `code:<bind>`, or place the bind on the page |
+| Build fails on `bettercms:config` | A page imports `BcmsSearch` or the virtual module on a build where `bettercms()` is not registered | Register it unconditionally. `BcmsSections`, `BcmsBlocks`, `BcmsImage` and `BcmsForm` need no integration |
+| Draft link 500 | `BCMS_DRAFT_SECRET` unset | Set it on the server env, redeploy |
+| `ReferenceError: X is not defined` from a `[slug].astro` route | `getStaticPaths()` reads a `const` declared in the frontmatter; Astro runs it in its own scope, before the page, seeing only imports | Declare the client or reader call inside `getStaticPaths`, or import it from a module |