@hegemonart/get-design-done 1.51.0 → 1.53.0

package/scripts/lib/design-context/extract-a11y.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+// scripts/lib/design-context/extract-a11y.mjs — Phase 52 (DesignContext graph), executor B.
+//
+// Deterministic, dependency-free accessibility extractor. Regex-scans source
+// for ARIA attributes, role=, keyboard handlers, focus states, semantic
+// landmarks, skip links, and image alt coverage, and emits a Fragment
+// (schema_version 52.0) of `a11y-pattern` nodes with `documented-by` /
+// `referenced-by` edges:
+//   - component file --referenced-by--> a11y-pattern  (the file exhibits the pattern)
+//   - a11y-pattern --documented-by--> wcag:<criterion> node  (when a known pattern
+//     maps to a WCAG criterion we recognize)
+//
+// Semantics mirror agents/a11y-mapper.md (ARIA / keyboard / focus / landmarks /
+// alt). Static-only — no live browser. Structural pass: summary='' and
+// complexity='moderate' are stubs the LLM/mapper phase fills later. No network,
+// no deps, no top-level Date.now() (stamped in main()).
+//
+// Public API:
+//   extract(roots, opts?) -> Fragment   (pure)
+//   main()                              -> prints Fragment JSON to stdout
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const MAPPER = 'a11y-mapper';
+const SCHEMA_VERSION = '52.0';
+
+const SCANNABLE_EXT = new Set([
+  '.tsx', '.jsx', '.ts', '.js',
+  '.vue', '.svelte', '.html', '.htm',
+  '.css', '.scss',
+]);
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', '.next', 'coverage',
+  '.design', '.planning', 'out', '.cache', '.turbo', '.svelte-kit',
+]);
+
+function walk(root) {
+  const out = [];
+  let st;
+  try { st = fs.statSync(root); } catch { return out; }
+  if (st.isFile()) {
+    if (SCANNABLE_EXT.has(path.extname(root).toLowerCase())) out.push(root);
+    return out;
+  }
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) { if (!SKIP_DIRS.has(e.name)) stack.push(full); }
+      else if (e.isFile() && SCANNABLE_EXT.has(path.extname(e.name).toLowerCase())) out.push(full);
+    }
+  }
+  return out;
+}
+
+function slug(s) {
+  return String(s).trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'x';
+}
+function stubNode(id, type, name, extra) {
+  return { id, type, name, summary: '', tags: [], complexity: 'moderate', ...extra };
+}
+
+// ---------------------------------------------------------------------------
+// A11y matchers + WCAG mapping.
+// ---------------------------------------------------------------------------
+
+const ARIA_ATTR = /\baria-([a-z]+)\s*=/g;
+const ROLE_ATTR = /\brole\s*=\s*["']([a-z]+)["']/g;
+const KEYBOARD = /\b(?:tabIndex|tabindex|onKeyDown|onKeyPress|onKeyUp|on:keydown)\b/g;
+const FOCUS_STATE = /:focus(?:-visible)?|focus-visible:|focus:/g;
+const LANDMARK = /<(header|nav|main|section|article|aside|footer)\b/g;
+const SKIP_LINK = /(?:skip-nav|skip-to-content|skip-link|#main-content)/g;
+const IMG_TAG = /<img\b[^>]*>/gi;
+
+// pattern-id -> WCAG criterion it satisfies/relates to.
+const WCAG_FOR_PATTERN = {
+  'aria-attributes': '4.1.2',
+  'role-semantics': '4.1.2',
+  'keyboard-support': '2.1.1',
+  'focus-visible': '2.4.7',
+  'semantic-landmarks': '1.3.1',
+  'skip-link': '2.4.1',
+  'image-alt': '1.1.1',
+};
+
+function collect(re, content, mapFn) {
+  const out = [];
+  re.lastIndex = 0;
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    const v = mapFn(m);
+    if (v != null) out.push(v);
+    if (m.index === re.lastIndex) re.lastIndex++;
+  }
+  return out;
+}
+
+/**
+ * Pure extractor.
+ * @param {string[]|string} roots
+ * @param {{generatedAt?: string}} [opts]
+ * @returns {object} Fragment
+ */
+export function extract(roots, opts = {}) {
+  const rootList = (Array.isArray(roots) ? roots : [roots]).filter(Boolean);
+  const nodeMap = new Map();
+  const edgeSet = new Map();
+
+  const addPattern = (patternId, name, extra) => {
+    const id = `a11y-pattern:${patternId}`;
+    if (!nodeMap.has(id)) nodeMap.set(id, stubNode(id, 'a11y-pattern', name, extra || {}));
+    return id;
+  };
+  const addEdge = (source, target, type, weight) => {
+    const key = `${source}--${type}-->${target}`;
+    if (!edgeSet.has(key)) edgeSet.set(key, { source, target, type, direction: 'forward', weight });
+  };
+  // a11y-pattern --documented-by--> wcag criterion node.
+  const linkWcag = (patternKey, patternNodeId) => {
+    const crit = WCAG_FOR_PATTERN[patternKey];
+    if (!crit) return;
+    const wid = `pattern:wcag-${slug(crit)}`;
+    if (!nodeMap.has(wid)) nodeMap.set(wid, stubNode(wid, 'pattern', `WCAG ${crit}`, { criterion: crit }));
+    addEdge(patternNodeId, wid, 'documented-by', 0.8);
+  };
+
+  for (const root of rootList) {
+    for (const abs of walk(root)) {
+      let content;
+      try { content = fs.readFileSync(abs, 'utf8'); } catch { continue; }
+      const ext = path.extname(abs).toLowerCase();
+      const baseName = path.basename(abs, ext);
+      const compId = `component:${slug(baseName)}`;
+
+      // Detect each pattern family present in this file.
+      const aria = collect(ARIA_ATTR, content, (m) => m[1]);
+      const roles = collect(ROLE_ATTR, content, (m) => m[1]);
+      const kbd = (content.match(KEYBOARD) || []).length;
+      const focus = (content.match(FOCUS_STATE) || []).length;
+      const landmarks = collect(LANDMARK, content, (m) => m[1]);
+      const skip = (content.match(SKIP_LINK) || []).length;
+      const imgs = collect(IMG_TAG, content, (m) => m[0]);
+
+      const families = [];
+      if (aria.length) families.push(['aria-attributes', 'ARIA attributes', { attributes: [...new Set(aria)].slice(0, 12) }]);
+      if (roles.length) families.push(['role-semantics', 'ARIA role semantics', { roles: [...new Set(roles)].slice(0, 12) }]);
+      if (kbd) families.push(['keyboard-support', 'Keyboard navigation', {}]);
+      if (focus) families.push(['focus-visible', 'Focus-visible states', {}]);
+      if (landmarks.length) families.push(['semantic-landmarks', 'Semantic landmarks', { landmarks: [...new Set(landmarks)] }]);
+      if (skip) families.push(['skip-link', 'Skip link', {}]);
+      if (imgs.length) {
+        const withAlt = imgs.filter((t) => /\balt\s*=/.test(t)).length;
+        families.push(['image-alt', 'Image alt coverage', { images: imgs.length, with_alt: withAlt }]);
+      }
+
+      for (const [key, name, extra] of families) {
+        const pid = addPattern(key, name, extra);
+        // The file *references* the a11y pattern.
+        addEdge(compId, pid, 'referenced-by', 0.5);
+        // The pattern is *documented-by* the WCAG criterion.
+        linkWcag(key, pid);
+      }
+    }
+  }
+
+  return {
+    schema_version: SCHEMA_VERSION,
+    mapper: MAPPER,
+    generated_at: opts.generatedAt || '',
+    nodes: [...nodeMap.values()],
+    edges: [...edgeSet.values()],
+  };
+}
+
+export function main(argv = process.argv.slice(2)) {
+  const roots = argv.length ? argv : [process.cwd()];
+  const fragment = extract(roots, { generatedAt: new Date().toISOString() });
+  process.stdout.write(JSON.stringify(fragment, null, 2) + '\n');
+}
+
+const invokedDirectly =
+  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) main();

