aura-components-mcp 1.5.3 → 1.6.0

package/README.md

@@ -8,7 +8,7 @@
 
 > I got tired of opening twenty Aura tabs every time I started a landing page. So I built the MCP server I wanted: every free thing on aura.build, one stdio call away, no account, no key, no browser.
 
-> **v1.5.0** — 20 tools. Search never empties (OR-token fallback + suggested queries), bulk-fetch with `aura_bulk_fetch` (`aura_bundle` alias),undle`, one-turn page builds with `aura_scaffold_page`, dark/light faceting, related items, legal asset install.
+> **v1.6.0** — 20 tools. Search facets now equal detail facets (icons, fonts, weight), skills deduped by source_url, full DESIGN token surface with preview-mode warnings, legal asset plans, scoped CSS + paginated installs, transparent fallbacks. Search never empties (OR-token fallback + suggested queries), bulk-fetch with `aura_bulk_fetch` (`aura_bundle` alias),undle`, one-turn page builds with `aura_scaffold_page`, dark/light faceting, related items, legal asset install.
 
 Point any MCP client at `dist/server.js` and your agent can search 2,495 free components, read 187 agent skills in full, pull 30,688 assets, and apply 725 DESIGN.md systems. It answers in seconds because there is nothing to log into and almost nothing to download: one bundled JS file, zero dependencies.
 
@@ -127,6 +127,17 @@ npm run build   # rebundle src/*.mjs into dist/server.js
 
 Layout: `src/config.mjs` holds env parsing. `src/http.mjs` hides timeouts and retries behind an injectable fetch. `src/catalog.mjs` is the deep module (queries, cache, shaping, counts). `src/guide.mjs` turns rows into install plans. `src/tools.mjs` validates args. `src/protocol.mjs` speaks JSON-RPC. `src/server.mjs` only wires stdio.
 
