sliderpro-agentic-skills-etch 0.1.2 → 0.2.1

package/skills-package/slider-skills/slider-pro-skills.md

@@ -4,9 +4,13 @@ icon: robot
 
 # AI Skills Reference
 
-Everything an agent needs to build and configure **Slider Pro for Etch** through the Etch AI
-Connector. Read this file in full at session start. Its companion,
-`slider-pro-skills-reference.md`, is lookup-only: Grep into it, never read it whole.
+Everything an agent needs to configure **Slider Pro for Etch** through the Etch AI Connector. Read
+this file in full at session start. It has two companions in the same folder, and neither is read
+up front:
+
+* **`slider-pro-skills-build.md`** is the building guide: block JSON, slots, the design recipes
+  and the block builders. Read it when you are creating something from scratch, and not otherwise.
+* **`slider-pro-skills-reference.md`** is lookup-only. Grep into it, never read it whole.
 
 ### When to consult the reference file
 
@@ -106,8 +110,15 @@ npx @digital-gravy/etch-connector eval "return etch.blocks.getTree().length" -t
 npx @digital-gravy/etch-connector eval -f ./script.js -t "<tab>" --timeout 30000
 ```
 
-Anything longer than one expression goes in a file with `-f`. Inline multi-line quoting breaks in
-every shell eventually.
+Anything longer than one expression goes in a file with `-f`, and use an **absolute path**: a bare
+`./script.js` resolves against whatever directory happens to be current.
+
+**Write that file with your file-writing tool, never a shell heredoc.** Script bodies are full of
+quotes, backticks, `$` and regex, all of which the shell tries to interpret first. `cat > f <<'EOF'`
+fails to parse and writes nothing, so you lose the call and learn nothing. Write the file directly
+and the shell never sees the contents.
+
+Keep every temp script in a working subdirectory you made for the task, and delete it when done.
 
 ### Safe mode
 
@@ -143,64 +154,13 @@ etch.components.list()                       // [{ id, name }, ...]
 etch.components.getJson(id)                  // .properties and .blocks
 etch.styles.list()                           // [{ id, selector, type, collection, css }]
 etch.styles.create(selector, css)            // returns a STYLE ID; pass it to a class prop
+etch.styles.update(id, { selector?, css? })  // NOTE the object. See the warning below
+etch.styles.delete(id)
 etch.blocks.addClass(blockId, name)          // plain elements only; throws on a component
 etch.blocks.getJson(id).script               // { code }, the JavaScript code block
 await etch.saveAsync()
 ```
 
-### Component instances are the unit of work
-
-A Slider Pro build is a tree of `etch/component` blocks, each naming a component and carrying a
-flat `attributes` map of prop values. **Two different shapes describe the same tree, and mixing
-them up is the first thing that goes wrong in a session.**
-
-**The live shape**, which `etch.blocks.getTree()` returns and `etch.blocks.create()` accepts:
-
-```json
-{
-  "type": "etch/component",
-  "version": 1,
-  "context": {},
-  "children": [],
-  "componentId": 6455,
-  "attributes": { "wrapperHeight": "350px", "spaceBetweenSliders": "50px" }
-}
-```
-
-`version`, `context` and `children` are required. Block ids are strings (`"ot2wnef"`), not numbers.
-
-**The export shape**, which you only ever see inside a premade template `.json` file, uses
-`blockName`, nests under `attrs`, and calls the component id `ref`:
-
-```json
-{ "blockName": "etch/component", "attrs": { "ref": 6455, "attributes": {} }, "innerBlocks": [] }
-```
-
-Never pass the export shape to `create()`. It is rejected with
-`Invalid block JSON: expected string, received undefined` at `path: ["type"]`. To put a template on
-the page, hand its whole `gutenbergBlock` to `etch.blocks.pasteAsync()` instead.
-
-### Children go in a slot, never directly on the component
-
-A component's children must be wrapped in an `etch/slot-content` node naming the slot they fill.
-Putting a Slider straight inside a Wrapper's `children` renders nothing.
-
-```json
-{ "type": "etch/slot-content", "version": 1, "context": {}, "children": [], "slotName": "Slides" }
-```
-
-| Component | Slots |
-| --- | --- |
-| DWC Slider Wrapper | `Sliders_and_Controls` |
-| DWC Slider | `Top__Controls`, `Slides`, `Bottom__Controls` |
-| DWC Slide | `Content` |
-| DWC Slider Pagination | `PaginationButtons` |
-| DWC Slider Nav Button | `Nav_Btn_Content` |
-| DWC Slider Progress, DWC Slider Play-Pause | none |
-
-Controls are siblings of the Slider inside `Sliders_and_Controls`, or children of the Slider's own
-`Top__Controls` / `Bottom__Controls`. Both work, because controls find their own slider.
-
 ### Classes: two different mechanisms
 
 Adding a class to a plain element and adding one to a component are **not the same operation**, and
