@moonarc/mcp 0.1.0

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@moonarc/mcp",
+  "version": "0.1.0",
+  "description": "MCP server and CI CLI for Moonarc: search the catalogue by intent and byte budget, read a component's craft notes and source, get the install command; with a Pro key, audit motion in your codebase, measure per-route JS of your build, and compose sections.",
+  "type": "module",
+  "license": "MIT",
+  "author": "azriPtr",
+  "homepage": "https://moonarc.dev/mcp/",
+  "keywords": [
+    "astro",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "animation",
+    "motion",
+    "components",
+    "claude-code",
+    "cursor"
+  ],
+  "bin": {
+    "moonarc-mcp": "./bin/moonarc.js",
+    "moonarc": "./bin/moonarc.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "catalog.json",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/server.js",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.0",
+    "zod": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build:catalog": "node scripts/build-catalog.mjs",
+    "test": "node scripts/build-catalog.mjs && node scripts/smoke.mjs && node scripts/test.mjs"
+  }
+}

package/src/audit.js

@@ -0,0 +1,365 @@
+/**
+ * audit_motion: findings against the critique rubric, on the user's own
+ * files. Static, deterministic, line-accurate. Runs forever on evolving code,
+ * which is what makes it worth a subscription; cannot be copy-pasted.
+ *
+ * Each rule reads one view of a file, so prose is never a finding: the style
+ * sheets (a .css file, <style> blocks, style="" attributes, a script's css``
+ * and styled`` templates), the scripts with their comments blanked (a .js/.ts
+ * file, <script> blocks), or the markup. An .astro file's frontmatter runs on
+ * the server and is in none of them. Every view keeps each character where it
+ * was, so a finding's line is the source line.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { extname, join, relative } from 'node:path';
+
+const EXT = new Set(['.astro', '.css', '.scss', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.svelte', '.vue', '.html']);
+const SKIP = new Set(['node_modules', 'dist', '.astro', '.git', '.output', 'build', '.vercel', '.netlify']);
+const SCRIPT_EXT = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs']);
+
+/** @typedef {{ rule: string, severity: 'error'|'warn'|'info', file: string, line: number, message: string, fix: string, excerpt: string }} Finding */
+
+const LAYOUT_PROPS = /\b(width|height|top|left|right|bottom|margin(?:-[a-z]+)?|padding(?:-[a-z]+)?|inset(?:-[a-z]+)?|font-size|line-height|border-width)\b/;
+/** A property name that is not the end of a longer one: `transition` but not `--my-transition`. */
+const prop = (name) => `(?<![\\w-])${name}`;
+
+// ---------- views ----------
+
+const blankRange = (chars, from, to) => { for (let k = from; k < to; k++) if (chars[k] !== '\n') chars[k] = ' '; };
+const blankOf = (text) => text.replace(/[^\n]/g, ' ');
+
+/** A style sheet with its comments blanked (block comments, and SCSS line comments). */
+function cssText(src, scss = false) {
+  let out = src.replace(/\/\*[\s\S]*?(?:\*\/|$)/g, blankOf);
+  if (scss) out = out.replace(/(^|[\s;{}])(\/\/[^\n]*)/g, (_, pre, c) => pre + blankOf(c));
+  return out;
+}
+
+const REGEX_AFTER = /(?:^|[^\w$])(?:return|typeof|case|do|else|in|of|void|yield|await|delete|instanceof|new|throw)$/;
+/** The tag of a CSS-in-JS template literal (styled-components, Emotion, Lit): an untagged template is text, often prose. */
+const CSS_TAG = /(?:^|[^\w$.])(?:css|keyframes|createGlobalStyle|injectGlobal|styled(?:\.[\w$]+|\([^()]*\))(?:\.attrs\([^()]*\))?)\s*$/;
+/**
+ * A script with its comments blanked (`code`), and a copy with everything blanked but the text of its CSS template
+ * literals (`tpl`). A regular-expression literal is told from a division by what precedes it, well enough for a line
+ * audit.
+ */
+function scriptText(src) {
+  const code = src.split('');
+  const tpl = blankOf(src).split('');
+  const braces = [];
+  let depth = 0;
+  let i = 0;
+  let css = false;
+  const regexAllowed = () => {
+    let k = i - 1;
+    while (k >= 0 && /\s/.test(code[k])) k--;
+    if (k < 0) return true;
+    if ('(,=:[!&|?{};+-*%<>~^'.includes(code[k])) return true;
+    return /[\w$]/.test(code[k]) && REGEX_AFTER.test(code.slice(Math.max(0, k - 11), k + 1).join(''));
+  };
+  // i is just past a backtick, or past the } that closes a ${…}: read the literal up to its end or its next ${, and copy
+  // its text into tpl when it is CSS
+  const template = () => {
+    while (i < src.length) {
+      const c = src[i];
+      if (c === '\\') { if (css) { tpl[i] = c; if (i + 1 < src.length && src[i + 1] !== '\n') tpl[i + 1] = src[i + 1]; } i += 2; continue; }
+      if (c === '`') { i++; return; }
+      if (c === '$' && src[i + 1] === '{') { braces.push({ depth, css }); depth++; i += 2; return; }
+      if (css && c !== '\n') tpl[i] = c;
+      i++;
+    }
+  };
+  while (i < src.length) {
+    const c = src[i];
+    if (c === '/' && src[i + 1] === '/') { const e = src.indexOf('\n', i); const end = e < 0 ? src.length : e; blankRange(code, i, end); i = end; continue; }
+    if (c === '/' && src[i + 1] === '*') { const e = src.indexOf('*/', i + 2); const end = e < 0 ? src.length : e + 2; blankRange(code, i, end); i = end; continue; }
+    if (c === '"' || c === "'") { i++; while (i < src.length && src[i] !== c && src[i] !== '\n') i += src[i] === '\\' ? 2 : 1; i++; continue; }
+    if (c === '`') { css = CSS_TAG.test(src.slice(Math.max(0, i - 60), i)); i++; template(); continue; }
+    if (c === '/' && regexAllowed()) {
+      i++;
+      let cls = false;
+      while (i < src.length && src[i] !== '\n') {
+        const d = src[i];
+        if (d === '\\') { i += 2; continue; }
+        if (d === '[') cls = true;
+        else if (d === ']') cls = false;
+        else if (d === '/' && !cls) break;
+        i++;
+      }
+      i++;
+      while (i < src.length && /[a-z]/i.test(src[i])) i++;
+      continue;
+    }
+    if (c === '{') depth++;
+    else if (c === '}') {
+      depth--;
+      if (braces.length && braces.at(-1).depth === depth) { ({ css } = braces.pop()); i++; template(); continue; }
+    }
+    i++;
+  }
+  return { code: code.join(''), tpl: tpl.join('') };
+}
+
+const RUNS_AS_SCRIPT = /^(?:module|(?:text|application)\/(?:x-)?(?:java|ecma)script|text\/babel)$/i;
+
+/** The views of one file: `css`, `code` and `markup`, each as long as the file. */
+function views(file, text) {
+  const ext = extname(file);
+  if (ext === '.css' || ext === '.scss') return { css: cssText(text, ext === '.scss'), code: blankOf(text), markup: blankOf(text) };
+  if (SCRIPT_EXT.has(ext)) { const s = scriptText(text); return { css: cssText(s.tpl), code: s.code, markup: blankOf(text) }; }
+  const css = blankOf(text).split('');
+  const code = blankOf(text).split('');
+  const markup = text.split('');
+  const put = (chars, at, s) => { for (let k = 0; k < s.length; k++) if (s[k] !== '\n') chars[at + k] = s[k]; };
+  // text that is neither markup nor a block: an .astro frontmatter (server code) and HTML comments
+  const dead = [];
+  if (ext === '.astro') { const m = text.match(/^\s*---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?=\r?\n|$)/); if (m) dead.push([0, m[0].length]); }
+  for (const m of text.matchAll(/<!--[\s\S]*?(?:-->|$)/g)) dead.push([m.index, m.index + m[0].length]);
+  const isDead = (at) => dead.some(([a, b]) => at >= a && at < b);
+  for (const [a, b] of dead) blankRange(markup, a, b);
+  for (const m of text.matchAll(/<(style|script)\b((?:[^>"']|"[^"]*"|'[^']*')*)>([\s\S]*?)<\/\1\s*>/gi)) {
+    if (isDead(m.index)) continue;
+    const start = m.index + m[0].length - m[3].length - `</${m[1]}>`.length - (m[0].match(/<\/\w+(\s*)>$/)?.[1].length ?? 0);
+    blankRange(markup, start, start + m[3].length);
+    if (m[1].toLowerCase() === 'style') { put(css, start, cssText(m[3], /\blang=["']?scss/.test(m[2]))); continue; }
+    const type = m[2].match(/(?:^|\s)type\s*=\s*["']?([^"'\s>]+)/i)?.[1];
+    if (type && !RUNS_AS_SCRIPT.test(type)) continue; // JSON, JSON-LD, an import map: data
+    const s = scriptText(m[3]);
+    put(code, start, s.code);
+    put(css, start, cssText(s.tpl));
+  }
+  // inline styles: the value of each style="" attribute left in the markup
+  const live = markup.join('');
+  for (const m of live.matchAll(/\sstyle\s*=\s*(?:"([^"]*)"|'([^']*)')/g)) {
+    const value = m[1] ?? m[2];
+    put(css, m.index + m[0].length - value.length - 1, value);
+  }
+  return { css: css.join(''), code: code.join(''), markup: live };
+}
+
+/**
+ * Every { } block of a style sheet: where its prelude starts, where it opens and closes, and `own`, the text between
+ * its braces with each nested block (prelude and body) blanked and ended with a `;`, so its own declarations stand
+ * alone. The last entry is the sheet's top level (style="" values live there).
+ */
+function blocksOf(css) {
+  const out = [];
+  const stack = [{ open: -1, prelude: 0, seg: 0, nested: [] }];
+  let quote = null;
+  for (let i = 0; i < css.length; i++) {
+    const c = css[i];
+    // a CSS string ends at its quote, or at the end of the line (an unclosed one)
+    if (quote) { if (c === '\\') i++; else if (c === quote || c === '\n') quote = null; continue; }
+    if (c === '"' || c === "'") { quote = c; continue; }
+    const top = stack.at(-1);
+    if (c === ';') top.seg = i + 1;
+    else if (c === '{') stack.push({ open: i, prelude: top.seg, seg: i + 1, nested: [] });
+    else if (c === '}' && stack.length > 1) {
+      const b = stack.pop();
+      const parent = stack.at(-1);
+      parent.nested.push([b.prelude, i]);
+      parent.seg = i + 1;
+      out.push({ ...b, close: i });
+    }
+  }
+  out.push({ ...stack[0], open: -1, close: css.length });
+  for (const b of out) {
+    const own = css.slice(b.open + 1, b.close).split('');
+    for (const [s, e] of b.nested) { blankRange(own, s - b.open - 1, e - b.open); own[e - b.open - 1] = ';'; }
+    b.own = own.join('');
+    b.selector = b.open < 0 ? '' : css.slice(b.prelude, b.open).trim();
+  }
+  return out;
+}
+
+/** The innermost block around a position of the sheet. */
+const blockAt = (blocks, at) => blocks.filter((b) => b.open < at && at < b.close).reduce((a, b) => (b.open > a.open ? b : a), blocks.at(-1));
+/** A declaration of the block itself (not of a nested rule): `name:` at its start or after a `;`. */
+const declares = (b, name) => new RegExp(`(?:^|;)\\s*${name}\\s*:\\s*(?!none\\b)[^;\\s]`).test(b.own);
+const KEYFRAME_STEP = /^(?:from|to|\d+(?:\.\d+)?%)(?:\s*,\s*(?:from|to|\d+(?:\.\d+)?%))*$/;
+const STATE = /:(?:hover|active|focus|focus-visible|focus-within|checked)\b|\[(?:open|aria-[\w-]+|data-[\w-]+)[^\]]*\]|\.is-[\w-]+/;
+
+const lineAt = (text, at) => text.slice(0, at).split('\n').length;
+/** The first character at or after `at` that is not white space: where a prelude's text starts. */
+const firstChar = (text, at) => { while (at < text.length && /\s/.test(text[at])) at++; return at; };
+/** Top-level commas only: `var(--a, 1s)` keeps its comma. */
+const splitList = (s) => { const out = []; let depth = 0; let cur = ''; for (const c of s) { if (c === '(') depth++; else if (c === ')') depth--; if (c === ',' && depth === 0) { out.push(cur); cur = ''; } else cur += c; } out.push(cur); return out; };
+
+// ---------- rules ----------
+
+/** A rule tested line by line on one view: `test` returns the message or null. */
+const perLine = (view, test) => (v, file) => v[view].split('\n').flatMap((l, i, lines) => { const msg = test(l, { file, lines, i, v }); return msg ? [{ line: i + 1, message: msg }] : []; });
+
+/** @type {{ id: string, severity: Finding['severity'], run: (v: { css: string, code: string, markup: string, raw: string, blocks: any[] }, file: string) => { line: number, message: string }[], fix: string }[]} */
+const RULES = [
+  {
+    id: 'transition-all',
+    severity: 'error',
+    fix: 'Name the properties: `transition: transform 200ms var(--ease-out), opacity 200ms var(--ease-out)`. `all` animates layout properties and repaints every frame.',
+    run: perLine('css', (l) => (new RegExp(`${prop('transition(?:-property)?')}\\s*:\\s*all\\b`).test(l) ? '`transition: all` animates every property, including layout' : null)),
+  },
+  {
+    id: 'layout-transition',
+    // a warning: an accordion's height or a divider's left can be the right call, and only a person can tell
+    severity: 'warn',
+    fix: 'Animate `transform`, `opacity`, `clip-path` or `filter` instead; for size changes animate `scale` or use a grid-rows trick, for position use `translate`.',
+    run: perLine('css', (l) => {
+      const m = l.match(new RegExp(`${prop('transition(?:-property)?')}\\s*:\\s*([^;}{]+)`));
+      if (!m) return null;
+      const props = splitList(m[1]).map((p) => p.trim().split(/\s+/)[0]).filter((p) => p && !p.startsWith('--') && !p.startsWith('var('));
+      const bad = props.filter((p) => LAYOUT_PROPS.test(p));
+      return bad.length ? `transitions a layout property (${bad.join(', ')}): the browser lays out and paints every frame` : null;
+    }),
+  },
+  {
+    id: 'layout-keyframes',
+    severity: 'warn',
+    fix: 'Move the motion to `transform`/`translate`/`scale`/`opacity`. Keyframes on layout properties run on the main thread.',
+    // once per @keyframes rule, at its first step that moves a layout property
+    run: (v) => v.blocks.filter((k) => /^@(?:-\w+-)?keyframes\b/.test(k.selector)).flatMap((k) => {
+      for (const b of v.blocks.filter((b) => b.open > k.open && b.close < k.close && KEYFRAME_STEP.test(b.selector)).sort((a, b) => a.open - b.open)) {
+        const m = b.own.match(/(?:^|;)\s*((?:min-|max-)?(?:width|height)|top|left|right|bottom|margin[\w-]*|padding[\w-]*)\s*:/);
+        if (m) return [{ line: lineAt(v.css, firstChar(v.css, b.prelude)), message: `keyframe animates ${m[1]}, a layout property` }];
+      }
+      return [];
+    }),
+  },
+  {
+    id: 'will-change-static',
+    severity: 'warn',
+    fix: '`will-change` is a loan: set it when the interaction starts and clear it when it ends (the runtime does this in Reveal). Left in a stylesheet it costs memory on every matching element, always. An element that animates for as long as the rule applies (an infinite or scroll-driven animation in the same rule) is the exception, and is not reported.',
+    run: (v) => [...v.css.matchAll(new RegExp(`${prop('will-change')}\\s*:\\s*(?!auto\\b)[a-z-]`, 'g'))].flatMap((m) => {
+      const b = blockAt(v.blocks, m.index);
+      if (STATE.test(b.selector) || declares(b, 'animation(?:-name)?')) return [];
+      return [{ line: lineAt(v.css, m.index), message: 'will-change declared permanently in CSS' }];
+    }),
+  },
+  {
+    id: 'blur-animated',
+    severity: 'warn',
+    fix: 'Animate the position or opacity of an already-blurred element instead of the blur radius; keep radii under ~8px when you must.',
+    run: (v) => {
+      if (!/\bblur\(/.test(v.css)) return [];
+      const out = [];
+      for (const m of v.css.matchAll(new RegExp(`${prop('transition(?:-property)?')}\\s*:[^;{}]*${prop('(?:backdrop-)?filter')}\\b`, 'g'))) out.push({ line: lineAt(v.css, m.index), message: 'transitioned blur() is re-rendered every frame' });
+      for (const b of v.blocks.filter((b) => KEYFRAME_STEP.test(b.selector))) {
+        const m = b.own.match(/(?:^|;)\s*(?:backdrop-)?filter\s*:[^;]*\bblur\(/);
+        if (m) out.push({ line: lineAt(v.css, b.open + 1 + m.index + m[0].search(/(?:backdrop-)?filter/)), message: 'keyframed blur() is re-rendered every frame' });
+      }
+      return out;
+    },
+  },
+  {
+    id: 'long-ui-duration',
+    severity: 'info',
+    fix: 'UI transitions (hover, press, open/close) read best at 100–300 ms; reserve 500+ ms for reveals beside content, never for something in front of the user\'s intent.',
+    run: perLine('css', (l) => {
+      const m = l.match(new RegExp(`${prop('transition(?:-duration)?')}\\s*:[^;]*?(\\d+(?:\\.\\d+)?)(ms|s)\\b`));
+      if (!m) return null;
+      const ms = m[2] === 's' ? Number(m[1]) * 1000 : Number(m[1]);
+      return ms > 600 ? `transition of ${ms} ms, long for a UI state change` : null;
+    }),
+  },
+  {
+    id: 'animation-timeline-shorthand',
+    severity: 'error',
+    fix: 'Put `animation-timeline` in a separate rule with different selector text. lightningcss folds it into the `animation` shorthand, which browsers reject, and the animation silently disappears in production.',
+    // the declaration only: `@supports (animation-timeline: view())` is a condition, and a nested rule is another rule
+    run: (v) => v.blocks.filter((b) => b.open >= 0 && /(?:^|;)\s*animation\s*:/.test(b.own)).flatMap((b) => [...b.own.matchAll(/(?:^|;)(\s*)animation-timeline\s*:/g)].map((m) => ({ line: lineAt(v.css, b.open + 1 + m.index + (m[0].startsWith(';') ? 1 : 0) + m[1].length), message: '`animation-timeline` in the same rule as the `animation` shorthand' }))),
+  },
+  {
+    id: 'no-reduced-motion',
+    severity: 'warn',
+    fix: 'Add a `@media (prefers-reduced-motion: reduce)` branch that keeps the fade and drops the travel, or read `prefersReducedMotion()` from the runtime in scripts.',
+    run: (v) => {
+      const animates = new RegExp(`@keyframes\\b|${prop('(?:animation|transition)(?:-name|-property)?')}\\s*:\\s*(?!none\\b)[^;\\s]`).test(v.css) || /\.animate\(\s*[[{]/.test(v.code);
+      return animates && !/prefers-reduced-motion|reduced-?motion|motion-(?:reduce|safe)/i.test(v.raw) ? [{ line: 1, message: 'file animates but has no reduced-motion branch' }] : [];
+    },
+  },
+  {
+    id: 'page-load-listener',
+    severity: 'error',
+    fix: 'Use `onMount`/`onPage` from `@moonarc/core/runtime`: `astro:page-load` does not fire without <ClientRouter />, can be skipped or doubled on back/forward, and needs a matching `astro:before-swap` teardown.',
+    run: (v) => (/astro:before-swap/.test(v.code) ? [] : perLine('code', (l) => (/addEventListener\(\s*['"`]astro:page-load['"`]/.test(l) ? '`astro:page-load` listener without an `astro:before-swap` teardown' : null))(v)),
+  },
+  {
+    id: 'single-instance-query',
+    severity: 'warn',
+    fix: 'Astro runs a component <script> once per page, not per instance. Use `querySelectorAll` and loop, or `onMount(selector, setup)` from the runtime.',
+    run: (v, file) => (/\.astro$/.test(file) ? perLine('code', (l) => (/^\s*(?:const|let|var)\s+\w+\s*=\s*document\.querySelector\(/.test(l) ? '`document.querySelector` in a component script binds only the first instance' : null))(v) : []),
+  },
+  {
+    id: 'define-vars-script',
+    severity: 'warn',
+    fix: 'Pass per-instance values as `data-*` attributes and read `el.dataset` in the script. `define:vars` on a <script> implies `is:inline`: no bundling, no imports, duplicated per instance.',
+    run: perLine('markup', (l) => (/<script\b[^>]*\bdefine:vars\b/.test(l) ? '`define:vars` on a <script>' : null)),
+  },
+  {
+    id: 'hover-not-gated',
+    severity: 'info',
+    fix: 'Wrap hover-only motion in `@media (hover: hover) and (pointer: fine)` so touch devices do not trigger it on tap.',
+    run: (v) => (/:hover\s*\{[^}]*(transform|translate|scale|animation)/.test(v.css.replace(/\n/g, ' ')) && !/hover:\s*hover/.test(v.raw) ? [{ line: 1, message: ':hover motion not gated on (hover: hover)' }] : []),
+  },
+  {
+    id: 'scale-zero',
+    severity: 'info',
+    fix: 'Use `scale(0.9–0.97)` with `opacity: 0`; scaling from zero reads as a pop, not an entrance.',
+    run: perLine('css', (l) => (new RegExp(`(?:${prop('transform')}\\s*:\\s*scale|${prop('scale')}\\s*:)\\s*\\(?\\s*0\\s*\\)?\\s*[;}]`).test(l) ? 'scale(0) entrance' : null)),
+  },
+];
+
+function* walk(dir) {
+  for (const f of readdirSync(dir)) {
+    if (SKIP.has(f)) continue;
+    const p = join(dir, f);
+    const st = statSync(p);
+    if (st.isDirectory()) yield* walk(p);
+    else if (EXT.has(extname(f))) yield p;
+  }
+}
+
+/**
+ * @param {string[]} paths files or directories
+ * @returns {{ files: number, findings: Finding[] }}
+ */
+export function audit(paths) {
+  const files = [];
+  for (const p of paths) {
+    let st;
+    try {
+      st = statSync(p);
+    } catch {
+      throw new Error(`No such file or folder: ${p}`);
+    }
+    if (st.isDirectory()) files.push(...walk(p));
+    else files.push(p);
+  }
+  const root = process.cwd();
+  /** @type {Finding[]} */
+  const findings = [];
+  for (const file of files) {
+    const raw = readFileSync(file, 'utf8');
+    const v = { ...views(file, raw), raw };
+    v.blocks = blocksOf(v.css);
+    const lines = raw.split('\n');
+    const rel = relative(root, file) || file;
+    for (const rule of RULES) {
+      for (const f of rule.run(v, file)) findings.push({ rule: rule.id, severity: rule.severity, file: rel, line: f.line, message: f.message, fix: rule.fix, excerpt: (lines[f.line - 1] ?? '').trim().slice(0, 120) });
+    }
+  }
+  const order = { error: 0, warn: 1, info: 2 };
+  findings.sort((a, b) => order[a.severity] - order[b.severity] || a.file.localeCompare(b.file) || a.line - b.line);
+  return { files: files.length, findings };
+}
+
+/** @param {{ files: number, findings: Finding[] }} r */
+export function formatAudit(r) {
+  if (r.findings.length === 0) return `moonarc audit · ${r.files} files · no findings`;
+  const by = (s) => r.findings.filter((f) => f.severity === s).length;
+  const head = `moonarc audit · ${r.files} files · ${by('error')} errors, ${by('warn')} warnings, ${by('info')} notes`;
+  const body = r.findings.map((f) => `  ${f.severity.padEnd(5)} ${f.file}:${f.line}  [${f.rule}] ${f.message}\n        ${f.excerpt}\n        → ${f.fix}`).join('\n\n');
+  return `${head}\n\n${body}`;
+}
+
+/** The rule ids, for tests that hold the count /pro states (13) against the code. */
+export const ruleIds = RULES.map((r) => r.id);

package/src/catalog.js

@@ -0,0 +1,186 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** @typedef {{ name: string, slug: string, title: string, description: string, category: string, tier: string, props: {name:string,type:string,default?:string,description:string}[], reducedMotion: string, clientRouter: string, craft: string[], related: string[], intents: string[], replaces: string[], source: string, cost: { js: {raw:number,gzip:number}, jsWithShared: {raw:number,gzip:number}, css: {raw:number,gzip:number}, dependsOn: string[] } | null, url: string }} Entry */
+/** @typedef {{ site: string, runtime: {raw:number,gzip:number}|null, chunks?: Record<string, {raw:number,gzip:number}>, components: Entry[] }} Catalog */
+
+let cached = null;
+
+/** What every tool reads of a catalogue: a site and components with names, slugs and props. A URL answering anything else is not used. */
+const usable = (c) => typeof c?.site === 'string' && Array.isArray(c.components) && c.components.length > 0 && c.components.every((e) => typeof e?.name === 'string' && typeof e.slug === 'string' && Array.isArray(e.props) && Array.isArray(e.intents));
+
+/**
+ * The bundled catalogue, or the one at MOONARC_CATALOG_URL: the same shape as catalog.json, served by a mirror or a
+ * test. A URL that fails, takes over 5 s or answers another shape leaves the bundled copy in charge, with a line on
+ * stderr (an MCP client shows the server's stderr in its log; stdout is the protocol).
+ * @returns {Promise<Catalog>}
+ */
+export async function loadCatalog() {
+  if (cached) return cached;
+  const url = process.env.MOONARC_CATALOG_URL;
+  if (url) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
+      if (!res.ok) throw new Error(`answered ${res.status}`);
+      const body = await res.json();
+      if (!usable(body)) throw new Error('answered something other than a catalogue');
+      return (cached = body);
+    } catch (err) {
+      console.error(`moonarc: MOONARC_CATALOG_URL ${err?.name === 'TimeoutError' ? 'gave no answer within 5 s' : err.message}; using the bundled catalogue`);
+    }
+  }
+  const path = join(dirname(fileURLToPath(import.meta.url)), '../catalog.json');
+  return (cached = JSON.parse(readFileSync(path, 'utf8')));
+}
+
+const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, '');
+
+/** One component by name or slug, in any case and spacing: Reveal, reveal, split-text, Split Text. */
+export function findComponent(cat, name) {
+  const key = norm(name);
+  return key ? cat.components.find((c) => norm(c.name) === key || norm(c.slug) === key) : undefined;
+}
+
+/**
+ * The names Rollup gives Moonarc's chunks in a build (Reveal, runtime, canvas, …), for measure_budget's share: the
+ * catalogue's `chunks` when build-catalog wrote them (every component and helper a fixture page loads, Pro included),
+ * else the components and what they depend on.
+ * @param {Catalog} cat
+ */
+export function libraryChunks(cat) {
+  if (cat.chunks) return new Set(Object.keys(cat.chunks));
+  return new Set(cat.components.flatMap((c) => [c.name, ...(c.cost?.dependsOn ?? [])]));
+}
+
+/** A byte figure with its unit, as the site prints it: "1.3 kB raw", "699 B gzip"; zero is "0 B" in either. */
+const fmt = (b, unit) => (b === 0 ? '0 B' : `${b < 1024 ? `${b} B` : `${(b / 1024).toFixed(1)} kB`} ${unit}`);
+
+/** @param {Entry} e */
+export function costLine(e) {
+  if (!e.cost) return 'not measured';
+  const deps = e.cost.dependsOn;
+  if (e.cost.js.raw === 0 && deps.length === 0) return '0 B JS';
+  if (e.cost.js.raw === 0) return `0 B JS of its own (uses ${deps.join(' + ')}; ${fmt(e.cost.jsWithShared.raw, 'raw')} with them)`;
+  return `${fmt(e.cost.js.raw, 'raw')} JS own (${fmt(e.cost.js.gzip, 'gzip')}), ${fmt(e.cost.jsWithShared.raw, 'raw')} with ${deps.join(' + ') || 'nothing'}`;
+}
+
+const BASELINE = { widely: 'Baseline widely available', newly: 'Baseline newly available', limited: 'limited availability' };
+/** @param {Entry} e */
+const supportText = (e) => `${e.supportLine} (${BASELINE[e.support.baseline] ?? e.support.baseline})${e.support.fallback ? `; elsewhere: ${e.support.fallback}` : ''}`;
+
+// Words that say nothing about which component is meant. Each field is matched word by word, so "in" never matches
+// "inline" and "text" never matches "context".
+const STOP = new Set('a an and any are as at be by can for from how i in into is it its like make me my need of on or our so some that the this to use want we with you your'.split(' '));
+/** Words, with a name split where its case changes: BlurText is "blur text", SVGIcon is "svg icon". */
+const words = (s) => s.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2').toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+/** One form per word: fade, fading and faded are fad; logos is logo; glasses is glass. */
+const stem = (w) => {
+  if (w.length <= 3) return w;
+  for (const s of ['ing', 'ed', 'es', 's', 'e']) if (w.endsWith(s) && w.length - s.length >= 3 && !(s === 's' && w.endsWith('ss'))) return w.slice(0, -s.length);
+  return w;
+};
+const terms = (s) => words(s).filter((w) => !STOP.has(w)).map(stem);
+const bag = (s) => [...new Set(terms(s))];
+/** Full weight for the word itself, half for a longer form of it (follow and follower, count and counter). */
+const weigh = (field, t, weight) => (field.includes(t) ? weight : field.some((w) => (t.length >= 4 && w.startsWith(t)) || (w.length >= 4 && t.startsWith(w))) ? weight / 2 : 0);
+
+const index = new WeakMap();
+/** @param {Entry} e */
+const fieldsOf = (e) => {
+  if (!index.has(e)) {
+    index.set(e, {
+      intents: bag(e.intents.join(' ')),
+      title: bag(`${e.title} ${e.name} ${e.slug}`),
+      replaces: bag(e.replaces.join(' ')),
+      description: bag(e.description),
+      category: bag(e.category),
+      trigger: bag((e.trigger ?? []).join(' ')),
+      phrases: [...e.intents, ...e.replaces].map((p) => words(p).join(' ')),
+    });
+  }
+  return index.get(e);
+};
+
+/**
+ * Every component that answers the intent, best first. Each word of the intent scores once per field it appears in
+ * (intents 4, title 3, what it replaces 3, category 2, description 1, trigger 1); a component that answers more of the
+ * words ranks above one that answers one word in many fields; the intent naming one of its intents or what it
+ * replaces, or a run of words inside one, adds more, and its exact name most. Ties go to the smaller script.
+ * @param {Entry[]} components @param {string} intent @param {{ maxJsBytes?: number, tier?: string }} [filters]
+ */
+export function search(components, intent, { maxJsBytes, tier } = {}) {
+  const q = [...new Set(terms(intent))];
+  const phrase = words(intent).join(' ');
+  const exact = norm(intent);
+  return components
+    .map((e) => {
+      const f = fieldsOf(e);
+      let score = 0;
+      let answered = 0;
+      for (const t of q) {
+        const s = weigh(f.intents, t, 4) + weigh(f.title, t, 3) + weigh(f.replaces, t, 3) + weigh(f.category, t, 2) + weigh(f.description, t, 1) + weigh(f.trigger, t, 1);
+        if (s) { score += s; answered++; }
+      }
+      if (q.length > 1) score += 3 * answered;
+      if (phrase && f.phrases.includes(phrase)) score += 12;
+      else if (phrase.includes(' ') && f.phrases.some((p) => ` ${phrase} `.includes(` ${p} `) || ` ${p} `.includes(` ${phrase} `))) score += 6;
+      if (exact && (exact === norm(e.name) || exact === norm(e.slug))) score += 20;
+      return { e, score };
+    })
+    .filter(({ e, score }) => score > 0 && (tier ? e.tier === tier : true) && (maxJsBytes != null ? (e.cost ? e.cost.js.raw <= maxJsBytes : true) : true))
+    .sort((a, b) => b.score - a.score || (a.e.cost?.js.raw ?? Infinity) - (b.e.cost?.js.raw ?? Infinity) || a.e.name.localeCompare(b.e.name))
+    .map(({ e }) => e);
+}
+
+/** @param {Entry} e */
+export function summary(e) {
+  return { name: e.name, slug: e.slug, title: e.title, description: e.description, category: e.category, tier: e.tier, trigger: e.trigger, readout: e.readout, cost: costLine(e), jsBytes: e.cost?.js.raw ?? null, support: supportText(e), page: e.url, markdown: `${e.url.replace(/\/$/, '')}.md` };
+}
+
+/** A Markdown table cell: a pipe would end the cell, inside code too (GitHub's table rules), and a newline the row. */
+const cell = (s) => String(s).replace(/\|/g, '\\|').replace(/\s*\n\s*/g, ' ');
+
+/** @param {Entry} e @param {{raw:number}|null} runtime */
+export function detail(e, runtime) {
+  const props = e.props.map((p) => `| \`${cell(p.name)}\` | \`${cell(p.type)}\` | ${p.default ? `\`${cell(p.default)}\`` : 'none'} | ${cell(p.description)} |`).join('\n');
+  return `# ${e.title}
+
+${e.description}
+
+Import: \`import ${e.name} from '@moonarc/core/${e.name}'\`
+Cost: ${costLine(e)}${runtime ? ` · shared runtime ${fmt(runtime.raw, 'raw')} once per site` : ''}
+Support: ${supportText(e)}
+Trigger: ${e.trigger.join(', ')}
+Page: ${e.url}
+
+## Usage
+
+\`\`\`astro
+${e.usage}
+\`\`\`
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+${props}
+
+## Reduced motion
+${e.reducedMotion}
+
+## With ClientRouter
+${e.clientRouter}
+
+## Craft: repeat these decisions, do not re-derive them
+${e.craft.map((c) => `- ${c}`).join('\n')}
+
+## Replaces
+${e.replaces.map((r) => `- ${r}`).join('\n')}
+
+## Source (\`${e.name}.astro\`)
+\`\`\`astro
+${e.source}
+\`\`\`
+`;
+}