package/scripts/lib/design-context/extract-components.mjs

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+// scripts/lib/design-context/extract-components.mjs — Phase 52 (DesignContext graph), executor B.
+//
+// Deterministic, dependency-free component extractor. Regex-scans component
+// files (.tsx/.jsx/.vue/.svelte) for component definitions/exports, classifies
+// each as Atomic / Molecular / Organism via import + composition heuristics, and
+// emits a Fragment (schema_version 52.0) of `component` + `variant` + `layer`
+// nodes with `composes` / `extends` edges.
+//
+// Heuristics (mirrors agents/component-taxonomy-mapper.md semantics):
+//   - Atomic    : composes 0 other detected components
+//   - Molecular  : composes 1-4 other detected components
+//   - Organism  : composes 5+ OR is route/page-shaped (Page/Screen/Layout/View name)
+// A `variant` node is emitted when a `variant`/`size`/`intent` prop union or a
+// cva()/tv() variants block is detected; the variant `extends` its component.
+// A `layer` node (subtype Atomic/Molecular/Organism) is emitted per distinct
+// layer and the component `composes`... is captured component->component.
+//
+// Structural pass only: summary='' and complexity='moderate' are stubs the
+// LLM/mapper phase fills later (validator soft-warns). No network, no deps, no
+// top-level Date.now() (stamped in main()).
+//
+// Public API:
+//   extract(roots, opts?) -> Fragment   (pure)
+//   main()                              -> prints Fragment JSON to stdout
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const MAPPER = 'component-taxonomy-mapper';
+const SCHEMA_VERSION = '52.0';
+
+const COMPONENT_EXT = new Set(['.tsx', '.jsx', '.vue', '.svelte']);
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', '.next', 'coverage',
+  '.design', '.planning', 'out', '.cache', '.turbo', '.svelte-kit',
+]);
+
+const ORGANISM_NAME = /(Page|Screen|Layout|View|Dashboard|Shell|Provider)$/;
+
+/** Recursively collect component files under `root`. */
+function walk(root) {
+  const out = [];
+  let st;
+  try { st = fs.statSync(root); } catch { return out; }
+  if (st.isFile()) {
+    if (COMPONENT_EXT.has(path.extname(root).toLowerCase())) out.push(root);
+    return out;
+  }
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) { if (!SKIP_DIRS.has(e.name)) stack.push(full); }
+      else if (e.isFile() && COMPONENT_EXT.has(path.extname(e.name).toLowerCase())) out.push(full);
+    }
+  }
+  return out;
+}
+
+function slug(s) {
+  return String(s).trim().replace(/[^A-Za-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'x';
+}
+
+// Canonical component id — lowercased so it MATCHES the file-basename-derived
+// `component:<basename>` ids produced by the token / a11y / visual-hierarchy
+// extractors. Component identity is case-insensitive across the graph so that a
+// `referenced-by` edge from a11y (which only knows the filename) recovers
+// against the `component` node defined here (which knows the export name).
+// Cross-fragment edge recovery in merge-fragments.mjs depends on this.
+function componentId(name) {
+  return `component:${slug(name).toLowerCase()}`;
+}
+
+function stubNode(id, type, name, extra) {
+  return { id, type, name, summary: '', tags: [], complexity: 'moderate', ...extra };
+}
+
+// ---------------------------------------------------------------------------
+// Component detection.
+// ---------------------------------------------------------------------------
+
+// React/TS component definitions: function decl, arrow const, class, default export.
+const DEF_FN = /(?:export\s+(?:default\s+)?)?function\s+([A-Z][A-Za-z0-9]*)\s*\(/g;
+const DEF_ARROW = /(?:export\s+)?const\s+([A-Z][A-Za-z0-9]*)\s*(?::\s*[A-Za-z0-9_.<>,\s]+)?=\s*(?:\([^)]*\)|[A-Za-z0-9_]+)\s*=>/g;
+const DEF_CLASS = /(?:export\s+(?:default\s+)?)?class\s+([A-Z][A-Za-z0-9]*)\s+extends\s+(?:React\.)?(?:Pure)?Component\b/g;
+const DEF_MEMO = /(?:export\s+)?const\s+([A-Z][A-Za-z0-9]*)\s*=\s*(?:React\.)?(?:memo|forwardRef)\s*\(/g;
+
+// JSX usage of a capitalized tag → a composed child component.
+const JSX_USE = /<([A-Z][A-Za-z0-9]*)[\s/>]/g;
+
+// Variant signals.
+const VARIANT_PROP = /\b(?:variant|intent|size|tone|appearance|kind)\??\s*:\s*([^;\n}]+)/g;
+const CVA_BLOCK = /\b(?:cva|tv|cssVariants)\s*\(/g;
+
+function collect(re, content, mapFn) {
+  const out = [];
+  re.lastIndex = 0;
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    const v = mapFn(m);
+    if (v) out.push(v);
+    if (m.index === re.lastIndex) re.lastIndex++;
+  }
+  return out;
+}
+
+/** Detect component definitions in one file. Returns array of names. */
+function definedComponents(content, ext, baseName) {
+  const names = new Set();
+  if (ext === '.tsx' || ext === '.jsx') {
+    for (const n of collect(DEF_FN, content, (m) => m[1])) names.add(n);
+    for (const n of collect(DEF_ARROW, content, (m) => m[1])) names.add(n);
+    for (const n of collect(DEF_CLASS, content, (m) => m[1])) names.add(n);
+    for (const n of collect(DEF_MEMO, content, (m) => m[1])) names.add(n);
+  }
+  // Vue/Svelte (and React fallback): the file itself is a component named by
+  // its basename when nothing else was detected.
+  if (!names.size && /^[A-Z]/.test(baseName)) names.add(baseName);
+  else if (ext === '.vue' || ext === '.svelte') names.add(baseName);
+  return [...names];
+}
+
+/** Detect child components composed inside one file. */
+function composedChildren(content) {
+  const kids = new Set();
+  for (const n of collect(JSX_USE, content, (m) => m[1])) {
+    // Skip well-known intrinsic-ish wrappers that aren't design components.
+    if (n === 'Fragment' || n === 'Suspense' || n === 'StrictMode') continue;
+    kids.add(n);
+  }
+  return kids;
+}
+
+function classifyLayer(name, childCount) {
+  if (ORGANISM_NAME.test(name) || childCount >= 5) return 'Organism';
+  if (childCount >= 1) return 'Molecular';
+  return 'Atomic';
+}
+
+/**
+ * Pure extractor.
+ * @param {string[]|string} roots
+ * @param {{generatedAt?: string}} [opts]
+ * @returns {object} Fragment
+ */
+export function extract(roots, opts = {}) {
+  const rootList = (Array.isArray(roots) ? roots : [roots]).filter(Boolean);
+  const nodeMap = new Map();
+  const edgeSet = new Map();
+  const layerSeen = new Set();
+
+  // Pass 1: collect every defined component name (across files) so composes
+  // edges only point at components we actually saw defined somewhere.
+  const fileInfos = [];
+  const definedGlobal = new Set();
+  for (const root of rootList) {
+    for (const abs of walk(root)) {
+      let content;
+      try { content = fs.readFileSync(abs, 'utf8'); } catch { continue; }
+      const ext = path.extname(abs).toLowerCase();
+      const baseName = path.basename(abs, ext);
+      const defs = definedComponents(content, ext, baseName);
+      const kids = composedChildren(content);
+      const hasCva = CVA_BLOCK.test(content) || VARIANT_PROP.test(content);
+      // reset lastIndex side effects of .test on global regexes
+      CVA_BLOCK.lastIndex = 0; VARIANT_PROP.lastIndex = 0;
+      defs.forEach((d) => definedGlobal.add(d));
+      fileInfos.push({ defs, kids, hasCva });
+    }
+  }
+
+  // Pass 2: build nodes + edges.
+  for (const { defs, kids, hasCva } of fileInfos) {
+    for (const name of defs) {
+      const id = componentId(name);
+      // Children that are themselves defined components (drop self + unknown).
+      const realKids = [...kids].filter((k) => k !== name && definedGlobal.has(k));
+      const layer = classifyLayer(name, realKids.length);
+
+      if (!nodeMap.has(id)) {
+        nodeMap.set(id, stubNode(id, 'component', name, { layer }));
+      } else {
+        // Prefer the more-specific (higher) layer if seen twice.
+        const order = { Atomic: 0, Molecular: 1, Organism: 2 };
+        const prev = nodeMap.get(id);
+        if (order[layer] > order[prev.layer]) prev.layer = layer;
+      }
+
+      // layer node (one per distinct layer) + component depends-on-layer is
+      // implicit via the `layer` field; we emit the layer node so the graph has
+      // a navigable taxonomy anchor.
+      const layerId = `layer:${layer}`;
+      if (!layerSeen.has(layerId)) {
+        layerSeen.add(layerId);
+        nodeMap.set(layerId, stubNode(layerId, 'layer', `${layer} layer`, { subtype: layer }));
+      }
+
+      // composes edges: component -> child component.
+      for (const k of realKids) {
+        const childId = componentId(k);
+        const key = `${id}--composes-->${childId}`;
+        if (!edgeSet.has(key)) {
+          edgeSet.set(key, { source: id, target: childId, type: 'composes', direction: 'forward', weight: 0.6 });
+        }
+      }
+
+      // variant node + extends edge.
+      if (hasCva) {
+        const variantId = `variant:${slug(name).toLowerCase()}`;
+        if (!nodeMap.has(variantId)) {
+          nodeMap.set(variantId, stubNode(variantId, 'variant', `${name} (variants)`, {}));
+        }
+        const vkey = `${variantId}--extends-->${id}`;
+        if (!edgeSet.has(vkey)) {
+          edgeSet.set(vkey, { source: variantId, target: id, type: 'extends', direction: 'forward', weight: 0.7 });
+        }
+      }
+    }
+  }
+
+  return {
+    schema_version: SCHEMA_VERSION,
+    mapper: MAPPER,
+    generated_at: opts.generatedAt || '',
+    nodes: [...nodeMap.values()],
+    edges: [...edgeSet.values()],
+  };
+}
+
+export function main(argv = process.argv.slice(2)) {
+  const roots = argv.length ? argv : [process.cwd()];
+  const fragment = extract(roots, { generatedAt: new Date().toISOString() });
+  process.stdout.write(JSON.stringify(fragment, null, 2) + '\n');
+}
+
+const invokedDirectly =
+  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) main();

package/scripts/lib/design-context/extract-motion.mjs

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+// scripts/lib/design-context/extract-motion.mjs — Phase 52 (DesignContext graph), executor B.
+//
+// Deterministic, dependency-free motion extractor. Regex-scans source for CSS
+// transitions / @keyframes / animations, Tailwind motion utilities, and JS
+// libs (framer-motion, GSAP) plus easing tokens, and emits a Fragment
+// (schema_version 52.0) of `motion-fragment` + `state` nodes with
+// `transitions-to` edges (state -> state for keyframe-style enter/exit pairs and
+// for AnimatePresence enter/exit; otherwise the motion-fragment links the two
+// canonical states it animates between).
+//
+// Semantics mirror agents/motion-mapper.md (easing / duration / trigger /
+// library). Structural pass only: summary='' and complexity='moderate' are
+// stubs the LLM/mapper phase fills later. No network, no deps, no top-level
+// Date.now() (stamped in main()).
+//
+// Public API:
+//   extract(roots, opts?) -> Fragment   (pure)
+//   main()                              -> prints Fragment JSON to stdout
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const MAPPER = 'motion-mapper';
+const SCHEMA_VERSION = '52.0';
+
+const SCANNABLE_EXT = new Set([
+  '.css', '.scss', '.sass', '.less',
+  '.tsx', '.jsx', '.ts', '.js', '.mjs',
+  '.vue', '.svelte', '.html', '.htm',
+]);
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', '.next', 'coverage',
+  '.design', '.planning', 'out', '.cache', '.turbo', '.svelte-kit',
+]);
+
+function walk(root) {
+  const out = [];
+  let st;
+  try { st = fs.statSync(root); } catch { return out; }
+  if (st.isFile()) {
+    if (SCANNABLE_EXT.has(path.extname(root).toLowerCase())) out.push(root);
+    return out;
+  }
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) { if (!SKIP_DIRS.has(e.name)) stack.push(full); }
+      else if (e.isFile() && SCANNABLE_EXT.has(path.extname(e.name).toLowerCase())) out.push(full);
+    }
+  }
+  return out;
+}
+
+function slug(s) {
+  return String(s).trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'x';
+}
+function stubNode(id, type, name, extra) {
+  return { id, type, name, summary: '', tags: [], complexity: 'moderate', ...extra };
+}
+
+// ---------------------------------------------------------------------------
+// Motion matchers.
+// ---------------------------------------------------------------------------
+
+const KEYFRAMES = /@keyframes\s+([A-Za-z0-9_-]+)/g;
+const CSS_TRANSITION = /transition\s*:\s*([^;}\n]+)/gi;
+const CSS_ANIMATION = /\banimation\s*:\s*([^;}\n]+)/gi;
+const TW_MOTION = /\b(?:animate-[a-z-]+|duration-\d+|ease-(?:linear|in|out|in-out)|transition(?:-[a-z]+)?)\b/g;
+const FRAMER = /\b(?:framer-motion|motion\.(?:div|span|button|ul|li|a|section|nav|header|footer)|useAnimation|useSpring|useTransform|whileHover|whileTap|AnimatePresence|layoutId)\b/g;
+const GSAP = /\b(?:gsap|TweenMax|TimelineMax)\.(?:to|from|fromTo|timeline)\b/g;
+const EASING = /cubic-bezier\(([^)]+)\)/g;
+const REDUCED_MOTION = /prefers-reduced-motion/g;
+
+// Trigger heuristics.
+function triggerFor(content, snippet) {
+  if (/whileHover|:hover/.test(snippet)) return 'hover';
+  if (/whileTap|:active|onClick|onPress/.test(snippet)) return 'press';
+  if (/useScroll|animation-timeline|ScrollTimeline|whileInView/.test(content)) return 'scroll';
+  if (/AnimatePresence|exit=|mount|unmount/.test(content)) return 'mount-unmount';
+  return 'state-change';
+}
+
+function collect(re, content, mapFn) {
+  const out = [];
+  re.lastIndex = 0;
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    const v = mapFn(m);
+    if (v) out.push(v);
+    if (m.index === re.lastIndex) re.lastIndex++;
+  }
+  return out;
+}
+
+/**
+ * Pure extractor.
+ * @param {string[]|string} roots
+ * @param {{generatedAt?: string}} [opts]
+ * @returns {object} Fragment
+ */
+export function extract(roots, opts = {}) {
+  const rootList = (Array.isArray(roots) ? roots : [roots]).filter(Boolean);
+  const nodeMap = new Map();
+  const edgeSet = new Map();
+
+  const addState = (name) => {
+    const id = `state:${slug(name)}`;
+    if (!nodeMap.has(id)) nodeMap.set(id, stubNode(id, 'state', name, {}));
+    return id;
+  };
+  const addEdge = (source, target, type, weight) => {
+    const key = `${source}--${type}-->${target}`;
+    if (!edgeSet.has(key)) edgeSet.set(key, { source, target, type, direction: 'forward', weight });
+  };
+
+  for (const root of rootList) {
+    for (const abs of walk(root)) {
+      let content;
+      try { content = fs.readFileSync(abs, 'utf8'); } catch { continue; }
+      const ext = path.extname(abs).toLowerCase();
+      const baseName = path.basename(abs, ext);
+      const reducedMotion = (content.match(REDUCED_MOTION) || []).length > 0;
+
+      // @keyframes -> motion-fragment + an idle->active transition pair.
+      for (const kf of collect(KEYFRAMES, content, (m) => m[1])) {
+        const id = `motion-fragment:${slug(kf)}`;
+        if (!nodeMap.has(id)) {
+          nodeMap.set(id, stubNode(id, 'motion-fragment', kf, {
+            library: 'css-keyframes',
+            trigger: triggerFor(content, kf),
+            reduced_motion_handled: reducedMotion,
+          }));
+        }
+        const idle = addState(`${kf}-idle`);
+        const active = addState(`${kf}-active`);
+        addEdge(idle, active, 'transitions-to', 0.6);
+      }
+
+      // CSS transition decls -> a motion-fragment named by file+property.
+      const transitions = collect(CSS_TRANSITION, content, (m) => m[1].trim());
+      transitions.forEach((decl, i) => {
+        const prop = decl.split(/\s+/)[0] || 'all';
+        const id = `motion-fragment:${slug(baseName)}-transition-${slug(prop)}-${i}`;
+        if (!nodeMap.has(id)) {
+          nodeMap.set(id, stubNode(id, 'motion-fragment', `${baseName} transition (${prop})`, {
+            library: 'css',
+            trigger: triggerFor(content, decl),
+            reduced_motion_handled: reducedMotion,
+          }));
+        }
+      });
+
+      // CSS animation shorthand -> motion-fragment.
+      collect(CSS_ANIMATION, content, (m) => m[1].trim()).forEach((decl, i) => {
+        const id = `motion-fragment:${slug(baseName)}-animation-${i}`;
+        if (!nodeMap.has(id)) {
+          nodeMap.set(id, stubNode(id, 'motion-fragment', `${baseName} animation`, {
+            library: 'css',
+            trigger: triggerFor(content, decl),
+            reduced_motion_handled: reducedMotion,
+          }));
+        }
+      });
+
+      // Framer-motion usage -> motion-fragment + (if AnimatePresence) enter/exit states.
+      const framerHits = (content.match(FRAMER) || []);
+      if (framerHits.length) {
+        const id = `motion-fragment:${slug(baseName)}-framer`;
+        if (!nodeMap.has(id)) {
+          nodeMap.set(id, stubNode(id, 'motion-fragment', `${baseName} (framer-motion)`, {
+            library: 'framer-motion',
+            trigger: triggerFor(content, content),
+            reduced_motion_handled: reducedMotion,
+          }));
+        }
+        if (/AnimatePresence/.test(content)) {
+          const enter = addState(`${baseName}-enter`);
+          const exit = addState(`${baseName}-exit`);
+          addEdge(enter, exit, 'transitions-to', 0.7);
+        }
+      }
+
+      // GSAP usage -> motion-fragment.
+      if ((content.match(GSAP) || []).length) {
+        const id = `motion-fragment:${slug(baseName)}-gsap`;
+        if (!nodeMap.has(id)) {
+          nodeMap.set(id, stubNode(id, 'motion-fragment', `${baseName} (gsap)`, {
+            library: 'gsap',
+            trigger: triggerFor(content, content),
+            reduced_motion_handled: reducedMotion,
+          }));
+        }
+      }
+
+      // Tailwind motion utilities -> a single motion-fragment per file (low
+      // weight). Skip pure stylesheets: bare `transition` there is plain CSS,
+      // already captured by CSS_TRANSITION above (avoids a duplicate node).
+      const isStyle = ext === '.css' || ext === '.scss' || ext === '.sass' || ext === '.less';
+      if (!isStyle && (content.match(TW_MOTION) || []).length) {
+        const id = `motion-fragment:${slug(baseName)}-tw`;
+        if (!nodeMap.has(id)) {
+          nodeMap.set(id, stubNode(id, 'motion-fragment', `${baseName} (tailwind motion)`, {
+            library: 'tailwind',
+            trigger: triggerFor(content, content),
+            reduced_motion_handled: reducedMotion,
+          }));
+        }
+      }
+
+      // Easing tokens -> tag onto a per-file easing motion-fragment (informational).
+      const easings = collect(EASING, content, (m) => m[1].trim());
+      if (easings.length) {
+        const id = `motion-fragment:${slug(baseName)}-easing`;
+        if (!nodeMap.has(id)) {
+          nodeMap.set(id, stubNode(id, 'motion-fragment', `${baseName} easing`, {
+            library: 'easing',
+            easings: easings.slice(0, 8),
+            reduced_motion_handled: reducedMotion,
+          }));
+        }
+      }
+    }
+  }
+
+  return {
+    schema_version: SCHEMA_VERSION,
+    mapper: MAPPER,
+    generated_at: opts.generatedAt || '',
+    nodes: [...nodeMap.values()],
+    edges: [...edgeSet.values()],
+  };
+}
+
+export function main(argv = process.argv.slice(2)) {
+  const roots = argv.length ? argv : [process.cwd()];
+  const fragment = extract(roots, { generatedAt: new Date().toISOString() });
+  process.stdout.write(JSON.stringify(fragment, null, 2) + '\n');
+}
+
+const invokedDirectly =
+  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) main();