sliderpro-agentic-skills-etch 0.1.1 → 0.2.0

package/bin/cli.js

@@ -1,14 +1,33 @@
 #!/usr/bin/env node
 
-import { cpSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+// Installs the Slider Pro AI Connector skills into a project.
+//
+// The skills live in the docs repo and change more often than this package is
+// published, so the current files are fetched at install time and the bundled
+// copy is only a fallback for when the network is unavailable. Fetching is
+// all-or-nothing: a partial fetch would mix a new skills file with stale
+// component docs, which is worse than either source on its own.
+
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import {
+  applyRewrites,
+  DEFAULT_REF,
+  looksLikeMarkdown,
+  OUT_COMPONENTS_DIR,
+  OUT_SKILLS_DIR,
+  rawUrl,
+  REPO,
+  REPO_MANIFEST,
+} from "../lib/skills-source.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = join(__dirname, "..");
-const sourceRoot = join(packageRoot, "skills-package");
+const bundleRoot = join(packageRoot, "skills-package");
 
-const DIRS = ["slider-skills", "components"];
+const DIRS = [OUT_SKILLS_DIR, OUT_COMPONENTS_DIR];
+const TIMEOUT_MS = 10000;
 
 function printHelp() {
   console.log(`
@@ -18,27 +37,37 @@ Usage:
   npx sliderpro-agentic-skills-etch [directory] [options]
 
 Options:
-  --force, -f    Overwrite existing slider-skills/ or components/
-  --help, -h     Show this help message
+  --force, -f     Overwrite existing slider-skills/ or components/
+  --offline       Skip the network and install the copy bundled with this package
+  --ref <ref>     Install from a branch or tag (default: ${DEFAULT_REF})
+  --help, -h      Show this help message
+
+By default the current skills are fetched from ${REPO} so they are never
+older than this package. Without a network the bundled copy is used instead.
 
 Examples:
   npx sliderpro-agentic-skills-etch
   npx sliderpro-agentic-skills-etch ./my-site-project
-  npx sliderpro-agentic-skills-etch --force
+  npx sliderpro-agentic-skills-etch --offline --force
 `);
 }
 
 function parseArgs(argv) {
-  const options = { force: false, help: false, target: process.cwd() };
-
-  for (const arg of argv) {
-    if (arg === "--help" || arg === "-h") {
-      options.help = true;
-    } else if (arg === "--force" || arg === "-f") {
-      options.force = true;
-    } else if (!arg.startsWith("-")) {
-      options.target = resolve(arg);
-    } else {
+  const options = { force: false, help: false, offline: false, ref: DEFAULT_REF, target: process.cwd() };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") options.help = true;
+    else if (arg === "--force" || arg === "-f") options.force = true;
+    else if (arg === "--offline") options.offline = true;
+    else if (arg === "--ref") {
+      options.ref = argv[++i];
+      if (!options.ref) {
+        console.error("--ref needs a branch or tag name");
+        process.exit(1);
+      }
+    } else if (!arg.startsWith("-")) options.target = resolve(arg);
+    else {
       console.error(`Unknown option: ${arg}`);
       printHelp();
       process.exit(1);
@@ -48,60 +77,120 @@ function parseArgs(argv) {
   return options;
 }
 
-function listConflicts(target) {
-  return DIRS.filter((dir) => existsSync(join(target, dir))).map((dir) => `${dir}/`);
+async function get(url) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(url, { signal: controller.signal, headers: { "user-agent": "sliderpro-agentic-skills-etch" } });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    return await res.text();
+  } finally {
+    clearTimeout(timer);
+  }
 }
 
-function copyPackageFiles(target, force) {
-  mkdirSync(target, { recursive: true });
+function bundledManifest() {
+  return JSON.parse(readFileSync(join(bundleRoot, "manifest.json"), "utf8"));
+}
 
-  for (const dir of DIRS) {
-    const source = join(sourceRoot, dir);
-    const dest = join(target, dir);
+/** Returns { files: [{out, content}] } or null if anything at all went wrong. */
+async function fetchLive(ref) {
+  let manifest;
+  try {
+    manifest = JSON.parse(await get(rawUrl(ref, REPO_MANIFEST)));
+  } catch {
+    // The manifest may predate this feature on an older ref; the bundled list
+    // is still a reasonable guess at what to fetch.
+    try {
+      manifest = bundledManifest();
+    } catch {
+      return null;
+    }
+  }
+
+  const entries = [...(manifest.skills || []), ...(manifest.components || [])];
+  if (entries.length === 0) return null;
 
-    if (existsSync(dest) && !force) {
-      continue;
+  const files = [];
+  for (const entry of entries) {
+    let text;
+    try {
+      text = await get(rawUrl(ref, entry.repo));
+    } catch {
+      return null;
     }
+    if (!looksLikeMarkdown(text)) return null;
+    files.push({ out: entry.out, content: applyRewrites(text) });
+  }
+  return files;
+}
+
+function writeFiles(target, files) {
+  for (const file of files) {
+    const dest = join(target, file.out);
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, file.content);
+  }
+}
 
-    cpSync(source, dest, { recursive: true });
+function copyBundle(target) {
+  for (const dir of DIRS) {
+    const source = join(bundleRoot, dir);
+    if (existsSync(source)) cpSync(source, join(target, dir), { recursive: true });
   }
 }
 
-function countComponents() {
+function countComponents(target) {
   try {
-    return readdirSync(join(sourceRoot, "components")).filter((f) => f.endsWith(".md")).length;
+    return readdirSync(join(target, OUT_COMPONENTS_DIR)).filter((f) => f.endsWith(".md")).length;
   } catch {
     return 0;
   }
 }
 
-function main() {
-  const { force, help, target } = parseArgs(process.argv.slice(2));
+async function main() {
+  const { force, help, offline, ref, target } = parseArgs(process.argv.slice(2));
 
   if (help) {
     printHelp();
     return;
   }
 
-  const conflicts = listConflicts(target);
-
+  const conflicts = DIRS.filter((dir) => existsSync(join(target, dir))).map((dir) => `${dir}/`);
   if (conflicts.length > 0 && !force) {
     console.error("Installation blocked, the following already exist:");
-    for (const conflict of conflicts) {
-      console.error(`  ${conflict}`);
-    }
+    for (const conflict of conflicts) console.error(`  ${conflict}`);
     console.error("\nRe-run with --force to overwrite.");
     process.exit(1);
   }
 
-  copyPackageFiles(target, force);
+  mkdirSync(target, { recursive: true });
+
+  let source;
+  if (offline) {
+    copyBundle(target);
+    source = "the copy bundled with this package (--offline)";
+  } else {
+    const files = await fetchLive(ref);
+    if (files) {
+      writeFiles(target, files);
+      source = `${REPO} (${ref})`;
+    } else {
+      copyBundle(target);
+      source = "the copy bundled with this package (network unavailable)";
+    }
+  }
 
   console.log(`Installed Slider Pro AI Connector skills to ${target}`);
-  console.log(`  slider-skills/slider-pro-skills.md`);
-  console.log(`  slider-skills/slider-pro-skills-reference.md`);
-  console.log(`  components/ (${countComponents()} component prop docs)`);
-  console.log("\nPoint your AI coding agent at slider-skills/slider-pro-skills.md to load it.");
+  console.log(`  source: ${source}`);
+  console.log(`  ${OUT_SKILLS_DIR}/slider-pro-skills.md`);
+  console.log(`  ${OUT_SKILLS_DIR}/slider-pro-skills-reference.md`);
+  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('Then tell the agent: "npx @digital-gravy/etch-connector serve"');
 }
 
-main();
+main().catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/lib/skills-source.js

@@ -0,0 +1,65 @@
+// Single source of truth for where the skills come from and how their links are
+// rewritten for an installed project. Both scripts/build.js (which bundles a
+// copy at publish time) and bin/cli.js (which prefers a live copy at install
+// time) import this, so the two paths cannot drift in how they rewrite links.
+
+export const REPO = "udoro/SliderPro-Etch-Docs";
+export const DEFAULT_REF = "master";
+export const DOCS_URL = "https://design-with-cracka.gitbook.io/etchsliderpro";
+
+// Where things live in the docs repo.
+export const REPO_SKILLS_DIR = "ai-connector/slider-skills";
+export const REPO_COMPONENTS_DIR = "components";
+export const REPO_MANIFEST = "ai-connector/skills-manifest.json";
+
+// Where they land in a user's project.
+export const OUT_SKILLS_DIR = "slider-skills";
+export const OUT_COMPONENTS_DIR = "components";
+
+// The docs repo nests slider-skills/ two levels below the root
+// (ai-connector/slider-skills/), so it links components/ as ../../components/.
+// Installed, slider-skills/ sits directly under the project root, so that
+// becomes ../components/.
+//
+// The sibling doc pages the skills link to do not ship in the package at all,
+// so point those at the public site rather than leave a link resolving to
+// nothing.
+export const PATH_REWRITE = [
+  [/\.\.\/\.\.\/components\//g, "../components/"],
+  [/\.\.\/\.\.\/card-stack-templates\.md/g, `${DOCS_URL}/card-stack-templates`],
+  [/\.\.\/\.\.\/premade-templates\.md/g, `${DOCS_URL}/premade-templates`],
+  [/\.\.\/\.\.\/javascript-api\.md/g, `${DOCS_URL}/javascript-api`],
+  [/\.\.\/\.\.\/styling-and-responsive\.md/g, `${DOCS_URL}/styling-and-responsive`],
+  [/\.\.\/\.\.\/admin-settings\.md/g, `${DOCS_URL}/admin-settings`],
+  [/\.\.\/\.\.\/troubleshooting\.md/g, `${DOCS_URL}/troubleshooting`],
+];
+
+export function applyRewrites(content) {
+  let out = content;
+  for (const [pattern, replacement] of PATH_REWRITE) out = out.replace(pattern, replacement);
+  return out;
+}
+
+/**
+ * Only a markdown LINK TARGET pointing outside the package is a defect: it would
+ * 404 for every installed user. A bare ../../ path in prose is not, because the
+ * skills files deliberately reference optional local files and always say what
+ * to do when they are absent.
+ */
+export function findStaleLinks(content) {
+  return [...content.matchAll(/\]\((\.\.\/\.\.\/[^)]+)\)/g)].map((m) => m[1]);
+}
+
+export function rawUrl(ref, repoPath) {
+  return `https://raw.githubusercontent.com/${REPO}/${ref}/${repoPath}`;
+}
+
+/**
+ * A fetched file only counts if it is non-empty markdown. A proxy or an error
+ * page returning 200 with HTML would otherwise be written out as a skills file.
+ */
+export function looksLikeMarkdown(text) {
+  if (!text || text.trim().length < 200) return false;
+  const head = text.slice(0, 400).toLowerCase();
+  return !head.includes("<!doctype html") && !head.includes("<html");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sliderpro-agentic-skills-etch",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Installs the Slider Pro for Etch AI Connector skills files and component docs into any project",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "bin",
+    "lib",
     "skills-package"
   ],
   "scripts": {

package/skills-package/manifest.json

@@ -0,0 +1,43 @@
+{
+  "generated": "2026-08-22",
+  "skills": [
+    {
+      "repo": "ai-connector/slider-skills/slider-pro-skills-reference.md",
+      "out": "slider-skills/slider-pro-skills-reference.md"
+    },
+    {
+      "repo": "ai-connector/slider-skills/slider-pro-skills.md",
+      "out": "slider-skills/slider-pro-skills.md"
+    }
+  ],
+  "components": [
+    {
+      "repo": "components/dwc-slide.md",
+      "out": "components/dwc-slide.md"
+    },
+    {
+      "repo": "components/dwc-slider-nav-button.md",
+      "out": "components/dwc-slider-nav-button.md"
+    },
+    {
+      "repo": "components/dwc-slider-pagination.md",
+      "out": "components/dwc-slider-pagination.md"
+    },
+    {
+      "repo": "components/dwc-slider-play-pause.md",
+      "out": "components/dwc-slider-play-pause.md"
+    },
+    {
+      "repo": "components/dwc-slider-progress.md",
+      "out": "components/dwc-slider-progress.md"
+    },
+    {
+      "repo": "components/dwc-slider-wrapper.md",
+      "out": "components/dwc-slider-wrapper.md"
+    },
+    {
+      "repo": "components/dwc-slider.md",
+      "out": "components/dwc-slider.md"
+    }
+  ]
+}

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

@@ -142,6 +142,9 @@ etch.blocks.create(json, parentId?, index?)  // returns new id
 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.blocks.addClass(blockId, name)          // plain elements only; throws on a component
+etch.blocks.getJson(id).script               // { code }, the JavaScript code block
 await etch.saveAsync()
 ```
 
@@ -198,6 +201,87 @@ Putting a Slider straight inside a Wrapper's `children` renders nothing.
 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
+the component path is the one that matters here, because everything Slider Pro ships is a component.
+
+**On a component**, `addClass` throws `Block "<id>" is not an HTML block.` Classes go through the
+component's own class-typed prop, and the value is the **style id**, not the class name:
+
+```js
+const styleId = etch.styles.create('.flow-demo', 'border-radius: 1rem;');  // returns an id
+etch.blocks.setAttribute(wrapperId, 'customClass', styleId);
+```
+
+Etch resolves the id to the selector name when it renders, so the page gets
+`class="dwc-slider-wrapper flow-demo"`. The id never appears in the output. Store the id, not the
+name, so the class survives being renamed in the Etch UI.
+
+The class-typed props, one per component:
+
+| Component | Prop |
+| --- | --- |
+| DWC Slider Wrapper | `customClass` |
+| DWC Slider | `sliderClass` |
+| DWC Slide, Progress, Play-Pause, Pagination | `class` |
+| DWC Slider Nav Button | `buttonClass`, `buttonWrapperClass` |
+
+**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');
+```
+
+Passing a style id here does not resolve. It is treated as a literal name and sanitised, so
+`30xsolr` silently becomes the class `xsolr`. Creating the element with `attributes: { class: '...' }`
+works too and is fine when you are building a subtree in one call.
+
+Either way the CSS rule itself is `etch.styles.create('.fall-card', '...')`, which is what the
+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.
+
+**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
@@ -373,6 +457,38 @@ setGroup(thumbId, 'sliderSetup', { sliderRole: 'thumbnails', transitionType: 'Lo
 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
@@ -407,43 +523,79 @@ so the CSS can fan the left and right sides in opposite directions:
 .deck-stack-featured &:is([data-pos='2'], [data-pos='-2']) { /* ring 2, both sides */ }
 ```
 
-The stack container carries **`data-tiers`**, the number of rings the CSS defines, which lets the
-same CSS serve a three-ring fan and a one-ring stack.
+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 script does three things:
+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. per card: SIGNED offset from the active card, clamped to the deepest ring
-var signed = index - activeIndex;
-card.setAttribute('data-pos', String(Math.max(-MAX_TIERS, Math.min(MAX_TIERS, signed))));
+// 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. hit-testing: stack order by distance, and clicks off beyond the clickable rings
-var rank = Math.abs(signed);
+// 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
 
-There is no script block type. Add a `script` element inside the wrapper:
+**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
-el('script', {}, [ text(SOURCE) ])
+const wrapperId = etch.blocks.create({
+  type: 'etch/component', version: 1, context: {}, children: [ /* ... */ ],
+  componentId: C['DWC Slider Wrapper'], attributes: {},
+  script: { code: "(function () { /* ... */ })();" }
+});
 ```
 
-Component `<script>` elements are left alone on Sync Without Slider wrappers, which is why a deck
-script keeps working. Do not add one to a wrapper that contains a real slider and expect the same.
+`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.
 
-Step 3 is not optional. Stacked cards are coplanar, so the browser hit-tests them by DOM order and
-a click near the front card can land on one three positions away.
+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
@@ -581,6 +733,47 @@ 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.
+
+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.
+
+**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:
+
+```css
+&.etch-builder-block { min-block-size: 640px; }
+```
+
+**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.
+
+**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.