@@ -230,8 +190,7 @@ The class-typed props, one per component:
 **On a plain element**, use `addClass` with the bare class name, no dot and no id:
 
 ```js
-const id = etch.blocks.create(el('article', {}, []));
-etch.blocks.addClass(id, 'fall-card');
+etch.blocks.addClass(plainElementId, 'fall-card');   // no dot, no style id
 ```
 
 Passing a style id here does not resolve. It is treated as a literal name and sanitised, so
@@ -242,6 +201,75 @@ Either way the CSS rule itself is `etch.styles.create('.fall-card', '...')`, whi
 selector has to match.
 
 
+### CSS conventions
+
+Match the shipped templates. An install that already has premade sliders on it has these
+conventions everywhere, and a build that ignores them reads as foreign.
+
+**Naming.** The block is the slider, named after the design:
+
+| Thing | Pattern | Example |
+| --- | --- | --- |
+| Wrapper class, slider designs | `.slider-<name>-wrapper` | `.slider-flow-wrapper` |
+| Wrapper class, card stacks | `.slider-wrapper-<name>` | `.slider-wrapper-fall` |
+| Slider class | `.slider-<name>` | `.slider-chronos` |
+| Elements | `.slider-<name>__<element>` | `.slider-team__sync` |
+| Modifiers | `.slider-<name>__<element>--<variant>` | `.slider-afterform__word--form` |
+
+The wrapper class carries the word `wrapper` and the slider class carries the word `slider`. Do not
+invent a short prefix of your own.
+
+**One style entry per element class.** Never one nested parent entry holding the whole component.
+`etch.styles.create()` per class, each with its own CSS:
+
+```js
+const S = {};
+S.wrapper = etch.styles.create('.slider-afterform-wrapper', '/* ... */');
+S.caption = etch.styles.create('.slider-afterform__caption', '/* ... */');
+S.title   = etch.styles.create('.slider-afterform__caption-title', '/* ... */');
+```
+
+Inside an element's **own** entry, nesting is preferred for media queries, pseudo-elements
+(`&::after`), states (`&:hover`, `&.is-active`), ancestor states
+(`.splide__slide.is-active &`) and child tag selectors (`& img`, `& svg`). Do **not** nest another
+class's rules (`&__title`) inside a different class's entry: that class gets its own entry.
+
+**Wrap px values in `to-rem()`.** Etch preprocesses style-entry CSS and converts them, so write
+`to-rem(80px)`, never a raw `80px` and never a hand-converted `5rem`. It works inside media queries
+too. Leave unitless values alone (`z-index`, `opacity`, `line-height`, aspect ratios).
+
+```css
+--offset: to-rem(80px);
+@media (width <= to-rem(767px)) { --offset: to-rem(40px); }
+```
+
+**Every rule for an element belongs in the entry its class prop already points at.** It is tempting
+to answer a specificity problem with a second, more specific entry, for example
+`.dwc-slider-pagination-wrapper.my-class`. Do not. That entry is attached to no block, so selecting
+the element in Etch does not reveal it and the author cannot find the rule to edit. Nest the
+stronger selector inside the element's own entry instead, which gives the same specificity:
+
+```css
+/* inside the .my-class entry */
+&.dwc-slider-pagination-wrapper { display: grid; }
+```
+
+A style entry that no block references also survives deleting the element it was written for.
+
+
+**`etch.styles.update` takes an object, and a string fails silently.** The signature is
+`update(id, { selector, css })` and it reads `arg.css`. Hand it a bare CSS string and `arg.css` is
+`undefined`, so it falls back to the entry's existing CSS, writes that back unchanged, and **throws
+nothing**. The call looks like it worked. Read the entry back from `etch.styles.list()` and compare
+the CSS before believing an update landed.
+
+**Renaming is not one operation.** A style entry's selector and a block's `class` attribute are
+independent. Renaming the selector rewrites the rendered class only where the class came from a
+**component class prop**, because that prop stores the style id and resolves it at render. On a
+plain element the `class` attribute is literal, so a selector rename leaves it pointing at a
+selector that no longer exists. Rename both, or the element silently loses its CSS.
+
+
 ### Group props and the one-extra-brace rule
 
 Most Slider props live in groups (`layout`, `motion`, `slides`, `autoplay`, ...). A group is stored
