sliderpro-agentic-skills-etch 0.1.2 → 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.2",
+  "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

@@ -242,6 +242,46 @@ 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.
+
+**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
@@ -417,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
@@ -661,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.