@bettercms-ai/mcp 0.83.0 → 0.83.2

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

@@ -1,296 +1,296 @@
----
-title: "Animated sites"
-description: "Keeping GSAP, ScrollTrigger, SplitText, Framer Motion, Lenis, marquees, carousels, Lottie and hydrated islands working while their copy stays editable and publishable."
----
-
-# Animated sites: editable copy that keeps moving
-
-Read this when `package.json` lists `gsap`, `lenis`, `locomotive-scroll`, `framer-motion` or
-`motion`, `swiper`, `split-type`, `splitting`, `lottie-web`, `three` or `@react-three/fiber`, or
-when the built HTML carries
-`astro-island`, split-text spans or a duplicated marquee track. Attribute grammar:
-[bindings.md](bindings.md). Adapter wiring: [frameworks.md](frameworks.md).
-
-## 1. What a publish does to animated markup
-
-The bound element picks the writer. One that holds text and nothing else is replaced whole, as
-it always was. One that holds markup (inline elements, split spans, a `<br>`, or
-`data-bcms-split`) is written into its text nodes, and every element inside it is kept. That is
-what the recipes below rely on:
-
-| The page has | A publish does |
-|---|---|
-| Inline markup inside the bound element (`<em>`, a highlight `<span>`, `<br>`) | changes the words, keeps the elements and their attributes; a bare `<em>` or `<span>` the new words leave empty is removed |
-| Text cut into `word` / `char` / `line` spans, same word count | writes each span in place |
-| The same, word count changed, spans made by a library at runtime | puts the plain text back; the library splits it on its next run |
-| The same, spans written by your own template | rebuilds them from their own pattern, a new one copied from the last |
-| A split headline under an `aria-label` that says the same words (SplitText's own output) | one field on the headline: writes the label and the words |
-| A counter with its number in `data-target`, `data-count` or a like attribute | writes the attribute; writes the number shown only where it showed the old target, never a script's starting `0` |
-| A copy of the value under `aria-hidden="true"` or `data-bcms-clone` | writes the copy too (coverage kind `duplicate-track`) |
-| The value inside `astro-island` props, `__NEXT_DATA__` or the app router's flight scripts | rewrites the serialized string (coverage kind `island-props`) |
-
-It refuses, and says so on the publish, when the change would have to remove something:
-`TEXT_IN_CHILD_FIELD` (the words belong to a field declared inside this one),
-`TEXT_EMPTIES_ELEMENT` (a link, a scripted element or a wrapper with attributes would be left empty),
-`SPLIT_PATTERN_UNKNOWN` (split markup that is not one row of like tokens) and
-`ISLAND_PROPS_UNMATCHED` (a hydrated island draws the text from props that do not hold it).
-Each is fixed in the template with the recipe for its library.
-
-The last two rows follow a value only where the element was written into its text nodes. An
-operator can switch a project, or the fleet, to write every text value that way, so a plain-text
-value's copies and props follow it too; and can switch the text-node writer off, after which a
-publish replaces an element's content with plain text and refuses what that would break.
-
-## 2. Two rules for every library
-
-1. **Bind the element that holds the words, never the element the animation owns.** A pinned
-   section, a scroll wrapper, a slider track and a motion container are layout. Their text
-   leaves are the fields.
-2. **Refresh measurements after an edit.** The editor posts `{ type: "bcms:content-applied" }`
-   to the page's window after it applies an edit. Longer copy changes heights, so anything that
-   measured the page must measure again:
-
-```js
-window.addEventListener("message", (event) => {
-  if (event.data?.type !== "bcms:content-applied") return;
-  ScrollTrigger.refresh();   // or lenis.resize(), swiper.update(), split.revert() then split again
-});
-```
-
-`onContentApplied(handler)` from `@bettercms-ai/sdk` is the same listener with the check
-written for you. On a published page nothing posts the message and the listener never runs.
-
-## 3. GSAP and ScrollTrigger
-
-```html
-<section class="pin-wrap">                      <!-- trigger and pin: no field -->
-  <div class="pin">
-    <h2 data-bcms-field="story.title">Built to last</h2>
-    <p data-bcms-field="story.lead">Forged, not cast.</p>
-  </div>
-</section>
-```
-
-```js
-gsap.to(".pin h2", { yPercent: -20, scrollTrigger: { trigger: ".pin-wrap", pin: ".pin", scrub: 1 } });
-```
-
-Never put `data-bcms-field` on `.pin-wrap` or `.pin`: ScrollTrigger wraps a pinned element in
-a spacer and writes inline styles on it every frame. Use `<BcmsField>` only around a single
-element, where it adds no wrapper (section 10); a wrapper span between `.pin` and its `h2`
-would break `.pin > h2`.
-
-Check: with the page open, `ScrollTrigger.getAll().length` is the same before and after a
-publish of every field on the route.
-
-## 4. SplitText, SplitType, Splitting.js
-
-Bind the parent and say that it is split. Never bind a word or a character.
-
-```html
-<h1 class="js-split" data-bcms-field="hero.title" data-bcms-split="words">Fast screws, shipped</h1>
-```
-
-```js
-let split = new SplitText(".js-split", { type: "words" });
-window.addEventListener("message", (event) => {
-  if (event.data?.type !== "bcms:content-applied") return;
-  split.revert();
-  split = new SplitText(".js-split", { type: "words" });
-});
-```
-
-`data-bcms-split` takes `chars`, `words` or `lines`. It tells the editor that the spans under
-this element are one value, and it tells a publish that the children are tokens even when their
-class is not `word`, `char` or `line`.
-
-When your own template writes the spans (`title.split(" ").map(...)`), keep them one row of
-the same tag, with whitespace or nothing between them, and no other element in the row:
-
-```astro
-<h1 data-bcms-field="hero.title" data-bcms-split="words">
-  {title.split(" ").map((word) => <span class="word">{word}</span>)}
-</h1>
-```
-
-A `<br>` between two word spans makes the row unreadable once the word count changes
-(`SPLIT_PATTERN_UNKNOWN`): put the break in CSS, or split by lines.
-
-Check: publish a title with one more word, reload, and count `.word`: it equals the new word
-count and no word sits outside a span.
-
-## 5. Framer Motion
-
-```tsx
-<motion.section initial={{ opacity: 0 }} whileInView={{ opacity: 1 }}>   {/* no field */}
-  <motion.h2 data-bcms-field="story.title" variants={rise}>{story.title}</motion.h2>
-  <p data-bcms-field="story.lead">{story.lead}</p>
-</motion.section>
-```
-
-Put `data-bcms-field` straight on the motion element that renders the text: it passes
-`data-*` through to the DOM. Do not wrap a motion component in `<BcmsField>`; a component child
-keeps the wrapper span, and `layout` animations measure the wrong box. For words animated one
-by one, map them to `motion.span` under a parent carrying `data-bcms-split="words"`, as in
-section 4. The component hydrates, so section 9 applies to its props.
-
-Check: the built HTML for the route shows `data-bcms-field` on the `h2` itself, with no
-`display:contents` span around it.
-
-## 6. Lenis and other smooth scroll
-
-Lenis moves the page, not the content, so no binding changes. Two things do:
-
-```js
-const lenis = new Lenis();
-window.addEventListener("message", (event) => {
-  if (event.data?.type === "bcms:content-applied") lenis.resize();
-});
-```
-
-and any panel of yours that must scroll by itself inside the page takes `data-lenis-prevent`.
-Never bind the element Lenis is given as `wrapper` or `content`.
-
-In the Visual Editor the canvas owns the scroll: it marks the page's `<body>` with
-`data-lenis-prevent`, so the wheel there is the browser's own and has no easing. That is the
-editor, not a fault in the site: Lenis still reports every scroll (ScrollTrigger and anything
-else hung on `lenis.on("scroll")` runs), its own `scrollTo` still eases, and the published page
-is untouched. Do not remove the attribute or "repair" the easing for the canvas. What other
-scroll libraries need there is in section 12.
-
-Check: after an edit that adds two lines to a paragraph, the page still scrolls to the footer.
-
-## 7. Marquees and duplicated tracks
-
-Render the track once with fields, and mark every copy:
-
-```astro
-<div class="marquee">
-  <ul class="track">{logos.map((l, i) => <li class="logo" data-bcms-field={`logos[${i}].name`}>{l.name}</li>)}</ul>
-  <ul class="track" aria-hidden="true" data-bcms-clone>{logos.map((l) => <li class="logo">{l.name}</li>)}</ul>
-</div>
-```
-
-A copy under `aria-hidden="true"` or `data-bcms-clone` is not counted as unowned text, and a
-publish writes it with the original when it is the same tag with the same classes and the same
-text. A copy with neither marker is separate copy: it counts against the route's text coverage
-and keeps the old words. A script that clones the track in the browser needs nothing: the clone
-is made from the published HTML on every load.
-
-Check: publish one logo name, then `document.querySelectorAll(".track")` shows the new name in
-every track.
-
-## 8. Swiper and carousels
-
-Bind what is inside a slide, never `.swiper-wrapper` or `.swiper-slide`:
-
-```html
-<div class="swiper-slide"><h3 data-bcms-field="slides[0].title">Torque</h3></div>
-```
-
-Loop mode clones slides in the browser (`.swiper-slide-duplicate`); those are made from the
-published HTML and need no field. On `bcms:content-applied`, call `swiper.update()`.
-
-Check: `get_binding_report` lists no `slides[n]` path as pending for the route.
-
-## 9. Hydrated islands and `client:only`
-
-A hydrated component draws itself again from the props the build serialized. Keep the text it
-shows equal to one string prop, whole:
-
-```astro
-<Hero client:load title={page.hero.title} />
-```
-
-```tsx
-export default function Hero({ title }) { return <h1 data-bcms-field="hero.title">{title}</h1>; }
-```
-
-A publish then rewrites that prop with the text. It cannot when the component builds the text
-(`${title}!`, `title.toUpperCase()`, a string literal in the component), or when the props hold
-the same words more than once, under a key such as `id` or `slug`, or as `__html`: the publish reports
-`ISLAND_PROPS_UNMATCHED` and the value goes live with the next build. Content passed as a
-slot is plain HTML and needs no prop.
-
-`client:only` renders nothing at build time, so the built page has no copy to own. The release
-names every such island on its route and the setup gate lists it as a `client-only-island`
-exception by itself. To make the copy editable, change the directive to `client:load` or
-`client:visible`, or pass the copy in as a slot.
-
-Check: view source on the built route, find the `astro-island`, and its `props` attribute holds
-the published title after a publish.
-
-## 10. `<BcmsField>` adds no wrapper around one element
-
-```astro
-<BcmsField path="hero.title"><h1 class="title">{page.hero.title}</h1></BcmsField>
-```
-
-renders `<h1 class="title" data-bcms-field="hero.title">`: nothing sits between the parent and
-the heading. Text, several children, and in Next a component child are still wrapped in a
-`display:contents` span, and `as="div"` still gives a real wrapper. A site built with an older
-package version keeps its wrapper spans until it is rebuilt.
-
-`<BcmsSections>` follows the same rule for a whole section: the block id, the style marker and
-the block's style go on the section's own root, and in Astro the list is delimited by two HTML
-comments, never an element. `main > section`, `:first-child` and a ScrollTrigger on `.hero` match
-what they matched before. The one exception is a section that is not one element (several roots,
-an island, in Next a component child with no function form): it gets a box of ours, a node
-between `main` and the section. With no style on the block the box is `display:contents` and
-draws nothing. Once the block has a style the box is `display:flow-root` and carries it: one
-block box, so in a flex or grid parent its children are one item instead of several, and their
-margins stop collapsing with the neighbours'. Give such a section one root element, or the
-function form ([next.md](next.md)), when a selector or the layout depends on it.
-
-## 11. Lottie, canvas, WebGL, video
-
-Pixels drawn by a script are not in the HTML, so nothing in them is a field by itself. What is
-editable is what you pass in:
-
-| Drawn by | Make editable by |
-|---|---|
-| Lottie | Bind the animation file as an image-or-file field on the container and load `path` from it. For words inside the animation, keep a text layer named after the field and set it at load (`anim.renderer.elements[i].updateDocumentData({ t: value })`), reading the value from a hidden bound element or a prop. |
-| Canvas / WebGL / three.js | Read every string and texture URL from `data-*` attributes or props on the canvas's container; bind a visually hidden element per string and an `<img hidden>` per texture, and re-read them on `bcms:content-applied`. |
-| Video | The poster and the source are fields on the `<video>`; burned-in captions are not text. |
-
-Give the canvas `role="img"` and an `aria-label` bound to a field, or an adjacent caption. A
-scene with no text a visitor reads needs no field; record it under the `decorative` exception.
-
-A canvas drawn over the page (a fixed full-screen scene behind or above the copy) does not block
-the editor: a click looks through an element that is no field and no control to the field under
-it. Keep the copy in the HTML above or below the canvas, never only inside the scene.
-
-Check: change the bound string, publish, reload: the drawn text reads the new value.
-
-## 12. In the editor's canvas
-
-The Visual Editor shows the real page with its scripts running, and owns three things there: the
-scroll (the page scrolls its own window, as it does live), the pointer (a click selects a field)
-and the place on the page (picking a field in the panel scrolls to it). Motion that reads the
-window's scroll or the clock runs there as it does live. Only what takes one of those three away
-has to stand down, and the site decides that with one question:
-
-```js
-import { inEditor } from "@bettercms-ai/sdk";   // 1.31+. Without the SDK: window.name === "bcms-editor"
-
-const smooth = inEditor() ? null : new LocomotiveScroll({ el, smooth: true });
-```
-
-`inEditor()` is true from the page's first script and through every navigation inside the
-canvas, and false on the published page. What each kind of page does there:
-
-| The page uses | In the canvas | You write |
-|---|---|---|
-| Native scroll, CSS scroll-driven animations (`animation-timeline`), Motion `useScroll` / `whileInView`, ScrollTrigger pin and scrub | runs as live | nothing |
-| Lenis, Locomotive Scroll 5 | runs; the wheel has no easing (section 6) | nothing |
-| GSAP ScrollSmoother | runs; the window still scrolls, the content eases behind it | nothing |
-| Locomotive Scroll 4, any script that locks the window and moves the content by a transform | the page works under its own wheel, but the editor cannot scroll it and a field picked in the panel is not brought into view | `smooth: !inEditor()`, so the window scrolls |
-| A wheel-driven slide deck (GSAP `Observer`, fullPage) | the same | do not create the observer when `inEditor()`; let the sections stack and scroll |
-| A scene with its own scroll layer (react-three-fiber `ScrollControls`, a fixed `overflow: auto` layer) | runs; picking a field scrolls that layer | nothing |
-| An intro or preloader that holds the page (`overflow: hidden` until it ends, a full-screen cover) | plays on every reload of the canvas, and covers the page while it does | skip it when `inEditor()` |
-
-Never use `inEditor()` to change what a field renders, to hide a section or to stop a timeline:
-the canvas must show what a visitor gets. It is for scroll takeover, intros and nothing else.
-
-Check: open the page in the Visual Editor, scroll with the wheel, drag the page's scrollbar to the
-footer, then pick a field of the first section in the panel: the canvas returns to it.
+---
+title: "Animated sites"
+description: "Keeping GSAP, ScrollTrigger, SplitText, Framer Motion, Lenis, marquees, carousels, Lottie and hydrated islands working while their copy stays editable and publishable."
+---
+
+# Animated sites: editable copy that keeps moving
+
+Read this when `package.json` lists `gsap`, `lenis`, `locomotive-scroll`, `framer-motion` or
+`motion`, `swiper`, `split-type`, `splitting`, `lottie-web`, `three` or `@react-three/fiber`, or
+when the built HTML carries
+`astro-island`, split-text spans or a duplicated marquee track. Attribute grammar:
+[bindings.md](bindings.md). Adapter wiring: [frameworks.md](frameworks.md).
+
+## 1. What a publish does to animated markup
+
+The bound element picks the writer. One that holds text and nothing else is replaced whole, as
+it always was. One that holds markup (inline elements, split spans, a `<br>`, or
+`data-bcms-split`) is written into its text nodes, and every element inside it is kept. That is
+what the recipes below rely on:
+
+| The page has | A publish does |
+|---|---|
+| Inline markup inside the bound element (`<em>`, a highlight `<span>`, `<br>`) | changes the words, keeps the elements and their attributes; a bare `<em>` or `<span>` the new words leave empty is removed |
+| Text cut into `word` / `char` / `line` spans, same word count | writes each span in place |
+| The same, word count changed, spans made by a library at runtime | puts the plain text back; the library splits it on its next run |
+| The same, spans written by your own template | rebuilds them from their own pattern, a new one copied from the last |
+| A split headline under an `aria-label` that says the same words (SplitText's own output) | one field on the headline: writes the label and the words |
+| A counter with its number in `data-target`, `data-count` or a like attribute | writes the attribute; writes the number shown only where it showed the old target, never a script's starting `0` |
+| A copy of the value under `aria-hidden="true"` or `data-bcms-clone` | writes the copy too (coverage kind `duplicate-track`) |
+| The value inside `astro-island` props, `__NEXT_DATA__` or the app router's flight scripts | rewrites the serialized string (coverage kind `island-props`) |
+
+It refuses, and says so on the publish, when the change would have to remove something:
+`TEXT_IN_CHILD_FIELD` (the words belong to a field declared inside this one),
+`TEXT_EMPTIES_ELEMENT` (a link, a scripted element or a wrapper with attributes would be left empty),
+`SPLIT_PATTERN_UNKNOWN` (split markup that is not one row of like tokens) and
+`ISLAND_PROPS_UNMATCHED` (a hydrated island draws the text from props that do not hold it).
+Each is fixed in the template with the recipe for its library.
+
+The last two rows follow a value only where the element was written into its text nodes. An
+operator can switch a project, or the fleet, to write every text value that way, so a plain-text
+value's copies and props follow it too; and can switch the text-node writer off, after which a
+publish replaces an element's content with plain text and refuses what that would break.
+
+## 2. Two rules for every library
+
+1. **Bind the element that holds the words, never the element the animation owns.** A pinned
+   section, a scroll wrapper, a slider track and a motion container are layout. Their text
+   leaves are the fields.
+2. **Refresh measurements after an edit.** The editor posts `{ type: "bcms:content-applied" }`
+   to the page's window after it applies an edit. Longer copy changes heights, so anything that
+   measured the page must measure again:
+
+```js
+window.addEventListener("message", (event) => {
+  if (event.data?.type !== "bcms:content-applied") return;
+  ScrollTrigger.refresh();   // or lenis.resize(), swiper.update(), split.revert() then split again
+});
+```
+
+`onContentApplied(handler)` from `@bettercms-ai/sdk` is the same listener with the check
+written for you. On a published page nothing posts the message and the listener never runs.
+
+## 3. GSAP and ScrollTrigger
+
+```html
+<section class="pin-wrap">                      <!-- trigger and pin: no field -->
+  <div class="pin">
+    <h2 data-bcms-field="story.title">Built to last</h2>
+    <p data-bcms-field="story.lead">Forged, not cast.</p>
+  </div>
+</section>
+```
+
+```js
+gsap.to(".pin h2", { yPercent: -20, scrollTrigger: { trigger: ".pin-wrap", pin: ".pin", scrub: 1 } });
+```
+
+Never put `data-bcms-field` on `.pin-wrap` or `.pin`: ScrollTrigger wraps a pinned element in
+a spacer and writes inline styles on it every frame. Use `<BcmsField>` only around a single
+element, where it adds no wrapper (section 10); a wrapper span between `.pin` and its `h2`
+would break `.pin > h2`.
+
+Check: with the page open, `ScrollTrigger.getAll().length` is the same before and after a
+publish of every field on the route.
+
+## 4. SplitText, SplitType, Splitting.js
+
+Bind the parent and say that it is split. Never bind a word or a character.
+
+```html
+<h1 class="js-split" data-bcms-field="hero.title" data-bcms-split="words">Fast screws, shipped</h1>
+```
+
+```js
+let split = new SplitText(".js-split", { type: "words" });
+window.addEventListener("message", (event) => {
+  if (event.data?.type !== "bcms:content-applied") return;
+  split.revert();
+  split = new SplitText(".js-split", { type: "words" });
+});
+```
+
+`data-bcms-split` takes `chars`, `words` or `lines`. It tells the editor that the spans under
+this element are one value, and it tells a publish that the children are tokens even when their
+class is not `word`, `char` or `line`.
+
+When your own template writes the spans (`title.split(" ").map(...)`), keep them one row of
+the same tag, with whitespace or nothing between them, and no other element in the row:
+
+```astro
+<h1 data-bcms-field="hero.title" data-bcms-split="words">
+  {title.split(" ").map((word) => <span class="word">{word}</span>)}
+</h1>
+```
+
+A `<br>` between two word spans makes the row unreadable once the word count changes
+(`SPLIT_PATTERN_UNKNOWN`): put the break in CSS, or split by lines.
+
+Check: publish a title with one more word, reload, and count `.word`: it equals the new word
+count and no word sits outside a span.
+
+## 5. Framer Motion
+
+```tsx
+<motion.section initial={{ opacity: 0 }} whileInView={{ opacity: 1 }}>   {/* no field */}
+  <motion.h2 data-bcms-field="story.title" variants={rise}>{story.title}</motion.h2>
+  <p data-bcms-field="story.lead">{story.lead}</p>
+</motion.section>
+```
+
+Put `data-bcms-field` straight on the motion element that renders the text: it passes
+`data-*` through to the DOM. Do not wrap a motion component in `<BcmsField>`; a component child
+keeps the wrapper span, and `layout` animations measure the wrong box. For words animated one
+by one, map them to `motion.span` under a parent carrying `data-bcms-split="words"`, as in
+section 4. The component hydrates, so section 9 applies to its props.
+
+Check: the built HTML for the route shows `data-bcms-field` on the `h2` itself, with no
+`display:contents` span around it.
+
+## 6. Lenis and other smooth scroll
+
+Lenis moves the page, not the content, so no binding changes. Two things do:
+
+```js
+const lenis = new Lenis();
+window.addEventListener("message", (event) => {
+  if (event.data?.type === "bcms:content-applied") lenis.resize();
+});
+```
+
+and any panel of yours that must scroll by itself inside the page takes `data-lenis-prevent`.
+Never bind the element Lenis is given as `wrapper` or `content`.
+
+In the Visual Editor the canvas owns the scroll: it marks the page's `<body>` with
+`data-lenis-prevent`, so the wheel there is the browser's own and has no easing. That is the
+editor, not a fault in the site: Lenis still reports every scroll (ScrollTrigger and anything
+else hung on `lenis.on("scroll")` runs), its own `scrollTo` still eases, and the published page
+is untouched. Do not remove the attribute or "repair" the easing for the canvas. What other
+scroll libraries need there is in section 12.
+
+Check: after an edit that adds two lines to a paragraph, the page still scrolls to the footer.
+
+## 7. Marquees and duplicated tracks
+
+Render the track once with fields, and mark every copy:
+
+```astro
+<div class="marquee">
+  <ul class="track">{logos.map((l, i) => <li class="logo" data-bcms-field={`logos[${i}].name`}>{l.name}</li>)}</ul>
+  <ul class="track" aria-hidden="true" data-bcms-clone>{logos.map((l) => <li class="logo">{l.name}</li>)}</ul>
+</div>
+```
+
+A copy under `aria-hidden="true"` or `data-bcms-clone` is not counted as unowned text, and a
+publish writes it with the original when it is the same tag with the same classes and the same
+text. A copy with neither marker is separate copy: it counts against the route's text coverage
+and keeps the old words. A script that clones the track in the browser needs nothing: the clone
+is made from the published HTML on every load.
+
+Check: publish one logo name, then `document.querySelectorAll(".track")` shows the new name in
+every track.
+
+## 8. Swiper and carousels
+
+Bind what is inside a slide, never `.swiper-wrapper` or `.swiper-slide`:
+
+```html
+<div class="swiper-slide"><h3 data-bcms-field="slides[0].title">Torque</h3></div>
+```
+
+Loop mode clones slides in the browser (`.swiper-slide-duplicate`); those are made from the
+published HTML and need no field. On `bcms:content-applied`, call `swiper.update()`.
+
+Check: `get_binding_report` lists no `slides[n]` path as pending for the route.
+
+## 9. Hydrated islands and `client:only`
+
+A hydrated component draws itself again from the props the build serialized. Keep the text it
+shows equal to one string prop, whole:
+
+```astro
+<Hero client:load title={page.hero.title} />
+```
+
+```tsx
+export default function Hero({ title }) { return <h1 data-bcms-field="hero.title">{title}</h1>; }
+```
+
+A publish then rewrites that prop with the text. It cannot when the component builds the text
+(`${title}!`, `title.toUpperCase()`, a string literal in the component), or when the props hold
+the same words more than once, under a key such as `id` or `slug`, or as `__html`: the publish reports
+`ISLAND_PROPS_UNMATCHED` and the value goes live with the next build. Content passed as a
+slot is plain HTML and needs no prop.
+
+`client:only` renders nothing at build time, so the built page has no copy to own. The release
+names every such island on its route and the setup gate lists it as a `client-only-island`
+exception by itself. To make the copy editable, change the directive to `client:load` or
+`client:visible`, or pass the copy in as a slot.
+
+Check: view source on the built route, find the `astro-island`, and its `props` attribute holds
+the published title after a publish.
+
+## 10. `<BcmsField>` adds no wrapper around one element
+
+```astro
+<BcmsField path="hero.title"><h1 class="title">{page.hero.title}</h1></BcmsField>
+```
+
+renders `<h1 class="title" data-bcms-field="hero.title">`: nothing sits between the parent and
+the heading. Text, several children, and in Next a component child are still wrapped in a
+`display:contents` span, and `as="div"` still gives a real wrapper. A site built with an older
+package version keeps its wrapper spans until it is rebuilt.
+
+`<BcmsSections>` follows the same rule for a whole section: the block id, the style marker and
+the block's style go on the section's own root, and in Astro the list is delimited by two HTML
+comments, never an element. `main > section`, `:first-child` and a ScrollTrigger on `.hero` match
+what they matched before. The one exception is a section that is not one element (several roots,
+an island, in Next a component child with no function form): it gets a box of ours, a node
+between `main` and the section. With no style on the block the box is `display:contents` and
+draws nothing. Once the block has a style the box is `display:flow-root` and carries it: one
+block box, so in a flex or grid parent its children are one item instead of several, and their
+margins stop collapsing with the neighbours'. Give such a section one root element, or the
+function form ([next.md](next.md)), when a selector or the layout depends on it.
+
+## 11. Lottie, canvas, WebGL, video
+
+Pixels drawn by a script are not in the HTML, so nothing in them is a field by itself. What is
+editable is what you pass in:
+
+| Drawn by | Make editable by |
+|---|---|
+| Lottie | Bind the animation file as an image-or-file field on the container and load `path` from it. For words inside the animation, keep a text layer named after the field and set it at load (`anim.renderer.elements[i].updateDocumentData({ t: value })`), reading the value from a hidden bound element or a prop. |
+| Canvas / WebGL / three.js | Read every string and texture URL from `data-*` attributes or props on the canvas's container; bind a visually hidden element per string and an `<img hidden>` per texture, and re-read them on `bcms:content-applied`. |
+| Video | The poster and the source are fields on the `<video>`; burned-in captions are not text. |
+
+Give the canvas `role="img"` and an `aria-label` bound to a field, or an adjacent caption. A
+scene with no text a visitor reads needs no field; record it under the `decorative` exception.
+
+A canvas drawn over the page (a fixed full-screen scene behind or above the copy) does not block
+the editor: a click looks through an element that is no field and no control to the field under
+it. Keep the copy in the HTML above or below the canvas, never only inside the scene.
+
+Check: change the bound string, publish, reload: the drawn text reads the new value.
+
+## 12. In the editor's canvas
+
+The Visual Editor shows the real page with its scripts running, and owns three things there: the
+scroll (the page scrolls its own window, as it does live), the pointer (a click selects a field)
+and the place on the page (picking a field in the panel scrolls to it). Motion that reads the
+window's scroll or the clock runs there as it does live. Only what takes one of those three away
+has to stand down, and the site decides that with one question:
+
+```js
+import { inEditor } from "@bettercms-ai/sdk";   // 1.31+. Without the SDK: window.name === "bcms-editor"
+
+const smooth = inEditor() ? null : new LocomotiveScroll({ el, smooth: true });
+```
+
+`inEditor()` is true from the page's first script and through every navigation inside the
+canvas, and false on the published page. What each kind of page does there:
+
+| The page uses | In the canvas | You write |
+|---|---|---|
+| Native scroll, CSS scroll-driven animations (`animation-timeline`), Motion `useScroll` / `whileInView`, ScrollTrigger pin and scrub | runs as live | nothing |
+| Lenis, Locomotive Scroll 5 | runs; the wheel has no easing (section 6) | nothing |
+| GSAP ScrollSmoother | runs; the window still scrolls, the content eases behind it | nothing |
+| Locomotive Scroll 4, any script that locks the window and moves the content by a transform | the page works under its own wheel, but the editor cannot scroll it and a field picked in the panel is not brought into view | `smooth: !inEditor()`, so the window scrolls |
+| A wheel-driven slide deck (GSAP `Observer`, fullPage) | the same | do not create the observer when `inEditor()`; let the sections stack and scroll |
+| A scene with its own scroll layer (react-three-fiber `ScrollControls`, a fixed `overflow: auto` layer) | runs; picking a field scrolls that layer | nothing |
+| An intro or preloader that holds the page (`overflow: hidden` until it ends, a full-screen cover) | plays on every reload of the canvas, and covers the page while it does | skip it when `inEditor()` |
+
+Never use `inEditor()` to change what a field renders, to hide a section or to stop a timeline:
+the canvas must show what a visitor gets. It is for scroll takeover, intros and nothing else.
+
+Check: open the page in the Visual Editor, scroll with the wheel, drag the page's scrollbar to the
+footer, then pick a field of the first section in the panel: the canvas returns to it.