@@ -274,16 +302,50 @@ the prop reference.
 
 ### Visual verification
 
-You cannot see the page from inside safe mode. After any visual change:
+You cannot see the page from inside safe mode, and a read-back is not a substitute. A
+`getAttribute` read proves a value **persisted**; only looking at output proves the page is
+**right**. Say which of the two you reached.
+
+**You can reach rendered verification on your own.** The Etch builder sits behind the user's
+WordPress session, but the published page does not. Save first, or you will verify the old page.
+
+**1. Fetch the published page.** Cheapest, and often enough. Proves classes, attributes and text
+reached the markup.
 
 ```bash
-npx @digital-gravy/etch-connector shot -t "<tab>" -s ".my-slider" -o ./out.png
-npx @digital-gravy/etch-connector html ".my-slider" -t "<tab>"
-npx @digital-gravy/etch-connector computed ".my-slider .splide__slide" -t "<tab>" --props transform,opacity
+curl -s "https://the-site.com/the-page/" -o page.html
+grep -o 'data-focus="[^"]*"' page.html      # did the prop reach the engine?
 ```
 
-Then actually look at the screenshot. A slider that mounted is not the same as a slider that looks
-right.
+Count matches with `grep -o ... | wc -l`, not `grep -c`, which counts lines: rendered pages are
+minified onto very few lines and `grep -c` will report 1 for everything. Remember the page also
+inlines your style entries, so a class name appears once more than it does in the markup.
+
+**2. Screenshot it with your own headless browser.** Launch a fresh instance on a spare port with
+its own throwaway profile, then kill it and delete the profile when done. The page is public, so it
+needs no session.
+
+```bash
+chrome.exe --headless=new --remote-debugging-port=9555 \
+  --user-data-dir="<temp dir>/cdp-profile" --no-first-run about:blank &
+```
+
+Then drive it over CDP: `Page.navigate`, wait for `Page.loadEventFired`, wait again for Splide to
+mount and images to decode, then `Page.captureScreenshot`. `Runtime.evaluate` gives you
+`getComputedStyle` and `getBoundingClientRect`, which is how you turn "the dots look small" into a
+measurement. **Then actually look at the screenshot.** A slider that mounted is not a slider that
+looks right.
+
+Write attribute probes as `[data-x="false"]`, not `[data-x]`: the bare attribute selector matches
+whatever the value is, so a switched-off control still counts and you will report it as still there.
+
+> **Do not use the connector's `shot`, `html` or `computed`, and never ask the user to relaunch
+> their browser with `--remote-debugging-port=9222`.** Those attach to the user's own Chrome, so
+> they cost the logged-in session being tested and fail outright when that port is not already
+> open. The route above needs neither.
+
+**What this cannot show you**, and has to be handed to the user: unpublished pages, logged-in-only
+content, and anything you have not saved yet.
 
 ### Saving
 
@@ -326,7 +388,7 @@ Four rules follow from it:
 
 ## Decision tree
 
-**Build from scratch:** components and props first, then CSS.
+**Build from scratch:** read `slider-pro-skills-build.md` now. Components and props first, then CSS.
 
 Reach for a premade template only when the user names one ("use Deck Featured"). Then paste its
 JSON and customise, and read `https://design-with-cracka.gitbook.io/etchsliderpro/card-stack-templates` or `https://design-with-cracka.gitbook.io/etchsliderpro/premade-templates` for
