@hegemonart/get-design-done 1.51.0 → 1.52.0

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();

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

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+// scripts/lib/design-context/extract-tokens.mjs — Phase 52 (DesignContext graph), executor B.
+//
+// Deterministic, dependency-free token extractor. Regex-scans source roots for
+// design tokens (color / spacing / typography / radius / shadow) and emits a
+// Fragment (schema_version 52.0) to stdout. The structural pass fills
+// id/type/name/subtype + `uses-token` edges (component -> token, where a
+// component file references a token value); the LLM/mapper phase fills
+// summary/tags/complexity later — so summary defaults to '' and complexity to
+// 'moderate' (the validator soft-warns on these stubs).
+//
+// Idiom mirrors scripts/lib/detect/engine.cjs walk(): dep-free fs recursion
+// with a SKIP_DIRS set, scannable-extension filter, regex content scan. No
+// network, no optional deps, no top-level Date.now() (stamped only in main()).
+//
+// Public API:
+//   extract(roots, opts?) -> Fragment   (pure; opts.generatedAt to stamp)
+//   main()                              -> prints Fragment JSON to stdout
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const MAPPER = 'token-mapper';
+const SCHEMA_VERSION = '52.0';
+
+const SCANNABLE_EXT = new Set([
+  '.css', '.scss', '.sass', '.less',
+  '.tsx', '.jsx', '.ts', '.js', '.mjs', '.cjs',
+  '.vue', '.svelte', '.html', '.htm',
+]);
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', '.next', 'coverage',
+  '.design', '.planning', 'out', '.cache', '.turbo', '.svelte-kit',
+]);
+
+// A file is treated as a "component" file (a `uses-token` edge source) when it
+// is a component-bearing extension. CSS/SCSS are token *definition* surfaces,
+// not components, so they never originate `uses-token` edges.
+const COMPONENT_EXT = new Set(['.tsx', '.jsx', '.vue', '.svelte']);
+
+/** Recursively collect scannable files under `root` (a file or dir). */
+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;
+}
+
+/** Slugify an arbitrary token value/name into an id-safe fragment. */
+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: '',          // LLM phase fills this
+    tags: [],
+    complexity: 'moderate', // LLM phase refines this
+    ...extra,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Token matchers. Each returns { subtype, name, value } objects per match.
+// ---------------------------------------------------------------------------
+
+const HEX = /#[0-9a-fA-F]{3,8}\b/g;
+const FUNC_COLOR = /\b(?:rgb|rgba|hsl|hsla|oklch|oklab|lab|lch|color)\([^)]*\)/g;
+const CSS_VAR_DEF = /(--[a-z][a-z0-9-]*)\s*:\s*([^;}\n]+)/gi;
+const TW_COLOR = /\b(?:bg|text|border|ring|fill|stroke|from|to|via)-(?:slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-\d{2,3}\b/g;
+
+const SPACING_DECL = /\b(?:padding|margin|gap|inset|top|right|bottom|left|row-gap|column-gap)(?:-[a-z]+)?\s*:\s*(-?[0-9]*\.?[0-9]+(?:px|rem|em))\b/gi;
+const TW_SPACING = /\b(?:p|m|gap|space|inset)(?:[xytrbl])?-(?:px|0|0\.5|\d{1,2}(?:\.5)?)\b/g;
+
+const FONT_SIZE = /font-size\s*:\s*([0-9]*\.?[0-9]+(?:px|rem|em))/gi;
+const FONT_WEIGHT = /font-weight\s*:\s*([1-9]00|normal|bold|bolder|lighter)\b/gi;
+const FONT_FAMILY = /font-family\s*:\s*([^;}\n]+)/gi;
+const TW_TEXT = /\btext-(?:xs|sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|8xl|9xl)\b/g;
+const TW_FONTWEIGHT = /\bfont-(?:thin|extralight|light|normal|medium|semibold|bold|extrabold|black)\b/g;
+
+const RADIUS_DECL = /border-radius\s*:\s*([0-9]*\.?[0-9]+(?:px|rem|em|%)|9999px|50%)/gi;
+const TW_RADIUS = /\brounded(?:-(?:none|sm|md|lg|xl|2xl|3xl|full))?\b/g;
+
+const SHADOW_DECL = /box-shadow\s*:\s*([^;}\n]+)/gi;
+const TW_SHADOW = /\bshadow(?:-(?:sm|md|lg|xl|2xl|inner|none))?\b/g;
+
+function collect(re, content, mapFn) {
+  const out = [];
+  re.lastIndex = 0;
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    const t = mapFn(m);
+    if (t) out.push(t);
+    if (m.index === re.lastIndex) re.lastIndex++; // guard zero-width
+  }
+  return out;
+}
+
+/** Extract every token reference from one file's content (subtype-tagged). */
+function tokensInContent(content, ext) {
+  const found = [];
+  const isStyle = ext === '.css' || ext === '.scss' || ext === '.sass' || ext === '.less';
+
+  // --- color ---
+  // CSS custom properties whose value is colorish → name them by the var.
+  for (const m of collect(CSS_VAR_DEF, content, (mm) => mm)) {
+    const [, varName, rawVal] = m;
+    const val = rawVal.trim();
+    if (/#[0-9a-fA-F]{3,8}\b|\b(?:rgb|rgba|hsl|hsla|oklch|oklab|lab|lch)\(/.test(val)) {
+      found.push({ subtype: 'color', name: varName, value: val });
+    } else if (/(?:px|rem|em)\b/.test(val) && /^(?:[0-9.]+(?:px|rem|em)\s*)+$/.test(val)) {
+      found.push({ subtype: 'spacing', name: varName, value: val });
+    } else if (/(?:[0-9]{3}|bold|normal)/.test(val) && /font|weight|size/i.test(varName)) {
+      found.push({ subtype: 'typography', name: varName, value: val });
+    }
+  }
+  for (const v of collect(HEX, content, (mm) => mm[0])) found.push({ subtype: 'color', name: v, value: v });
+  for (const v of collect(FUNC_COLOR, content, (mm) => mm[0])) found.push({ subtype: 'color', name: v, value: v });
+  for (const v of collect(TW_COLOR, content, (mm) => mm[0])) found.push({ subtype: 'color', name: v, value: v });
+
+  // --- spacing ---
+  for (const m of collect(SPACING_DECL, content, (mm) => mm)) found.push({ subtype: 'spacing', name: m[1], value: m[1] });
+  for (const v of collect(TW_SPACING, content, (mm) => mm[0])) found.push({ subtype: 'spacing', name: v, value: v });
+
+  // --- typography ---
+  for (const m of collect(FONT_SIZE, content, (mm) => mm)) found.push({ subtype: 'typography', name: m[1], value: m[1] });
+  for (const m of collect(FONT_WEIGHT, content, (mm) => mm)) found.push({ subtype: 'typography', name: `weight-${m[1]}`, value: m[1] });
+  for (const m of collect(FONT_FAMILY, content, (mm) => mm)) found.push({ subtype: 'typography', name: m[1].trim().split(',')[0].replace(/['"]/g, ''), value: m[1].trim() });
+  for (const v of collect(TW_TEXT, content, (mm) => mm[0])) found.push({ subtype: 'typography', name: v, value: v });
+  for (const v of collect(TW_FONTWEIGHT, content, (mm) => mm[0])) found.push({ subtype: 'typography', name: v, value: v });
+
+  // --- radius ---
+  for (const m of collect(RADIUS_DECL, content, (mm) => mm)) found.push({ subtype: 'radius', name: m[1], value: m[1] });
+  for (const v of collect(TW_RADIUS, content, (mm) => mm[0])) found.push({ subtype: 'radius', name: v, value: v });
+
+  // --- shadow ---
+  for (const m of collect(SHADOW_DECL, content, (mm) => mm)) found.push({ subtype: 'shadow', name: m[1].trim().slice(0, 40), value: m[1].trim() });
+  for (const v of collect(TW_SHADOW, content, (mm) => mm[0])) found.push({ subtype: 'shadow', name: v, value: v });
+
+  // Suppress raw-utility noise in pure style files is unnecessary; dedupe by id
+  // happens at the fragment level. `isStyle` retained for future weighting.
+  void isStyle;
+  return found;
+}
+
+/**
+ * Pure extractor.
+ * @param {string[]|string} roots  one or more file/dir roots
+ * @param {{generatedAt?: string}} [opts]
+ * @returns {{schema_version:string, mapper:string, generated_at:string, nodes:object[], edges:object[]}}
+ */
+export function extract(roots, opts = {}) {
+  const rootList = (Array.isArray(roots) ? roots : [roots]).filter(Boolean);
+  const nodeMap = new Map();   // id -> node
+  const edgeSet = new Map();   // edgeKey -> edge (dedupe)
+
+  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 hits = tokensInContent(content, ext);
+      if (!hits.length) continue;
+
+      // Component-file id (only for `uses-token` edge origin).
+      const compId = COMPONENT_EXT.has(ext)
+        ? `component:${slug(path.basename(abs, ext))}`
+        : null;
+
+      for (const h of hits) {
+        const id = `token:${h.subtype}:${slug(h.name)}`;
+        if (!nodeMap.has(id)) {
+          nodeMap.set(id, stubNode(id, 'token', h.name, { subtype: h.subtype, value: h.value }));
+        }
+        if (compId) {
+          const key = `${compId}->${id}`;
+          if (!edgeSet.has(key)) {
+            edgeSet.set(key, {
+              source: compId,
+              target: id,
+              type: 'uses-token',
+              direction: 'forward',
+              weight: 0.5,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  return {
+    schema_version: SCHEMA_VERSION,
+    mapper: MAPPER,
+    generated_at: opts.generatedAt || '',
+    nodes: [...nodeMap.values()],
+    edges: [...edgeSet.values()],
+  };
+}
+
+/** CLI entry: roots from argv (default cwd), stamp generated_at, print JSON. */
+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');
+}
+
+// ESM "run as script" guard (Windows + POSIX safe via pathToFileURL).
+const invokedDirectly =
+  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) main();

package/scripts/lib/design-context/extract-visual-hierarchy.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+// scripts/lib/design-context/extract-visual-hierarchy.mjs — Phase 52, executor B.
+//
+// Deterministic, dependency-free visual-hierarchy extractor. Regex-scans source
+// for heading structure (<h1>..<h6>), type-scale steps (Tailwind text-* + CSS
+// font-size), focal/hero weight signals, and layout patterns (flex/grid/
+// F-/Z-/centered), and emits a Fragment (schema_version 52.0) of `layer` +
+// `pattern` nodes with `composes` edges (heading-level layer -> next deeper
+// level, capturing the document outline) and `referenced-by` edges
+// (component file -> pattern it exhibits).
+//
+// Semantics mirror agents/visual-hierarchy-mapper.md (headings / type-scale /
+// focal weight / layout patterns). 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 = 'visual-hierarchy-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 };
+}
+
+// ---------------------------------------------------------------------------
+// Visual-hierarchy matchers.
+// ---------------------------------------------------------------------------
+
+const HEADING = /<h([1-6])\b/g;
+const TW_TEXT_SCALE = /\btext-(xs|sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|8xl|9xl)\b/g;
+const CSS_FONTSIZE = /font-size\s*:\s*([0-9.]+(?:px|rem|em))/gi;
+const HERO = /\b(?:hero|headline|display-[a-z0-9]+|page-title|page-heading)\b/g;
+const LAYOUT = /\b(?:justify-(?:center|between|around|evenly)|items-center|grid-template|grid-cols-\d+|flex-(?:row|col)|flex-direction)\b/g;
+const CENTERED = /\b(?:mx-auto|justify-center|items-center|place-items-center|text-center)\b/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 != 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 headingLevels = new Set();      // numeric levels seen (1..6) across corpus
+  const typeScaleSteps = new Set();     // text-* scale steps seen
+
+  const addNode = (id, type, name, extra) => {
+    if (!nodeMap.has(id)) nodeMap.set(id, stubNode(id, type, 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 });
+  };
+
+  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)}`;
+
+      // Heading levels -> layer nodes (one per level seen).
+      for (const lvl of collect(HEADING, content, (m) => Number(m[1]))) {
+        headingLevels.add(lvl);
+        addNode(`layer:heading-h${lvl}`, 'layer', `Heading level h${lvl}`, { subtype: 'Template', level: lvl });
+      }
+
+      // Type-scale steps -> pattern nodes (the scale vocabulary in use).
+      for (const step of collect(TW_TEXT_SCALE, content, (m) => m[1])) {
+        typeScaleSteps.add(step);
+        addNode(`pattern:type-scale-${slug(step)}`, 'pattern', `Type scale: text-${step}`, { step });
+      }
+      for (const size of collect(CSS_FONTSIZE, content, (m) => m[1])) {
+        addNode(`pattern:type-scale-${slug(size)}`, 'pattern', `Type scale: ${size}`, { size });
+      }
+
+      // Focal / hero signals -> pattern node + referenced-by from the file.
+      if ((content.match(HERO) || []).length) {
+        const pid = addNode('pattern:focal-hero', 'pattern', 'Focal/hero emphasis', {});
+        addEdge(compId, pid, 'referenced-by', 0.5);
+      }
+
+      // Layout patterns.
+      if ((content.match(CENTERED) || []).length) {
+        const pid = addNode('pattern:layout-centered-column', 'pattern', 'Centered column layout', {});
+        addEdge(compId, pid, 'referenced-by', 0.4);
+      } else if ((content.match(LAYOUT) || []).length) {
+        const pid = addNode('pattern:layout-flow', 'pattern', 'Flex/grid flow layout', {});
+        addEdge(compId, pid, 'referenced-by', 0.4);
+      }
+    }
+  }
+
+  // composes edges: connect each heading level to the next-deeper one present,
+  // capturing the document-outline shape (h1 composes h2 composes h3 ...).
+  const sortedLevels = [...headingLevels].sort((a, b) => a - b);
+  for (let i = 0; i < sortedLevels.length - 1; i++) {
+    const src = `layer:heading-h${sortedLevels[i]}`;
+    const dst = `layer:heading-h${sortedLevels[i + 1]}`;
+    addEdge(src, dst, 'composes', 0.5);
+  }
+
+  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();