+## Share
+
+Star it if it saved you a tab or twenty: [github.com/swastiksingh-dev/Aura-Components-MCP](https://github.com/swastiksingh-dev/Aura-Components-MCP). Reposits welcome — see [DIRECTION.md](./DIRECTION.md) for where this is headed.
+
+```text
+built a free design MCP on aura.build: 2495 components, 187 skills, 30k assets, 20 tools. no login. resources are @MengTo's
+
+npx -y aura-components-mcp
+https://github.com/swastiksingh-dev/Aura-Components-MCP
+```
+
 ## Credits and license
 
 Server code by [swastiksingh-dev](https://github.com/swastiksingh-dev), MIT. Free to fork, use, and sell with. Catalogue text, code, and images belong to Aura and the creators listed in each `author` field; follow Aura's terms for that content. If you fork this, keep the credit line and point people at the original repo.

package/dist/server.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// aura-components-mcp v1.0.0 — bundled (zero deps). Built by swastiksingh-dev.
+// aura-components-mcp v1.6.0 — bundled (zero deps). Built by swastiksingh-dev.
 
 // ---- config.mjs ----
 // Module: config — one small interface (loadConfig) over all env parsing.
@@ -102,9 +102,9 @@ const CATALOG_SORTS = {
 };
 
 const LIST_COLS = {
-  // Lists exclude code (13KB/row): theme falls back to background + tags heuristics.
-  // Full code loads only on get/bundle, where facets recompute exactly.
-  components: "id,title,description,tags,premium,views,forks,slug,background,created_by,created_at,updated_at",
+  // PostgREST can't substring server-side: lists fetch code but shapeRow truncates to
+  // a 600-char probe for facets BEFORE the truncation marker (see shapeRow). ~0.7KB/row.
+  components: "id,title,description,tags,code,premium,views,forks,slug,background,created_by,created_at,updated_at",
   skills: "id,title,description,source_url,views,forks,featured,created_by,created_at,updated_at",
   assets: "id,title,description,keywords,media_type,premium,views,forks,image_800w,video_url,video_poster_url,created_by,created_at",
   design_systems: "id,slug,title,description,views,forks,featured,created_by,created_at,updated_at",
@@ -176,20 +176,42 @@ const trunc = (s, n) => (s && s.length > n ? s.slice(0, n) + "…[truncated]" :
 function pageUrl(kind, row) {
   if (kind === "components") return SITE + "/component/" + row.slug;
   if (kind === "skills") return SITE + "/skills/" + row.id;
+  // ISS9: asset pages are query-routed (no /assets/ID route exists). Keep the q= form
+  // but ALSO expose a stable key so agents can cite: id + slug + title together.
   if (kind === "assets") return SITE + "/assets?q=" + encodeURIComponent(row.title ?? "");
   return SITE + "/design-systems/" + (row.slug ?? row.id);
 }
 
+function assetKey(row) {
+  return { id: row.id, slug: row.slug ?? null, title: row.title ?? null };
+}
+
 function shapeRow(kind, row, cfg, withFacets) {
   const base = { ...row };
-  if (kind === "components" && typeof base.code === "string") { base.code_chars = base.code.length; base.code = trunc(base.code, cfg.codeChars); }
+  // Facets probe the first 600 chars of FULL code before truncation, so search facets
+  // equal detail facets for icons/fonts/theme. Weight uses the true length (ISS1/2/3).
+  if (kind === "components" && typeof base.code === "string") {
+    base.code_chars = base.code.length;
+    if (withFacets) { try { base.facets = withFacets(kind, { ...base, code: base.code.slice(0, 600) }, { fullLength: base.code.length }); } catch { /* never break rows */ } }
+    base.code = trunc(base.code, cfg.codeChars);
+  }
   if (kind === "skills" && typeof base.content === "string") base.content = trunc(base.content, cfg.contentChars);
   if (kind === "design_systems") {
     if (typeof base.content === "string") base.content = trunc(base.content, cfg.contentChars);
     if (typeof base.preview_html === "string") base.preview_html = trunc(base.preview_html, cfg.codeChars);
   }
   base.page_url = pageUrl(kind, row);
-  if (withFacets) { try { base.facets = withFacets(kind, base); } catch { /* facets never break rows */ } }
+  if (kind === "assets") base.asset_key = assetKey(row);
+  if (withFacets && !base.facets) { try { base.facets = withFacets(kind, base); } catch { /* facets never break rows */ } }
+  // ISS8: force absolute Supabase URLs — relative variant paths break fetch.
+  if (kind === "assets") {
+    const abs = (u) => (!u ? u : (/^https?:\/\//i.test(u) ? u : ("https://hoirqrkdgbmvpwutwuwj-all.supabase.co/storage/v1/object/public/assets/" + String(u).replace(/^\/+/, ""))));
+    for (const k of ["image_320w", "image_800w", "image_1600w", "image_3840w", "image_original", "image_url", "video_url", "video_poster_url"]) if (typeof base[k] === "string") base[k] = abs(base[k]);
+    if (base.facets) {
+      if (base.facets.download) base.facets.download = abs(base.facets.download);
+      if (base.facets.preview) base.facets.preview = abs(base.facets.preview);
+    }
+  }
   return base;
 }
 
@@ -278,15 +300,39 @@ function createCatalog({ fetcher, config, now = () => Date.now(), facetsFn = nul
           } catch { /* keep original empty result */ }
         }
       }
+      // ISS7: dedupe skills by source_url (same SKILL.md listed twice). First (most-viewed)
+      // wins, gets canonical:true; dupes are dropped and counted in deduped.
+      let deduped = 0;
+      if (kind === "skills") {
+        const seen = new Set();
+        const kept = [];
+        for (const r of rows) {
+          const u = (r.source_url || "").trim().toLowerCase();
+          if (u && seen.has(u)) { deduped++; continue; }
+          if (u) seen.add(u);
+          kept.push(r);
+        }
+        const byUrl = new Map();
+        for (const r of kept) {
+          const u = (r.source_url || "").trim().toLowerCase();
+          if (u && (!byUrl.has(u) || (r.views || 0) > (byUrl.get(u).views || 0))) byUrl.set(u, r);
+        }
+        rows = kept.map((r) => {
+          const u = (r.source_url || "").trim().toLowerCase();
+          return (u && byUrl.get(u) === r) ? { ...r, canonical: true } : r;
+        });
+      }
       const enriched = await enrichAuthors(rows);
       const out = { kind, total, limit, offset, items: enriched.map((r) => shapeRow(kind, r, config, facetsFn)), cached: false };
+      if (deduped) out.deduped = deduped;
       // Post-filter: theme (dark|light) is derived, not a column — filter shaped rows.
       if (q.theme && (kind === "components")) {
         const want = String(q.theme).toLowerCase();
         out.items = out.items.filter((it) => (it.facets && it.facets.theme) === want);
       }
-      if (fallback) out.fallback = fallback;
-      else if ((!rows || !rows.length) && toks.length) out.suggested_queries = suggest(toks);
+      // ISS15: transparent fallback — agents see what happened, not a magic string.
+      if (fallback) { out.fallback = fallback; out.isFallback = true; out.fallback_score = "token-overlap:" + toks.length + "-terms"; }
+      else if ((!rows || !rows.length) && toks.length) { out.isFallback = false; out.suggested_queries = suggest(toks).filter((s) => !/^[a-z0-9]{8,}$/i.test(s.replace(/\s/g, ""))); if (!out.suggested_queries.length) out.suggested_queries = ["hero", "pricing", "landing page"]; }
       cacheSet(key, out);
       return out;
     })();
@@ -365,7 +411,8 @@ function createCatalog({ fetcher, config, now = () => Date.now(), facetsFn = nul
   }
 
   // Related: same-tag / same-text overlap, views-ranked, excluding self.
-  async function relatedItems(kind, idOrSlug, limit = 3) {
+  // ISS10: freeOnly default true — free flows never get Pro recommendations.
+  async function relatedItems(kind, idOrSlug, limit = 3, freeOnly = true) {
     const got = await getItem(kind, idOrSlug);
     const item = got.item;
     const toks = queryTokens(item.title + " " + (item.description || "")).slice(0, 3);
@@ -375,7 +422,8 @@ function createCatalog({ fetcher, config, now = () => Date.now(), facetsFn = nul
     const sel = LIST_COLS[kind];
     const idCol = (kind === "components") ? "id" : "id";
     const selfId = encodeURIComponent(String(item.id));
-    const url = base + "/rest/v1/" + kind + "?select=" + encodeURIComponent(sel) + "&private=eq.false" + (kind === "components" || kind === "assets" ? "" : "") + tagF + "&" + idCol + "=neq." + selfId + (orParts.length ? "&or=(" + orParts.join(",") + ")" : "") + "&order=views.desc&limit=" + lim;
+    const premF = (freeOnly && (kind === "components" || kind === "assets")) ? "&premium=eq.false" : "";
+    const url = base + "/rest/v1/" + kind + "?select=" + encodeURIComponent(sel) + "&private=eq.false" + premF + tagF + "&" + idCol + "=neq." + selfId + (orParts.length ? "&or=(" + orParts.join(",") + ")" : "") + "&order=views.desc&limit=" + lim;
     try {
       const { rows } = await fetcher.getJson(url, headers);
       const enriched = await enrichAuthors(rows);
@@ -387,10 +435,10 @@ function createCatalog({ fetcher, config, now = () => Date.now(), facetsFn = nul
 }
 
 // ---- protocol.mjs ----
+const SERVER_INFO = { name: "aura-components-mcp", version: "1.6.0" };
 // Module: protocol — stdio JSON-RPC framing + MCP handshake + error codes.
 // One interface: createSession(send) -> { dispatch(msg) }. No business logic.
 
-const SERVER_INFO = { name: "aura-components-mcp", version: "1.0.0" };
 const PROTOCOL_VERSION = "2024-11-05";
 
 const protocolFn_err = (code, message, data) => ({ code, message, ...(data === undefined ? {} : { data }) });
@@ -463,21 +511,39 @@ const GUIDE_CDN = {
   iconify: 'https://code.iconify.design/iconify-icon/1.0.7/iconify-icon.min.js',
 };
 
+// Font allowlist: real families only. Tailwind weight/size utilities (medium, semibold,
+// normal, light-as-weight, size-*) are NOT families — old regex leaked them into fonts[].
+const KNOWN_FONTS = ['inter', 'geist', 'manrope', 'sora', 'space-grotesk', 'space-mono', 'poppins', 'montserrat', 'playfair-display', 'instrument-serif', 'dm-sans', 'dm-serif-display', 'jetbrains-mono', 'ibm-plex-mono', 'ibm-plex-serif', 'plus-jakarta-sans', 'bricolage-grotesque', 'newsreader', 'fraunces', 'lora', 'merriweather', 'libre-baskerville', 'cormorant-garamond', 'gfs-didot', 'bodoni-moda', 'cardo', 'marcellus', 'gloock', 'aboreto', 'syne', 'urbanist', 'sora', 'anton', 'bebas-neue', 'archivo-black', 'league-gothic', 'fredoka', 'chewy', 'foldit', 'oi', 'honk', 'nabla', 'quicksand', 'nunito', 'work-sans', 'oswald', 'lora', 'roboto', 'open-sans', 'figtree', 'outfit', 'lexend', 'gloria-hallelujah', 'caveat'];
+const FONT_RE = /font-(?:family-)?\[?['"]?([a-z][a-z0-9-]*)/g;
+
 function detectNeeds(code, tags) {
   const c = String(code || '').toLowerCase();
   const t = new Set((tags || []).map((x) => String(x).toLowerCase()));
   const needsTailwind = c.includes('class=') || t.has('tailwind');
-  const needsIcons = c.includes('iconify') || c.includes('svg');
+  // Probes must work on a 2k prefix too: icon svgs usually appear in the first screen of markup.
+  // svg alone under-matches in lists (no code fetched) — but must not over-claim either:
+  // 'svg' counts only with an icon-ish neighbor (iconify, <svg, lucide, heroicons, feather).
+  const needsIcons = c.includes('iconify') || c.includes('<svg') || c.includes('lucide') || c.includes('heroicon') || c.includes('data-lucide');
   const needsKeyframes = c.includes('keyframes') || c.includes('animation:');
   const fonts = new Set();
-  for (const m of c.matchAll(/font-([a-z0-9-]+)/g)) fonts.add(m[1]);
+  for (const m of c.matchAll(FONT_RE)) {
+    const fam = m[1].replace(/['"\]]/g, '');
+    if (KNOWN_FONTS.includes(fam)) fonts.add(fam);
+  }
+  // font-family: 'X', Y declarations (not utility classes)
+  for (const m of c.matchAll(/font-family\s*:\s*([^;}]{1,80})/g)) {
+    for (const part of m[1].split(',')) {
+      const fam = part.trim().replace(/['"]/g, '').toLowerCase().replace(/\s+/g, '-');
+      if (KNOWN_FONTS.includes(fam)) fonts.add(fam);
+    }
+  }
   return { needsTailwind, needsIcons, needsKeyframes, fonts: [...fonts].slice(0, 6) };
 };
 
 // Facets: cheap derived signals so search lists answer "dark? heavy? pro?" without a get.
 // theme: dark|light|mixed|unknown from background field + code palette probes.
 // weight: code_chars bucket (s/m/l) so agents can prefer light embeds.
-function facets(kind, row) {
+function facets(kind, row, opts) {
   const f = {};
   if (kind === 'components') {
     const bg = String(row.background || '').toLowerCase();
@@ -490,7 +556,7 @@ function facets(kind, row) {
     const bgDark = bg.includes('000') && !bg.includes('fff');
     const bgLight = bg.includes('fff') && !bg.includes('000');
     f.theme = bgDark || tagDark ? 'dark' : (bgLight || tagLight ? 'light' : (code ? (darkHits > lightHits * 2 ? 'dark' : (lightHits > darkHits * 2 ? 'light' : (darkHits || lightHits ? 'mixed' : 'unknown'))) : (tags.includes('saas') || tags.includes('minimal') ? 'light' : 'unknown')));
-    const n = String(row.code || '').length;
+    const n = (opts && opts.fullLength) || String(row.code || '').length;
     f.weight = n > 20000 ? 'l' : (n > 8000 ? 'm' : 's');
     f.code_chars = n;
     const needs = detectNeeds(row.code || '', row.tags || []);
@@ -498,6 +564,13 @@ function facets(kind, row) {
     f.needsIcons = needs.needsIcons;
     f.fonts = needs.fonts;
   }
+  // ISS14 lives here too: license is top-level on every asset row, not buried.
+  // ISS13: rewrite hotlinked demo images to stable asset references where possible.
+  // i.pravatar.cc + bare demo URLs 404 in production; flag them in the install plan.
+  if (kind === 'components' && typeof row.code === 'string') {
+    const hot = [...row.code.matchAll(/<img[^>]+src=["']([^"']+)["']/gi)].map((m) => m[1]).filter((u) => /pravatar|placehold|dummyimage|unsplash\/photos\/..\/download|example\.com/i.test(u));
+    if (hot.length) row = { ...row, _hotlinked: [...new Set(hot)].slice(0, 5) };
+  }
   if (kind === 'assets' || row.image_800w || row.image_original || row.video_url) {
     // Resolved 2026-09-13 from primary source https://www.aura.build/terms §4-5:
     // catalogue content is the exclusive property of DESIGNCODE IO PTE. LTD.;
@@ -506,7 +579,11 @@ function facets(kind, row) {
     f.download = row.image_original || row.image_1600w || row.image_800w || row.video_url || null;
     f.preview = row.image_800w || row.video_poster_url || null;
   }
-  if (kind === 'design_systems') f.has_preview = Boolean(row.preview_html);
+  if (kind === 'design_systems') {
+    // ISS4: lists never fetch preview_html (24KB/row). has_preview:true is authoritative
+    // only on detail; on lists report 'unknown-list' so agents fetch instead of trusting false.
+    f.has_preview = row.preview_html !== undefined ? Boolean(row.preview_html) : 'unknown-list';
+  }
   return f;
 }
 
@@ -526,11 +603,23 @@ function installGuide(kind, row) {
       steps.push('Add the iconify-icon CDN script so the icon tags render.');
     }
     if (needs.needsKeyframes) steps.push('Keep the embedded style block with the markup: that is where the keyframes live.');
+    // ISS11+12: pagination + CSS scoping. Code ships truncated at codeChars; the scope
+    // prefix below prevents .button/.inner/.point collisions in multi-component scaffolds.
+    const scope = 'aura-' + String(row.slug || row.id).toLowerCase().replace(/[^a-z0-9]+/g, '');
+    const fullLen = String(row.code || '').length;
+    const isTrunc = /…\[truncated\]$/.test(String(row.code || ''));
+    if (isTrunc) {
+      files.push({ path: 'components/' + (row.slug || row.id) + '.part1.html', contains: 'markup part 1 of N — fetch aura_get_component again and concatenate code chunks' });
+      steps.push('Code is paginated (' + fullLen + ' chars shown of more): install part files in order, or re-fetch for the full body.');
+    } else {
+      files.push({ path: 'components/' + (row.slug || row.id) + '.html', contains: 'section markup plus its style block' });
+    }
+    steps.push('Scope global CSS before pasting: prefix bare selectors (.button, .inner, .point) with .' + scope + ' to avoid collisions in multi-component pages.');
     steps.push('Paste the markup where the section belongs and update the CTA link (it ships as #).');
     if (url) steps.push('Preview first: ' + url);
-    files.push({ path: 'components/' + (row.slug || row.id) + '.html', contains: 'section markup plus its style block' });
+    if (row._hotlinked && row._hotlinked.length) steps.push('Replace demo images before shipping (' + row._hotlinked.slice(0, 3).join(', ') + '): hotlinked placeholders 404 in production — swap for aura_search_assets results.');
     if (needs.fonts.length) files.push({ path: 'styles/fonts.css', contains: 'font families referenced: ' + needs.fonts.join(', ') });
-    return { kind, title: row.title, page_url: url, free: row.premium === false, steps, deps, files, needs };
+    return { kind, title: row.title, page_url: url, free: row.premium === false, steps, deps, files, needs, css_scope: scope, code_truncated: isTrunc };
   }
   if (kind === 'skills') {
     steps.push('Read the SKILL.md content from aura_get_skill first: it names its own triggers and pitfalls.');
@@ -539,15 +628,37 @@ function installGuide(kind, row) {
     return { kind, title: row.title, page_url: url, steps, deps, files: [{ path: 'skills/' + row.id + '/SKILL.md', contains: 'full skill content' }] };
   }
   if (kind === 'design_systems') {
+    // ISS6: derive preview deps from preview_html so agents don't ship static pages.
+    const ph = String(row.preview_html || '');
+    const pl = ph.toLowerCase();
+    const has = (...ss) => ss.some((s) => pl.includes(s));
+    if (has('cdn.tailwindcss.com', 'tailwind')) deps.push({ name: 'tailwindcss', via: 'CDN (in preview_html)', cdn: GUIDE_CDN.tailwind });
+    if (has('iconify', '<svg', 'lucide', 'data-lucide')) deps.push({ name: 'iconify-icon', via: 'CDN (in preview_html)', cdn: GUIDE_CDN.iconify });
+    if (has('gsap')) deps.push({ name: 'gsap', via: 'CDN (in preview_html)', cdn: 'https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js' });
+    if (has('scrolltrigger')) deps.push({ name: 'gsap-ScrollTrigger', via: 'CDN (in preview_html)', cdn: 'https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/ScrollTrigger.min.js' });
+    const fonts = new Set();
+    for (const m of pl.matchAll(/family=([a-z+]+)/g)) fonts.add(m[1].replace(/\+/g, '-'));
+    if (fonts.size) deps.push({ name: 'google-fonts:' + [...fonts].slice(0, 4).join(','), via: 'link (in preview_html)' });
     steps.push('Copy the DESIGN.md content into your repo as DESIGN.md and treat it as the source of truth.');
     steps.push('Apply the color, type, and spacing tokens before copying any component markup.');
+    if (deps.length) steps.push('Install preview deps first (' + deps.map((d) => d.name).join(', ') + ') — the preview_html needs them.');
     return { kind, title: row.title, page_url: url, steps, deps, files: [{ path: 'DESIGN.md', contains: 'tokens and rules' }] };
   }
   steps.push('Use the image_800w URL for previews and image_original for production.');
   return { kind, title: row.title, page_url: url, steps, deps, files };
 };
 
-function tokenHints(content) {
+// ISS5: full token surface — colors + typography + spacing + radius — so scaffolded
+// pages don't lose the system. Also detects preview dark/light mode so agents don't
+// apply light-cream tokens to a dark preview body.
+function previewMode(previewHtml) {
+  const h = String(previewHtml || '').toLowerCase();
+  if (/bg-black|bg-neutral-950|bg-zinc-950|bg-slate-950|bg-\[#0/.test(h)) return 'dark';
+  if (/bg-white|bg-neutral-50|bg-slate-50/.test(h)) return 'light';
+  return 'unknown';
+}
+
+function tokenHints(content, previewHtml) {
   const Q = String.fromCharCode(39);
   const lines = String(content || '').split(Q + 'n' === Q + 'n' ? '\n' : '\n');
   const get = (key) => {
@@ -563,13 +674,42 @@ function tokenHints(content) {
   };
   const tokens = {
     primary: get('primary'),
+    secondary: get('secondary'),
+    accent: get('accent'),
     background: get('background'),
     surface: get('surface'),
-    text: get('text-primary') || get('text_primary'),
+    text_primary: get('text-primary') || get('text_primary'),
+    text_secondary: get('text-secondary') || get('text_secondary'),
+    border: get('border'),
+    display_font: get('display_lg_fontfamily') || get('display-font'),
+    body_font: get('body_md_fontfamily') || get('body-font'),
+    mono_font: get('label_md_fontfamily') || get('mono-font'),
+    section_padding: get('section-padding') || get('section_padding'),
+    card_padding: get('card-padding') || get('card_padding'),
+    card_radius: get('card') === null ? get('card_radius') : null,
+    control_radius: get('control'),
+    pill_radius: get('pill'),
   };
-  const rows = Object.entries(tokens).filter((e) => e[1]).map((e) => '  --aura-' + e[0] + ': ' + e[1] + ';');
+  const pick = (obj, keys) => { const o = {}; for (const k of keys) if (obj[k]) o[k] = obj[k]; return o; };
+  const colors = pick(tokens, ['primary', 'secondary', 'accent', 'background', 'surface', 'text_primary', 'text_secondary', 'border']);
+  const rows = [];
+  for (const [k, v] of Object.entries(colors)) rows.push('  --aura-' + k.replace(/_/g, '-') + ': ' + v + ';');
+  if (tokens.body_font) rows.push('  --aura-font-body: ' + tokens.body_font + ';');
+  if (tokens.display_font) rows.push('  --aura-font-display: ' + tokens.display_font + ';');
+  if (tokens.mono_font) rows.push('  --aura-font-mono: ' + tokens.mono_font + ';');
+  if (tokens.section_padding) rows.push('  --aura-section-padding: ' + tokens.section_padding + ';');
+  if (tokens.card_padding) rows.push('  --aura-card-padding: ' + tokens.card_padding + ';');
+  if (tokens.card_radius) rows.push('  --aura-radius-card: ' + tokens.card_radius + ';');
+  if (tokens.control_radius) rows.push('  --aura-radius-control: ' + tokens.control_radius + ';');
+  if (tokens.pill_radius) rows.push('  --aura-radius-pill: ' + tokens.pill_radius + ';');
   const css = rows.length ? ':root{' + '\n' + rows.join('\n') + '\n}' : '';
-  return { tokens, css };
+  const mode = previewMode(previewHtml);
+  const warn = (mode === 'dark' && tokens.background && !/000|0f1115|111827|1a1a1a|09090b/i.test(tokens.background))
+    ? 'tokens say light background ' + tokens.background + ' but preview_html renders dark — follow the preview body, not the tokens, or ask which mode is wanted'
+    : ((mode === 'light' && tokens.background && /000000|0f1115/i.test(tokens.background))
+      ? 'tokens say dark background but preview renders light — follow the preview body'
+      : null);
+  return { tokens, css, preview_mode: mode, mode_warning: warn };
 };
 
 // ---- tools.mjs ----
@@ -671,7 +811,7 @@ function createHandlers(catalog) {
     aura_use_design_system: async (a) => { a = a || {}; const id = a.id !== undefined ? a.id : a.slug;
       if (typeof id !== 'string' || !id) toolFn_bad('provide id or slug (string)');
       const got = await catalog.getItem('design_systems', id);
-      return textResult({ item: got.item, install: installGuide('design_systems', got.item), tokens: tokenHints(got.item.content || '') }); },
+      return textResult({ item: got.item, install: installGuide('design_systems', got.item), tokens: tokenHints(got.item.content || '', got.item.preview_html || '') }); },
     aura_trending: async (a) => { a = a || {}; const limit = toolFn_num(a.limit, 'limit') || 5;
       const r = await Promise.all([
         catalog.searchCatalog('components', { freeOnly: true, sort: 'trending', limit }),
@@ -679,7 +819,7 @@ function createHandlers(catalog) {
         catalog.searchCatalog('assets', { freeOnly: true, sort: 'trending', limit }),
         catalog.searchCatalog('design_systems', { sort: 'trending', limit }),
       ]);
-      return textResult({ window: 'last 90 days by views (7-day seed is empty: newest catalogue rows are months old)', components: r[0], skills: r[1], assets: r[2], design_systems: r[3] }); },
+      return textResult({ window: 'last 90 days by views', window_note: '7-day seed is empty (newest catalogue rows are months old); 90d keeps trending meaningful. Components here are low-signal (views 0-5): prefer skills/assets trending.', components: r[0], skills: r[1], assets: r[2], design_systems: r[3] }); },
     aura_categories: async () => textResult({ categories: await catalog.categoryCounts() }),
     aura_bundle: async (a) => { a = a || {}; const ids = idList(a.ids, 'ids') || idList(a.slugs, 'slugs');
       if (!ids || !ids.length) toolFn_bad('provide ids (array of 1-8 numbers/strings) or slugs (array of strings)');

package/flow/app.js

@@ -1,40 +1,178 @@
-(function(){
-'use strict';
-var root=document.documentElement;
-try{var s=localStorage.getItem('acm-theme');if(s==='dark'||s==='light')root.setAttribute('data-theme',s);else root.setAttribute('data-theme','dark');}catch(e){root.setAttribute('data-theme','dark');}
-var t=document.getElementById('themeBtn');
-function paint(){if(t)t.textContent=root.getAttribute('data-theme')==='dark'?'\u263E':'\u2600';}
-if(t)t.addEventListener('click',function(){var n=root.getAttribute('data-theme')==='dark'?'light':'dark';root.setAttribute('data-theme',n);try{localStorage.setItem('acm-theme',n);}catch(e){}paint();});
-paint();
-var here=(location.pathname.split('/').pop()||'index.html').toLowerCase().split('?')[0].split('#')[0];
-Array.prototype.forEach.call(document.querySelectorAll('.tabs a'),function(a){var h=(a.getAttribute('href')||'').toLowerCase().split('?')[0].split('#')[0].replace('./','');a.classList.toggle('on',h===here||(here===''&&h==='index.html'));});
-var nodes=[document.getElementById('n0'),document.getElementById('n1'),document.getElementById('n2')];
-var ni=0;function tick(){nodes.forEach(function(n,k){if(n)n.classList.toggle('live',k===ni%3);});ni++;}
-if(nodes[0]){tick();setInterval(tick,1600);}
-var io=null;
-function reveal(){var els=document.querySelectorAll('.reveal');if(!('IntersectionObserver' in window)){Array.prototype.forEach.call(els,function(e){e.classList.add('in');});return;}io=new IntersectionObserver(function(es){es.forEach(function(e){if(e.isIntersecting){e.target.classList.add('in');io.unobserve(e.target);}});},{threshold:.12});Array.prototype.forEach.call(els,function(e){io.observe(e);});}
-if(document.readyState==='loading')document.addEventListener('DOMContentLoaded',reveal);else reveal();
-var cv=document.querySelector('canvas.gl');
-if(cv&&!matchMedia('(prefers-reduced-motion: reduce)').matches){
-(function(){
-var gl=cv.getContext('webgl',{antialias:false,alpha:true});
-if(!gl)return;
-function sh(t,src){var s=gl.createShader(t);gl.shaderSource(s,src);gl.compileShader(s);return gl.getShaderParameter(s,gl.COMPILE_STATUS)?s:null;}
-var vs=sh(gl.VERTEX_SHADER,'attribute vec2 p;void main(){gl_Position=vec4(p,0.,1.);}');
-var fs=sh(gl.FRAGMENT_SHADER,'precision highp float;uniform vec2 R;uniform float T;void main(){vec2 uv=gl_FragCoord.xy/R;vec2 p=uv*2.-1.;p.x*=R.x/R.y;p.y+=.8;float r=length(p);float a=atan(p.y,p.x);float dist=abs(r-1.6);float warp=sin(r*4.-T*.5)*.3;float lines=sin((a+warp)*80.+T*2.);lines=smoothstep(.85,1.,lines);float mask=smoothstep(.5,0.,dist);float glow=.05/(dist*dist+.05);vec3 c1=vec3(0.,.4,1.);vec3 c2=vec3(.8,.1,.9);vec3 base=mix(c1,c2,sin(a*2.+T*.5)*.5+.5);vec3 line=mix(base,vec3(1.),.4);vec3 col=line*lines*mask*2.5+base*glow*1.5;col*=smoothstep(1.5,-.5,p.y);col*=smoothstep(3.,1.,r);gl_FragColor=vec4(col,1.);}');
-if(!vs||!fs)return;
-var pr=gl.createProgram();gl.attachShader(pr,vs);gl.attachShader(pr,fs);gl.linkProgram(pr);
-if(!gl.getProgramParameter(pr,gl.LINK_STATUS))return;
-var buf=gl.createBuffer();gl.bindBuffer(gl.ARRAY_BUFFER,buf);
-gl.bufferData(gl.ARRAY_BUFFER,new Float32Array([-1,1,1,1,-1,-1,1,-1]),gl.STATIC_DRAW);
-var loc=gl.getAttribLocation(pr,'p');var uR=gl.getUniformLocation(pr,'R');var uT=gl.getUniformLocation(pr,'T');
-function fit(){var d=Math.min(devicePixelRatio||1,1.5);var w=cv.clientWidth*d|0,h=cv.clientHeight*d|0;if(cv.width!==w||cv.height!==h){cv.width=w;cv.height=h;gl.viewport(0,0,w,h);}}
-var run=true;
-new IntersectionObserver(function(es){run=es[0].isIntersecting;},{threshold:0}).observe(cv);
-document.addEventListener('visibilitychange',function(){fit();});
-addEventListener('resize',fit,{passive:true});fit();
-function frame(t){requestAnimationFrame(frame);if(!run||document.hidden)return;gl.clearColor(0,0,0,0);gl.clear(gl.COLOR_BUFFER_BIT);gl.useProgram(pr);gl.bindBuffer(gl.ARRAY_BUFFER,buf);gl.vertexAttribPointer(loc,2,gl.FLOAT,false,0,0);gl.enableVertexAttribArray(loc);gl.uniform2f(uR,cv.width,cv.height);gl.uniform1f(uT,t*.001);gl.drawArrays(gl.TRIANGLE_STRIP,0,4);}
-requestAnimationFrame(frame);
+(()=>{"use strict";const r=document.documentElement;
+r.classList.remove("no-js");
+const reduced=matchMedia("(prefers-reduced-motion: reduce)").matches;
+function syncMeta(){const dark=r.dataset.theme!=="light";
+let single=document.querySelector('meta[name="theme-color"]:not([media])');
+if(!single){single=document.createElement("meta");single.name="theme-color";document.head.appendChild(single)}
+single.content=dark?"#000000":"#ffffff"}
+function paint(){const t=document.getElementById("themeBtn");
+if(t){t.textContent=r.dataset.theme==="dark"?"\u263E":"\u2600"}}
+function setTheme(n){r.dataset.theme=n;
+try{localStorage.setItem("acm-theme",n)}catch(e){}paint();syncMeta()}
+const tb=document.getElementById("themeBtn");
+if(tb){tb.addEventListener("click",function(){
+const n=r.dataset.theme==="dark"?"light":"dark";
+if(document.startViewTransition&&!reduced){document.startViewTransition(function(){setTheme(n)})}
+else{setTheme(n)}})}
+paint();syncMeta();
+const panel=document.getElementById("mpanel"),menu=document.getElementById("menuBtn");
+function openM(o){if(!panel){return}panel.classList.toggle("open",o);
+document.body.style.overflow=o?"hidden":""}
+if(menu&&panel){menu.addEventListener("click",function(){openM(!panel.classList.contains("open"))})}
+if(panel){panel.addEventListener("click",function(e){
+if(e.target.closest("[data-close]")||e.target===panel){openM(false)}})}
+addEventListener("keydown",function(e){if(e.key==="Escape"){openM(false)}});
+const here=(location.pathname.split("/").pop()||"index.html").toLowerCase().split("?")[0];
+function mark(a){const h=(a.getAttribute("href")||"").toLowerCase().replace("./","");
+a.classList.toggle("on",h===here||(here===""&&h==="index.html"))}
+document.querySelectorAll(".tabs a").forEach(mark);
+document.querySelectorAll(".msheet a[data-nav]").forEach(mark);
+const nav=document.querySelector(".nav");
+addEventListener("scroll",function(){if(nav){nav.classList.toggle("scrolled",(scrollY||0)>8)}},{passive:true});
+document.querySelectorAll(".card,.fnode").forEach(function(c){
+c.addEventListener("pointermove",function(e){
+const b=c.getBoundingClientRect();
+c.style.setProperty("--fx",((e.clientX-b.left)/b.width*100)+"%");
+c.style.setProperty("--fy",((e.clientY-b.top)/b.height*100)+"%")},{passive:true})});
+document.querySelectorAll("[data-copy]").forEach(function(btn){
+btn.addEventListener("click",function(){
+const pre=btn.parentElement.querySelector("pre");if(!pre){return}
+const done=function(t){btn.textContent=t;setTimeout(function(){btn.textContent="Copy"},1400)};
+if(navigator.clipboard&&navigator.clipboard.writeText){
+navigator.clipboard.writeText(pre.innerText).then(function(){done("Copied")},function(){done("Select + Ctrl+C")})}
+else{done("Select + Ctrl+C")}})});
+document.querySelectorAll(".ctabs").forEach(function(g){
+const btns=Array.prototype.slice.call(g.querySelectorAll("button"));
+btns.forEach(function(b){b.addEventListener("click",function(){
+btns.forEach(function(x){x.classList.remove("on")});b.classList.add("on");
+const id=b.getAttribute("data-tab");if(!id||!g.parentElement){return}
+const panes=g.parentElement.querySelectorAll("[data-pane]");
+panes.forEach(function(p){p.hidden=p.getAttribute("data-pane")!==id})})})});
+const yr=document.getElementById("yr");if(yr){yr.textContent=new Date().getFullYear()}
+const hasGsap=(typeof gsap!=="undefined")&&(typeof ScrollTrigger!=="undefined");
+if(!hasGsap||reduced){r.classList.add("no-gsap");
+const els=document.querySelectorAll(".reveal");
+if(!("IntersectionObserver" in window)){els.forEach(function(e){e.classList.add("in")})}
+else{const io=new IntersectionObserver(function(es){
+es.forEach(function(en){if(en.isIntersecting){en.target.classList.add("in");io.unobserve(en.target)}})},{threshold:.1});
+els.forEach(function(e){io.observe(e)})}}
+if(hasGsap&&!reduced){try{
+r.style.scrollBehavior="auto";
+gsap.registerPlugin(ScrollTrigger);
+gsap.from(".hero-in > *",{y:26,opacity:0,duration:.8,stagger:.09,ease:"power3.out",clearProps:"all"});
+gsap.utils.toArray(".reveal").forEach(function(el){
+if(el.matches(".grid3 .card")){return}
+gsap.fromTo(el,{y:24,opacity:0},{y:0,opacity:1,duration:.7,ease:"power3.out",
+scrollTrigger:{trigger:el,start:"top 88%",once:true}})});
+const batchCards=gsap.utils.toArray(".grid3 .card");
+if(batchCards.length){gsap.set(batchCards,{y:28,opacity:0});
+ScrollTrigger.batch(batchCards,{start:"top 88%",once:true,interval:.1,batchMax:3,
+onEnter:function(batch){gsap.to(batch,{y:0,opacity:1,duration:.7,
+ease:"power3.out",stagger:.12,overwrite:true})}});}
+document.querySelectorAll(".stat b[data-count]").forEach(function(b){
+const end=parseFloat(b.getAttribute("data-count"));const o={v:0};
+function tick(){b.textContent=Math.round(o.v).toLocaleString("en-US")}
+function play(){gsap.to(o,{v:end,duration:1.4,ease:"power2.out",onUpdate:tick})}
+ScrollTrigger.create({trigger:b,start:"top 92%",once:true,onEnter:play});
+});
+addEventListener("load",function(){ScrollTrigger.refresh()});
+}catch(err){r.classList.add("no-gsap")}}
+(function(){if(reduced){return}
+const cv=document.createElement("canvas");cv.id="bg-net";cv.setAttribute("aria-hidden","true");
+document.body.prepend(cv);const cx=cv.getContext("2d");
+let W=0,H=0,pts=[],run=true,mx=-999,my=-999;
+const dark=function(){return r.dataset.theme!=="light"};
+function fit(){const d=Math.min(devicePixelRatio||1,1.5);
+W=innerWidth;H=innerHeight;cv.width=W*d;cv.height=H*d;
+cv.style.width=W+"px";cv.style.height=H+"px";cx.setTransform(d,0,0,d,0,0);
+const n=Math.min(90,(W*H/22000)|0);pts=[];
+for(let i=0;i<n;i++){pts.push({x:Math.random()*W,y:Math.random()*H,
+vx:(Math.random()-.5)*.35,vy:(Math.random()-.5)*.35})}}
+addEventListener("resize",fit,{passive:true});fit();
+addEventListener("pointermove",function(e){mx=e.clientX;my=e.clientY},{passive:true});
+new IntersectionObserver(function(es){run=es[0].isIntersecting},{threshold:0}).observe(cv);
+document.addEventListener("visibilitychange",function(){run=!document.hidden});
+(function frame(){requestAnimationFrame(frame);
+if(!run||document.hidden){return}
+cx.clearRect(0,0,W,H);
+const mono=dark()?"255,255,255":"0,0,0";
+for(const p of pts){p.x+=p.vx;p.y+=p.vy;
+if(p.x<0||p.x>W){p.vx*=-1}if(p.y<0||p.y>H){p.vy*=-1}}
+for(let i=0;i<pts.length;i++){const a=pts[i];
+for(let j=i+1;j<pts.length;j++){const b=pts[j];
+const dx=a.x-b.x,dy=a.y-b.y,d=dx*dx+dy*dy;
+if(d<150*150){cx.strokeStyle="rgba("+mono+","+(0.10*(1-d/22500)).toFixed(3)+")";
+cx.lineWidth=1;cx.beginPath();cx.moveTo(a.x,a.y);cx.lineTo(b.x,b.y);cx.stroke()}}}
+for(const p of pts){const dm=(p.x-mx)*(p.x-mx)+(p.y-my)*(p.y-my);
+const glow=dm<120*120?0.5:0.22;
+cx.fillStyle="rgba("+mono+","+glow.toFixed(2)+")";
+cx.beginPath();cx.arc(p.x,p.y,dm<120*120?1.8:1.2,0,6.283);cx.fill()}})();
 })();
+const prog=document.getElementById("progress"),topBtn=document.getElementById("toTop");
+function onPos(){const h=document.documentElement;
+const max=h.scrollHeight-h.clientHeight;
+const p=max>0?(h.scrollTop||document.body.scrollTop)/max:0;
+if(prog){prog.style.transform="scaleX("+p+")"}
+if(topBtn){topBtn.classList.toggle("show",(h.scrollTop||0)>600)}}
+addEventListener("scroll",onPos,{passive:true});onPos();
+if(topBtn){topBtn.addEventListener("click",function(){
+scrollTo({top:0,behavior:reduced?"auto":"smooth"})})}
+if(hasGsap&&!reduced){try{
+gsap.to(".hero-in",{yPercent:-10,autoAlpha:.25,ease:"none",
+scrollTrigger:{trigger:".hero",start:"top top",end:"bottom top",scrub:true}});
+gsap.utils.toArray(".flow").forEach(function(f){
+const items=f.querySelectorAll(".fnode");
+if(items.length){gsap.fromTo(items,{y:34,autoAlpha:0},
+{y:0,autoAlpha:1,duration:.6,stagger:.18,ease:"power3.out",
+scrollTrigger:{trigger:f,start:"top 82%",once:true}})}});
+}catch(err){}}
+const fine=matchMedia("(pointer:fine)").matches;
+if(fine&&!reduced){
+const dot=document.createElement("div");dot.id="cursor";dot.setAttribute("aria-hidden","true");
+const ring=document.createElement("div");ring.id="aura";ring.setAttribute("aria-hidden","true");
+document.body.append(dot,ring);
+let x=innerWidth/2,y=innerHeight/2,rx=x,ry=y,sc=1,tsc=1;
+addEventListener("pointermove",function(e){x=e.clientX;y=e.clientY;
+const t=e.target.closest?e.target.closest("a,button,.card,.fnode"):null;
+tsc=t?2.1:1},{passive:true});
+(function loop(){rx+=(x-rx)*.16;ry+=(y-ry)*.16;sc+=(tsc-sc)*.2;
+dot.style.transform="translate("+x+"px,"+y+"px)";
+ring.style.transform="translate("+rx+"px,"+ry+"px) scale("+sc.toFixed(3)+")";
+requestAnimationFrame(loop)})();
+const hasG=typeof gsap!=="undefined";
+document.querySelectorAll(".hero .btn").forEach(function(b){
+const qx=hasG?gsap.quickTo(b,"x",{duration:.3,ease:"power3"}):null;
+const qy=hasG?gsap.quickTo(b,"y",{duration:.3,ease:"power3"}):null;
+b.addEventListener("pointermove",function(e){
+if(!qx||!qy){return}
+const bb=b.getBoundingClientRect();
+qx((e.clientX-(bb.left+bb.width/2))*.25);
+qy((e.clientY-(bb.top+bb.height/2))*.25)});
+b.addEventListener("pointerleave",function(){if(qx&&qy){qx(0);qy(0)}})});
+document.querySelectorAll(".hero .btn").forEach(function(b){
+if(b.querySelector(".ch")){return}
+const txt=b.textContent;b.setAttribute("aria-label",txt);b.textContent="";
+Array.prototype.forEach.call(txt,function(ch){
+const s=document.createElement("span");s.className="ch";s.setAttribute("aria-hidden","true");
+s.textContent=ch===" "?" ":ch;b.appendChild(s)});
+b.addEventListener("mouseenter",function(){
+if(!hasG){return}
+gsap.fromTo(b.querySelectorAll(".ch"),{y:0},
+{y:-5,duration:.13,ease:"power2.out",stagger:{each:.018,yoyo:true,repeat:1},overwrite:"auto"})})});
+const heroEl=document.querySelector(".hero"),statsEl=document.querySelector(".hero .stats");
+if(heroEl&&statsEl){statsEl.style.transformStyle="preserve-3d";
+heroEl.addEventListener("pointermove",function(e){
+const bb=statsEl.getBoundingClientRect();
+const px=(e.clientX-bb.left)/bb.width-.5,py=(e.clientY-bb.top)/bb.height-.5;
+statsEl.style.transform="perspective(800px) rotateX("+(-py*7).toFixed(2)+"deg) rotateY("+(px*9).toFixed(2)+"deg)"},{passive:true});
+heroEl.addEventListener("pointerleave",function(){
+statsEl.style.transform="perspective(800px)"})}
+let lastY=scrollY||0;
+addEventListener("scroll",function(){
+const yy=scrollY||0;
+if(!(panel&&panel.classList.contains("open"))){
+if(yy>140&&yy>lastY+4&&nav){nav.classList.add("hide")}
+else if((yy<lastY-4||yy<140)&&nav){nav.classList.remove("hide")}}
+lastY=yy},{passive:true});
 }
 })();