@@ -338,199 +400,6 @@ configure it the way its documentation describes instead of inventing new CSS ov
 
 ***
 
-## Design recipes
-
-Each of these is a shipped template reduced to the settings that produce it.
-
-### Cover-flow carousel (Slider Flow): no script, no CSS
-
-The whole effect is the `slides.*` group, which applies transforms to inactive slides and separate
-`-Active` values to the current one.
-
-```js
-setGroup(sliderId, 'layout',  { slidesPerPage: '3 lg:1', gapBetweenSlides: '20px',
-                                sliderEdgeOffset: 'lg:20% md:18%' });
-setGroup(sliderId, 'motion',  { focus: 'center', loop: '{true}', speed: '800',
-                                updateOnMove: '{true}' });
-setGroup(sliderId, 'slides',  { perspective: '950px', opacity: '0.3', scale: '0.9',
-                                borderRadius: '1rem',
-                                transition: 'transform 0.5s ease, opacity 0.5s ease' });
-setGroup(sliderId, 'dimensions', { sliderHeight: '350px md:300px sm:180px' });
-```
-
-`motion.focus: 'center'` is what puts the active slide in the middle. The neighbours are dimmed and
-shrunk purely by `slides.opacity` and `slides.scale`, which apply to inactive slides only.
-
-For an angled flip, add `slides.rotateY` and turn on `slides.flipNextRotateY` so the slide on the
-other side mirrors the angle instead of repeating it. Same for `translateX` with
-`flipNextTranslateX`.
-
-### Logo marquee (Slider Marquee): no script
-
-Two Sliders in one Wrapper, running in opposite directions.
-
-```js
-// both rows
-setGroup(sliderId, 'dimensions', { slideAutoWidth: '{true}' });   // slides size to content
-setGroup(sliderId, 'motion',     { loop: '{true}' });
-setGroup(sliderId, 'autoscroll', { infiniteScroll: '{true}', scrollSpeed: '1',
-                                   pauseOnHover: '{false}', pauseOnFocus: '{false}' });
-setGroup(sliderId, 'layout',     { gapBetweenSlides: '2.4rem' });
-
-// second row only
-setGroup(secondId, 'sliderSetup', { slldeDirection: 'rtl' });     // note the spelling
-```
-
-Edge Fade goes on the **Wrapper** (`props.edgeFade`), not the sliders, so both rows fade as one
-unit. `props.pauseSlidersOnHover` on the Wrapper pauses both rows together.
-
-Infinite Scroll needs the Auto-Scroll extension enabled in admin settings, which is the default.
-
-### Synced elements (Team, Stack)
-
-Driving arbitrary elements on the page from the slider is one prop.
-
-```js
-setGroup(sliderId, 'sliderSetup', { syncCustomElement: '.timeline-node',
-                                    syncCustomElementNav: '{true}' });
-```
-
-The plugin then moves `is-active`, `is-prev` and `is-next` across those elements as the slider
-moves, and with nav on, clicking one jumps the slider to it. **You write the CSS for the three
-states.** The elements do not need to be inside the slider and do not need to match the slide
-count.
-
-The selector takes a comma-separated list, so one slider can drive several groups at once. Team
-uses `'.slider-team__sync, .slider-team__sync-heading'` to move a portrait and a heading together.
-
-Grep `## 3. Sync Custom Element` in the reference for multiple selectors and the overlap caveat.
-
-### Main and thumbnails in one wrapper (Zeon)
-
-A full-bleed hero with a thumbnail strip needs no sync prop at all, just roles:
-
-```js
-setGroup(mainId,  'sliderSetup', { sliderRole: 'main',       transitionType: 'Fade' });
-setGroup(thumbId, 'sliderSetup', { sliderRole: 'thumbnails', transitionType: 'Loop' });
-```
-
-Both inside the same Wrapper and they pair automatically. A Wrapper can hold more than one
-thumbnail slider, which is how Zeon runs a background layer and a strip off the same main.
-
-### Carousel on mobile, grid on desktop
-
-```js
-setGroup(sliderId, 'layout', { layoutMode: 'static md:slider', gridColumns: '3 sm:1' });
-```
-
-Above `md` it is a plain CSS grid; at `md` and below it is a real carousel. The slider is built and
-torn down live as the viewport crosses the breakpoint. **Controls are hidden in static mode**,
-because there is no live slider to drive.
-
-### Card decks with no slider (Deck, Fall): the one place script is allowed
-
-Structure: a Wrapper with `sliderlessSync.customElement` pointing at your cards, no Slider inside,
-cards nested three deep as `card > lift > content` so the 3-D survives.
-
-```js
-setGroup(wrapperId, 'sliderlessSync', {
-  customElement: '.deck-card', customElementNav: '{true}',
-  loop: '{true}', autoplay: '{true}', autoplayInterval: '4000'
-});
-```
-
-CSS handles the front card and its two neighbours from `is-active` / `is-prev` / `is-next`. What
-CSS cannot do is know that a given card is *three* back, so the rows behind, the z-index ladder and
-the click targets need a script. That is case 1 of the native-first gate.
-
-The contract between that script and the CSS is one attribute, **`data-pos`**, which the script
-derives from `is-active` and writes on every card. It is a **signed** offset from the active card,
-so the CSS can fan the left and right sides in opposite directions:
-
-```css
-.deck-stack-featured &:is([data-pos='2'], [data-pos='-2']) { /* ring 2, both sides */ }
-```
-
-The stack container carries **`data-tiers`**, how many rings are actually in play. It is computed,
-not fixed: a looping deck needs spare cards to hide the wrap behind, so the script reduces the
-tiers when there are too few cards.
-
-Writing an unsigned rank, or naming the attribute anything else, produces a flat pile: the rules
-above simply never match. The shipped script does this:
-
-```js
-// 1. make a custom property interpolable, so a blur can animate (case 2)
-CSS.registerProperty({ name: '--stack-focus', syntax: '<number>',
-                       inherits: true, initialValue: '0' });
-
-// 2. how many rings this deck can afford, given looping and the card count
-var mayLoop = wrap.dataset.loop === 'true' && total >= MIN_LOOP;
-stack.dataset.tiers = mayLoop ? Math.min(MAX_TIERS, Math.floor((total - 3) / 2)) : MAX_TIERS;
-
-// 3. per card: SIGNED offset from the active card. On a looping deck the offset
-//    wraps, so the far end of the list reads as the near side, not as distance 8.
-var d = n - active;
-if (mayLoop) {
-  if (d >  total / 2) d -= total;
-  if (d < -total / 2) d += total;
-}
-card.dataset.pos = d;
-
-// 4. hit-testing: stack order by distance, and clicks off beyond the clickable rings
-var rank = Math.abs(d);
-card.style.zIndex = String(total - rank);
-lift.style.pointerEvents = rank <= NAV_RINGS ? 'auto' : 'none';
-```
-
-Do not clamp `data-pos` to the tier count. Cards past the deepest ring should match no rule and
-stay stacked at the back; clamping piles them onto the last visible ring instead.
-
-Both decks also set `--i` on each line of card content so the CSS can stagger it:
-
-```js
-card.querySelectorAll('.deck-card-featured__content > *')
-    .forEach(function (line, j) { line.style.setProperty('--i', j); });
-```
-
-Step 4 is Deck only. **Fall's script is much smaller**: it sets `--i` and a signed `data-pos`, and
-nothing else. Fall never loops, so there is no wrap to fold and no z-index ladder to maintain,
-because the cards fall past each other rather than fanning around a front card.
-
-Recompute on every change: watch the stack with a `MutationObserver` filtered to `class`, since
-`is-active` moving is the only signal you get.
-
-### Where a script goes
-
-**Not in a `<script>` element.** Etch silently drops one from the render, so the page looks right
-in the builder and ships with no behaviour at all.
-
-Every block has an optional `script` field (`EtchBlockScript`), which is Etch's JavaScript code
-block. Put the code on the **component instance that owns the markup**, which for a card stack is
-the Wrapper:
-
-```js
-const wrapperId = etch.blocks.create({
-  type: 'etch/component', version: 1, context: {}, children: [ /* ... */ ],
-  componentId: C['DWC Slider Wrapper'], attributes: {},
-  script: { code: "(function () { /* ... */ })();" }
-});
-```
-
-`code` is **plain source** over the API. The base64 you see in a premade template `.json` is only
-how the export serialises it; do not encode it yourself.
-
-Etch renders it as `<script type="module" defer>`, so it runs after parsing and top-level `await`
-is available. Read it back with `etch.blocks.getJson(id).script`.
-
-Component scripts are also the reason a card deck keeps working: the bridge leaves Sync Without
-Slider wrappers unreconstructed precisely so an author's script keeps observing the original nodes.
-
-Card counts for a looping deck: three are always visible (front plus two), and a loop needs a
-hidden slot at each end, so **five is the minimum** and nine gives the full three-row fan. Fall
-never loops, so it has no minimum.
-
-***
-
 ## Script library
 
 Include these at the top of any script.
