sliderpro-agentic-skills-etch 0.2.0 → 0.2.2

package/bin/cli.js

@@ -140,6 +140,24 @@ function copyBundle(target) {
   }
 }
 
+// When each skills file is meant to be read. The split exists so that only the
+// entry file is read up front, so saying so here is part of the install.
+const SKILL_ROLES = {
+  "slider-pro-skills.md": "read this first, every session",
+  "slider-pro-skills-build.md": "read only when building from scratch",
+  "slider-pro-skills-reference.md": "lookup only, never read whole",
+};
+
+function installedSkills(target) {
+  try {
+    return readdirSync(join(target, OUT_SKILLS_DIR))
+      .filter((f) => f.endsWith(".md"))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
 function countComponents(target) {
   try {
     return readdirSync(join(target, OUT_COMPONENTS_DIR)).filter((f) => f.endsWith(".md")).length;
@@ -183,10 +201,13 @@ async function main() {
 
   console.log(`Installed Slider Pro AI Connector skills to ${target}`);
   console.log(`  source: ${source}`);
-  console.log(`  ${OUT_SKILLS_DIR}/slider-pro-skills.md`);
-  console.log(`  ${OUT_SKILLS_DIR}/slider-pro-skills-reference.md`);
+  for (const name of installedSkills(target)) {
+    const role = SKILL_ROLES[name];
+    console.log(`  ${OUT_SKILLS_DIR}/${name}${role ? ` (${role})` : ""}`);
+  }
   console.log(`  ${OUT_COMPONENTS_DIR}/ (${countComponents(target)} component prop docs)`);
   console.log(`\nPoint your AI coding agent at ${OUT_SKILLS_DIR}/slider-pro-skills.md to load it.`);
+  console.log("It reads the other two only when a task needs them.");
   console.log('Then tell the agent: "npx @digital-gravy/etch-connector serve"');
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sliderpro-agentic-skills-etch",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Installs the Slider Pro for Etch AI Connector skills files and component docs into any project",
   "type": "module",
   "bin": {

package/skills-package/components/dwc-slider-pagination.md

@@ -58,3 +58,41 @@ Set **Custom Pagination Mode** to `Template` and design the *first* item as your
 
 - **Numbers** count up starting from whatever number you type, so `1` produces `1, 2, 3, ...` while `2003` produces `2003, 2004, 2005, ...`. Leading zeros are preserved as the number grows (`007` → `007, 008, ..., 010, 011, ...`).
 - **Letters and roman numerals** (`a`, `A`, `i`, `I`) always start at the beginning of their sequence (a/b/c…, i/ii/iii…). Only numbers support a custom starting point.
+
+## Styling the active item
+
+Slider Pro adds the class `is-active` to whichever pagination item matches the slide on screen. Use
+it to style the current one:
+
+```css
+.my-dot           { background: #e5e7eb; }
+.my-dot.is-active { background: #45bf55; }
+```
+
+The class moves on its own as the slider changes, so you do not need any JavaScript. It works the
+same in `Default` and `Template` mode.
+
+***
+
+## If your own layout does not apply
+
+The pagination lays itself out as a flex row or column, using the **Direction** and **Gap**
+settings above, and it is only as tall as its items.
+
+If you write your own layout on it, for example a grid, and nothing seems to happen, this is why:
+your rule and the plugin's rule are equally specific, so the plugin's wins. Put the plugin's class
+in front of yours to make your rule stronger:
+
+```css
+/* has no effect on its own */
+.my-pagination { display: grid; }
+
+/* wins */
+.dwc-slider-pagination-wrapper.my-pagination {
+  display: grid;
+  block-size: 100%;
+  gap: 0;
+}
+```
+
+Remember to reset `gap` if you set your own spacing, because the flex gap still applies.

package/skills-package/manifest.json

@@ -1,6 +1,10 @@
 {
-  "generated": "2026-08-22",
+  "generated": "2026-08-29",
   "skills": [
+    {
+      "repo": "ai-connector/slider-skills/slider-pro-skills-build.md",
+      "out": "slider-skills/slider-pro-skills-build.md"
+    },
     {
       "repo": "ai-connector/slider-skills/slider-pro-skills-reference.md",
       "out": "slider-skills/slider-pro-skills-reference.md"

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

@@ -0,0 +1,438 @@
+---
+icon: hammer
+---
+
+# AI Skills Reference: Building
+
+Read this when you are building a slider, a card deck or a template **from scratch**. For changing
+a prop, adjusting CSS or fixing an existing build, `slider-pro-skills.md` (same folder) is enough.
+
+Everything in `slider-pro-skills.md` still applies here: the native-first gate, the one-extra-brace
+rule, the class mechanisms, the CSS conventions and the gotchas. This file adds only what building
+from nothing needs. Read it after that file, never instead of it.
+
+***
+
+## Block JSON
+
+### 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.
+
+***
+
+## 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.
+
+### Animating slide content: no script
+
+Splide puts `is-active` on the current `.splide__slide`, which is all you need to animate anything
+inside it. Give the element its resting state, then reveal it from the active slide:
+
+```css
+/* in .slider-<name>__figure's own entry */
+opacity: 0;
+transform: translateY(30px);
+transition: opacity 820ms cubic-bezier(0.22, 0.68, 0.24, 1),
+            transform 820ms cubic-bezier(0.22, 0.68, 0.24, 1);
+
+.splide__slide.is-active & { opacity: 1; transform: translateY(0); }
+```
+
+Stagger a caption by putting the same pair on each line with a growing `transition-delay`
+(thumbnail 140ms, status 200ms, title 260ms, body 320ms) so the block assembles rather than
+appearing at once.
+
+Two things that bite:
+
+* **Keep layout transforms in the animated transform.** An element centred with
+  `translateX(-50%)` must animate as `translateX(-50%) translateY(30px)`, or it jumps sideways on
+  every transition. Where a breakpoint drops the centring, restate the transform there too.
+* **A slow drift on the backdrop** (`scale(1.06)` to `scale(1)` over several seconds) makes a
+  change read as movement rather than a cut. Put it on the image, not the slide, so it does not
+  fight the transition.
+
+This works with the Fade transition, which crossfades the slides underneath while the contents
+move independently.
+
+
+### Numbered steps beside a slider: no script
+
+A vertical list of steps next to an image, where the number highlights as the image changes, uses
+**two mechanisms on one slider**, split by whether the content repeats:
+
+* **What repeats goes in the pagination.** The numbered markers are identical except for the digit,
+  which is exactly what `customPaginationMode: 'Template'` does: put one item in the
+  `PaginationButtons` slot with a literal `1` in it and the engine clones it per slide, substituting
+  the number. Add a slide later and the marker appears by itself. The active marker gets
+  `is-active`, and each is a real button, so clicking navigates.
+* **What differs goes in a synced set.** Titles and descriptions are per step, and a clone cannot
+  carry them, so those are your own elements driven by
+  `sliderSetup.syncCustomElement` with `syncCustomElementNav` on.
+
+```js
+setGroup(sliderId, 'sliderSetup', { transitionType: 'Fade',
+                                    syncCustomElement: '.step',
+                                    syncCustomElementNav: '{true}' });
+etch.blocks.setAttribute(pagId, 'customPaginationMode', 'Template');
+```
+
+Do not force one mechanism to do both. Template mode cannot give each clone its own text, and
+faking it with a script to fill the clones is the kind of work the native features already cover.
+
+**Give the template two levels.** The cloned root has to stretch to its row so it can carry the
+connecting line, while the circle stays a fixed square at the top:
+
+```
+.mark          <- the cloned root; receives is-active, fills the row, draws the line
+  .mark-dot    <- the circle and the number
+```
+
+State travels from the root to the dot through custom properties, so no descendant selector has to
+fight the plugin for the same box:
+
+```css
+.mark            { --dot-bg: #e5e7eb; --dot-fg: #4b5563; }
+.mark.is-active  { --dot-bg: #45bf55; --dot-fg: #fff; }
+.mark-dot        { background: var(--dot-bg); color: var(--dot-fg); }
+```
+
+**Let the row count come from the slides, not the stylesheet.** Put both columns in one parent row
+so they are the same height, then give each `grid-auto-rows`. Marker *n* then lines up with card
+*n* whatever the copy length, and adding a slide needs no CSS change:
+
+```css
+.rail  { display: grid; grid-template-columns: auto 1fr; gap: 0 to-rem(24px); }
+.marks,
+.steps { display: grid; grid-auto-rows: minmax(0, 1fr); }
+```
+
+**Hang the connecting line off each marker, not the container.** A single line drawn on the
+container has to be told where to stop, which means hardcoding the count. Per marker it is
+self-terminating:
+
+```css
+.mark:not(:last-child)::after {
+  content: ""; position: absolute;
+  inset-inline-start: 50%; transform: translateX(-50%);
+  inset-block-start: calc(var(--dot-top) + var(--dot-size));
+  inset-block-end: 0;
+  inline-size: to-rem(2px); background: #e5e7eb;
+}
+```
+
+The last marker gets no line for free, at any slide count.
+
+Three traps, all silent:
+
+* **Use `minmax(0, 1fr)`, not `1fr`.** `1fr` means `minmax(auto, 1fr)`, so a longer description
+  expands its own row and the two columns drift apart by a few pixels per row.
+* **Match `gap` on both columns.** The pagination carries a flex `gap` of its own, which shortens
+  every row on that side only. Set it explicitly, including `0`.
+* **The pagination will not accept your layout without a co-class.** It sets `display: flex` and
+  `block-size: fit-content` on `.dwc-slider-pagination-wrapper`, which ties with a single class of
+  yours and wins on order. Write the override **inside the entry its class prop already points at**,
+  so it stays findable from the element:
+
+```css
+/* the .marks entry itself */
+position: relative;
+
+&.dwc-slider-pagination-wrapper {
+  display: grid; grid-auto-rows: minmax(0, 1fr); block-size: 100%; gap: 0;
+}
+```
+
+
+### 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.
+
+***
+
+## Block builders
+
+These extend the four helpers in `slider-pro-skills.md`. Include both sets.
+
+```js
+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 }); }
+```
+
+### 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.

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

@@ -189,6 +189,7 @@ matches the components installed on the site. Do not hand-edit this section.
 | Background Blur | `props.style.backgroundBlur` | `style` | `8px` | Shown when `props.progressType === "counter" \|\| (props.progressType === "circular" && props.circularCounter)` |
 | Progress Fill Color | `props.style.progressFillColor` | `style` | `#ff4d6a` | Shown when `props.progressType === "bar" \|\| props.progressType === "circular"` |
 | Progress Fill Color 2 | `props.style.progressFillColor2` | `style` | `#ff8fa3` | Shown when `props.progressType === "bar"` |
+| Progress Height | `props.style.progressHeight` | `style` | `3px` | Shown when `props.progressType === "bar"` |
 | Progress Track Color | `props.style.progressTrackColor` | `style` | `rgba(255, 255, 255, 0.1)` | Shown when `props.progressType === "bar" \|\| props.progressType === "circular"` |
 | Background Color | `props.style.backgroundColor` | `style` | `rgba(0, 0, 0, 0.4)` | Shown when `props.progressType === "counter"` |
 | Border Radius | `props.style.borderRadius` | `style` | `20px` | Shown when `props.progressType === "counter"` |
@@ -280,9 +281,13 @@ Arrows, dots, pagination, progress, play/pause and the lightbox are styled with
 properties, not props. The template class is **`.slider-navigation-vars`**, holding 94 variables.
 
 **Per-slider styling.** Each Slider's **Slider Class** prop (`props.sliderClass`) names the class
-its variables are read from, so two sliders on one page style independently. The plugin renames
-the auto-generated class on save, so never style directly on `.slider-navigation-vars`: add your
-own class (e.g. `.my-slider`) and style that. Classes you add yourself are never renamed.
+its variables are read from, so two sliders on one page style independently. The plugin gives each
+slider its own minted `.dwc-slider-vars-*` copy of that class, and mints a fresh one whenever a
+slider is duplicated. So never style directly on `.slider-navigation-vars`, and never write that
+shared class into the prop: doing so stops the minting and makes every duplicate share one set of
+variables. Add your own class (e.g. `.my-slider`) alongside the minted one and style that. Classes
+you add yourself are never touched. See "`sliderClass` carries a minted per-instance class" in
+[slider-pro-skills.md](slider-pro-skills.md).
 
 ### Arrows
 

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
@@ -275,6 +234,35 @@ Inside an element's **own** entry, nesting is preferred for media queries, pseud
 (`.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
@@ -314,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
+curl -s "https://the-site.com/the-page/" -o page.html
+grep -o 'data-focus="[^"]*"' page.html      # did the prop reach the engine?
+```
+
+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
-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
+chrome.exe --headless=new --remote-debugging-port=9555 \
+  --user-data-dir="<temp dir>/cdp-profile" --no-first-run about:blank &
 ```
 
-Then actually look at the screenshot. A slider that mounted is not the same as a slider that looks
-right.
+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
 
@@ -366,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
@@ -378,231 +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.
-
-### Animating slide content: no script
-
-Splide puts `is-active` on the current `.splide__slide`, which is all you need to animate anything
-inside it. Give the element its resting state, then reveal it from the active slide:
-
-```css
-/* in .slider-<name>__figure's own entry */
-opacity: 0;
-transform: translateY(30px);
-transition: opacity 820ms cubic-bezier(0.22, 0.68, 0.24, 1),
-            transform 820ms cubic-bezier(0.22, 0.68, 0.24, 1);
-
-.splide__slide.is-active & { opacity: 1; transform: translateY(0); }
-```
-
-Stagger a caption by putting the same pair on each line with a growing `transition-delay`
-(thumbnail 140ms, status 200ms, title 260ms, body 320ms) so the block assembles rather than
-appearing at once.
-
-Two things that bite:
-
-* **Keep layout transforms in the animated transform.** An element centred with
-  `translateX(-50%)` must animate as `translateX(-50%) translateY(30px)`, or it jumps sideways on
-  every transition. Where a breakpoint drops the centring, restate the transform there too.
-* **A slow drift on the backdrop** (`scale(1.06)` to `scale(1)` over several seconds) makes a
-  change read as movement rather than a cut. Put it on the image, not the slide, so it does not
-  fight the transition.
-
-This works with the Fade transition, which crossfades the slides underneath while the contents
-move independently.
-
-
-### 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.
@@ -624,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 || []) {
@@ -653,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
@@ -710,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.
@@ -733,27 +504,124 @@ 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 prop that gates a component's internals must be set explicitly, even to its default.** This is
-the one exception to "never set a prop to its default", and it is invisible when you hit it. A
-component's declared default populates the Etch settings panel; it is **not** written onto an
-instance you create programmatically. 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**. Both branches vanish at once.
+**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.
 
-The worked case: 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}'`, which is
-already the default, makes the arrow render. If a component renders structurally but its inner
-content is missing, this is the first thing to check.
+**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.
 
-**Give the slider a builder height when slide content is absolutely positioned.** A slide whose
-children are all `position: absolute` has no intrinsic height, so before the slider initialises it
-collapses to nothing and the layout is unusable in the builder. Guard it:
+**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
-&.etch-builder-block { min-block-size: 640px; }
+.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:
@@ -768,6 +636,19 @@ 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