@@ -552,25 +421,6 @@ function setGroup(id, key, patch) {
   etch.blocks.setAttribute(id, key, '{' + JSON.stringify(next) + '}');
 }
 
-function node(extra, children) {
-  return Object.assign({ version: 1, context: {}, children: children || [] }, extra);
-}
-
-function component(componentId, attributes, children) {
-  return node({ type: 'etch/component', componentId: componentId,
-                attributes: attributes || {} }, children);
-}
-
-function slot(slotName, children) {
-  return node({ type: 'etch/slot-content', slotName: slotName }, children);
-}
-
-function el(tag, attributes, children) {
-  return node({ type: 'etch/element', tag: tag, attributes: attributes || {} }, children);
-}
-
-function text(t) { return node({ type: 'etch/text', text: t }); }
-
 function findByRef(nodes, componentId, out) {
   out = out || [];
   for (const n of nodes || []) {
@@ -581,35 +431,6 @@ function findByRef(nodes, componentId, out) {
 }
 ```
 
-### Build a wrapper with N slides
-
-```js
-const C = comps();
-const slides = [];
-for (let i = 0; i < 5; i++) {
-  slides.push(component(C['DWC Slide'], {}, [
-    slot('Content', [ el('div', {}, [ text('Slide ' + (i + 1)) ]) ])
-  ]));
-}
-
-const id = etch.blocks.create(
-  component(C['DWC Slider Wrapper'], {}, [
-    slot('Sliders_and_Controls', [
-      component(C['DWC Slider'], {}, [ slot('Slides', slides) ]),
-      component(C['DWC Slider Nav Button'], {}),
-      component(C['DWC Slider Pagination'], {})
-    ])
-  ])
-);
-return id;
-```
-
-An empty Slide has no content and so no height. Give slides something to size before wondering why
-the slider is a flat line.
-
-Build **one** first, screenshot it, then scale to the full count. Do not generate twenty slides
-before you have seen one render.
-
 ### Read the current state of a slider
 
 ```js
@@ -638,6 +459,28 @@ mistake, and `ltr sm:ttb` does the opposite of what it looks like.
 
 **Never set a prop to its default.** It adds noise to the markup and hides real intent.
 
+**Adding a control component does not remove the built-in one. Switch the built-in off yourself.**
+Three of them ship **on**, and each renders a second set of controls underneath your design:
+
+| Built-in | Prop | Default |
+| --- | --- | --- |
+| Arrows | `props.navigation.navigationArrows` | `true` |
+| Pagination dots | `props.navigation.paginationDots` | `true` |
+| Play/pause toggle | `props.autoplay.playPauseButton` | `true` |
+
+Dropping in a DWC Slider Pagination while `paginationDots` is still `true` gives you two sets of
+dots, and `playPauseButton` puts a circular toggle at the slider's bottom-right of a design that
+never asked for one. This is the one place the "never set a prop to its default" rule reads
+backwards: you are not setting a default, you are turning an unwanted default off.
+
+**Pagination dot size is derived from the dot font size. Change the font size, not the size.**
+`props.dot.size` is declared as `calc(var(--font-size) * 2)`, so it tracks `props.dot.fontSize`
+by design. Writing a fixed `size` severs that and the dots stop scaling with the type. Leave
+`size` alone and set `fontSize` to half the dot you want: `0.32rem` gives a 10px dot.
+
+Default mode also puts the slide **number** inside each dot. For plain dots set
+`props.dot.textColor` and `props.dot.activeTextColor` to `transparent`.
+
 **A nested inner slider must be Slide or Fade, never Loop or Infinite Scroll.** A looping slider
 makes hidden copies of its slides, and copying a slider that contains a slider breaks both. To wrap
 around, use Fade, or Slide with Rewind.
@@ -661,6 +504,157 @@ rather than debugging a slider that will never start.
 
 **Do not touch the plugin's own stylesheet.** Style through the Slider Class and CSS variables.
 
+**A component's declared default is never written onto an instance you create.** Defaults populate
+the Etch settings panel. They are not present in the attributes map of a block you create through
+the API, so `getAttribute` returns nothing for them. This is the one exception to "never set a prop
+to its default", and it fails silently in two different ways.
+
+**Symptom one, a condition that never matches.** When a condition inside the component reads a flag
+prop and the key is absent, the expression does not resolve and the condition returns false
+**whichever operator it uses**, so both branches vanish at once. A DWC Slider Nav Button created
+with `navigationType` alone renders `<button>` with no icon: the default arrow sits behind
+`useCustomArrow isFalsy` and the custom SVG behind `useCustomArrow isTruthy`, and neither appears.
+Writing `useCustomArrow: '{false}'`, already the default, makes the arrow render. If a component
+renders structurally but its inner content is missing, check this first.
+
+**Symptom two, a class prop that silently replaces the default.** Class props are arrays of
+**space-separated style ids**. Writing one id does not add to the default, it becomes the whole
+value, and the default is gone with no error. Setting `sliderClass` to your own class alone drops
+the slider's navigation variables, which carry the arrow, pagination, play/pause and progress
+styling, and nothing looks wrong until one of those controls misbehaves. Always read, append,
+write back, never overwrite.
+
+## `sliderClass` carries a minted per-instance class
+
+Every slider needs its **own copy** of the navigation variables so two sliders on one page can be
+styled independently. The plugin mints that copy for you as a class named `.dwc-slider-vars-XXXXXX`
+whose CSS is copied from `.slider-navigation-vars`. A correctly built slider holds the minted class
+plus any design class of your own, which is what every premade template does:
+
+```
+.dwc-slider-vars-vsj76d  .slider-chronos
+```
+
+**Never put `.slider-navigation-vars` into the slot yourself.** Resolving it by selector and writing
+that shared id looks right and renders right, so nothing warns you. It silently breaks duplication:
+the plugin only manages classes matching `.dwc-slider-vars-*`, so a slider carrying the shared
+default gets no fresh class when it is duplicated, and every copy then reads one set of variables.
+Recolouring one slider's arrows changes them all. This is the single easiest way to ship a slider
+that looks finished and is not.
+
+**Create first, append second.** Leave `sliderClass` alone when you create the slider. The plugin
+polls roughly every two seconds and mints a class for any instance that appeared after the builder
+loaded while the prop is still unset. Once it has, read the value back and append your design class
+to what it wrote:
+
+```js
+const ids = (etch.blocks.getAttribute(sliderId, 'sliderClass') || '').split(/\s+/).filter(Boolean);
+// ids now starts with a minted .dwc-slider-vars-* id. Append to it, never replace it.
+ids.push(myStyleId);
+etch.blocks.setAttribute(sliderId, 'sliderClass', ids.join(' '));
+```
+
+If the prop is still empty after a few seconds, mint one yourself. Copy the CSS from
+`.slider-navigation-vars` and keep the required name shape, because a class named anything else is
+not managed:
+
+```js
+const src = etch.styles.list().find(s => s.selector === '.slider-navigation-vars');
+const taken = new Set(etch.styles.list().map(s => s.selector));
+let selector;
+do {
+  selector = '.dwc-slider-vars-' + Math.random().toString(36).slice(2, 8);
+} while (taken.has(selector));
+const varsId = etch.styles.create(selector, src.css);
+```
+
+**Resolve by selector, not by the documented id.** The prop reference records `sliderClass`'s
+default as a style id, but that id differs per install, so look the style up by
+`.slider-navigation-vars` when you need its CSS to copy.
+
+**Verify the shape before you call the slider done.** Read `sliderClass` back and confirm it holds
+exactly one `.dwc-slider-vars-*` id, plus your design class if you added one. A slider holding
+`.slider-navigation-vars`, or holding no vars class at all, is a defect you introduced.
+
+**Anything whose resting state waits on `is-active` breaks in edit mode.** The slider runs in
+Preview but not while the user is editing, so in edit mode no slide carries `is-active` and none of
+your active-state rules apply. Height that comes from the active slide collapses; an element
+resting at `opacity: 0` stays invisible. Guard on the condition "nothing is active yet", which is
+true only in edit mode and switches itself off the moment the slider runs:
+
+```css
+.figure { opacity: 0; }
+.splide__slide.is-active .figure { opacity: 1; }
+.splide:not(:has(.splide__slide.is-active)) .figure { opacity: 1; }
+```
+
+**Where the check goes depends on which element receives the class.** Above, the slide becomes
+active and the figure is inside it, so the test sits on a shared ancestor. With Sync Custom Element
+your own elements receive `is-active` themselves, so test their container instead:
+`.steps:not(:has(.step.is-active)) .step`. A single canned selector does not fit every case; work
+out which element actually gets the class first.
+
+`.etch-builder-block` alone is not enough. It says "in the builder", not "not running", so a rule
+gated only on it can also suppress the effect in Preview.
+
+**The same gate is needed for anything positioned against the slide, not just for `is-active`
+states.** A slide's height arrives with Splide. Until it mounts the slide has none, so absolutely
+positioned children have nothing to sit in, and the whole design collapses into a pile in the
+builder. That covers an overlay caption, a corner button and an `inset: 0` image alike. Give the slide a height under
+the same "nothing is active yet" condition, so it applies in the builder and stops the moment the
+slider runs:
+
+```css
+/* inside the slide class's own entry */
+position: relative;
+
+.splide:not(:has(.splide__slide.is-active)) & {
+  min-block-size: to-rem(480px);
+}
+```
+
+Build the design so the builder shows something honest. An author who cannot see the slide cannot
+edit its content.
+
+**Read computed style, not source, to decide what the plugin already does.** `getComputedStyle(el)`
+answers directly and in one call. Do not conclude from page source that a rule is absent: component
+styles are inlined into the page but the engine's stylesheet is a separate file, so a rule can be
+in force while being nowhere in the HTML. Presence in the DOM is not visibility either, since a
+hidden element is still there.
+
+**Do not anchor against a neighbour that stops shrinking.** A `vw` offset tuned at one width
+silently collides at another, because `min()` and `clamp()` neighbours stop shrinking while the
+`vw` keeps going. Derive the clearance from the neighbour's real footprint instead:
+
+```css
+/* wrong: fits at 1771, overlaps the column from 1024 to 1430 */
+right: 17.6vw;
+/* right: reserve exactly what the column occupies */
+right: calc(4vw + min(15vw, 195px) + 2.5vw);
+```
+
+Check the mid range explicitly. Between the widest layout and the first breakpoint is where
+side-by-side compositions fail, and it is the range nobody screenshots.
+
+**Missing Preview and Grid buttons on a slider you just built mean the install is older than
+1.2.1, not that the build is broken.** The builder watches the canvas and attaches those controls
+to sliders as they appear, but before 1.2.1 that watcher only started if a slider was **already**
+on the page when the builder loaded. Build onto an empty page there and nothing is watching, so the
+controls never appear until the tab is reloaded, however the blocks were added, by script or by
+hand.
+
+You cannot fix it from a script on those versions: the refresh is an iframe reload, and safe mode
+has no `window` or `document` to reach it with. Do not paper over it by sending the user to reload
+every time. Confirm the blocks and the published page are right, tell them it is fixed in 1.2.1,
+and mention that a reload brings the controls back meanwhile. Preview is how they watch the slider
+actually run, so it is worth naming rather than leaving them to find it.
+
+**A save can lag the front end.** `etch.saveAsync()` resolves before the change is necessarily
+readable on the published page, so a fetch straight afterwards can return the previous value and
+look like a failed write. Re-read through `etch.blocks.getAttribute` to confirm intent, and treat a
+stale page as latency rather than loss. Reloading the builder tab flushes anything pending.
+
+
 ### Do not
 
 * Hardcode component IDs.