@hegemonart/get-design-done 1.51.0 → 1.53.0

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

package/scripts/lib/design-context/integration-map.mjs

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+// scripts/lib/design-context/integration-map.mjs - Phase 52 (DesignContext graph), executor D.
+//
+// Renders an Atomic-Design integration map (mermaid) from the canonical
+// DesignContext graph at .design/context-graph.json. The map groups nodes into
+// the four Atomic-Design tiers (Atomic, Molecular, Organism, Template) using the
+// `layer` node subtype as the tier authority, then draws the `composes` and
+// `extends` edges between entities so a reader sees how the system assembles.
+//
+// Tier assignment
+// ---------------
+// A `layer` node carries a subtype of Atomic / Molecular / Organism / Template
+// and a set of `composes`/`extends` edges to the entities that sit in that tier.
+// Every entity reachable from a layer node by a composes/extends edge is placed
+// in that layer's tier. An entity with no layer membership lands in an
+// "Unlayered" bucket so nothing is silently dropped. When the graph has NO layer
+// nodes at all (a pre-taxonomy graph), every composes/extends participant falls
+// into "Unlayered" and the map still renders.
+//
+// Pure render seam
+// ----------------
+// render(graph) -> mermaid markdown string. No I/O, no Date.now(), no deps. The
+// CLI main() reads .design/context-graph.json and atomic-writes
+// .design/INTEGRATION-MAP.md via the sibling graph/atomic-write helper. main() is
+// non-fatal when the graph is absent or unreadable: it prints a notice to stderr
+// and returns 0, so a pipeline step that always runs it never breaks a build.
+//
+// No network, no optional deps, no top-level Date.now() (stamped only in main()).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { writeFileSync, renameSync, unlinkSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname, basename, join, resolve } from 'node:path';
+
+const DEFAULT_GRAPH = path.join('.design', 'context-graph.json');
+const DEFAULT_OUT = path.join('.design', 'INTEGRATION-MAP.md');
+
+// The four Atomic-Design tiers, in render order (broad to composed).
+const TIERS = ['Atomic', 'Molecular', 'Organism', 'Template'];
+const UNLAYERED = 'Unlayered';
+
+// Edges that express assembly. composes = whole -> part; extends = special -> base.
+const ASSEMBLY_EDGE_TYPES = new Set(['composes', 'extends']);
+
+function nodeList(graph) {
+  return Array.isArray(graph && graph.nodes) ? graph.nodes : [];
+}
+function edgeList(graph) {
+  return Array.isArray(graph && graph.edges) ? graph.edges : [];
+}
+
+/**
+ * Map every node id to its Atomic-Design tier. A `layer` node's subtype names a
+ * tier; the entities it composes/extends inherit that tier. Ids not reached from
+ * any layer land in UNLAYERED. A node id may appear under at most one tier (first
+ * layer membership wins, layers walked in TIERS order then by id for stability).
+ */
+function tierByNodeId(graph) {
+  const nodes = nodeList(graph);
+  const edges = edgeList(graph);
+  const byId = new Map(nodes.filter((n) => n && typeof n.id === 'string').map((n) => [n.id, n]));
+
+  // Layer nodes grouped by their tier subtype.
+  const layerNodes = nodes.filter((n) => n && n.type === 'layer' && typeof n.id === 'string');
+  const tierOfLayer = new Map();
+  for (const ln of layerNodes) {
+    const sub = TIERS.includes(ln.subtype) ? ln.subtype : UNLAYERED;
+    tierOfLayer.set(ln.id, sub);
+  }
+
+  // For each layer, the entities it reaches via a composes/extends edge.
+  const assignment = new Map(); // nodeId -> tier
+  const orderedLayers = [...layerNodes].sort((a, b) => {
+    const ta = TIERS.indexOf(tierOfLayer.get(a.id));
+    const tb = TIERS.indexOf(tierOfLayer.get(b.id));
+    if (ta !== tb) return (ta === -1 ? TIERS.length : ta) - (tb === -1 ? TIERS.length : tb);
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+  });
+
+  for (const ln of orderedLayers) {
+    const tier = tierOfLayer.get(ln.id) || UNLAYERED;
+    for (const e of edges) {
+      if (!e || !ASSEMBLY_EDGE_TYPES.has(e.type)) continue;
+      // A layer "owns" the member regardless of edge direction: the member is the
+      // non-layer endpoint of an assembly edge that touches this layer.
+      let member = null;
+      if (e.source === ln.id) member = e.target;
+      else if (e.target === ln.id) member = e.source;
+      if (member && byId.has(member) && !assignment.has(member)) assignment.set(member, tier);
+    }
+    // The layer node itself sits in its own tier.
+    if (!assignment.has(ln.id)) assignment.set(ln.id, tier);
+  }
+
+  return { assignment, byId };
+}
+
+/** Sanitize a node id into a mermaid-safe node key (alnum + underscore). */
+function mermaidKey(id) {
+  return 'n_' + String(id).replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+}
+
+/** Escape a label for a mermaid quoted node label. */
+function mermaidLabel(node) {
+  const name = (node && (node.name || node.id)) || '';
+  const type = (node && node.type) || '';
+  const text = type ? `${name} (${type})` : `${name}`;
+  return text.replace(/"/g, "'").replace(/[\r\n]+/g, ' ');
+}
+
+/**
+ * Pure render: build the Atomic-Design integration map as mermaid markdown.
+ * @param {object} graph  a DesignContext graph ({nodes[], edges[]}) or empty/absent.
+ * @returns {string} markdown with a fenced mermaid flowchart, always non-empty.
+ */
+export function render(graph) {
+  const nodes = nodeList(graph);
+  const edges = edgeList(graph);
+  const { assignment, byId } = tierByNodeId(graph);
+
+  // Bucket every assembly participant by tier (so the diagram only draws nodes
+  // that actually take part in composition, plus their layer nodes).
+  const buckets = new Map([...TIERS, UNLAYERED].map((t) => [t, []]));
+  const drawn = new Set();
+  const place = (id) => {
+    if (!byId.has(id) || drawn.has(id)) return;
+    const tier = assignment.get(id) || UNLAYERED;
+    buckets.get(tier).push(id);
+    drawn.add(id);
+  };
+  for (const e of edges) {
+    if (!e || !ASSEMBLY_EDGE_TYPES.has(e.type)) continue;
+    place(e.source);
+    place(e.target);
+  }
+  // Always show layer nodes even if they have no assembly edge yet.
+  for (const n of nodes) if (n && n.type === 'layer') place(n.id);
+
+  const lines = [];
+  lines.push('# Integration Map');
+  lines.push('');
+  lines.push(
+    'Atomic-Design composition map derived from `.design/context-graph.json`. Nodes are grouped ' +
+      'by Atomic-Design tier (from `layer` node subtype); edges show `composes` and `extends` ' +
+      'relationships. Regenerate with `node scripts/lib/design-context/integration-map.mjs`.',
+  );
+  lines.push('');
+
+  const totalDrawn = [...buckets.values()].reduce((acc, ids) => acc + ids.length, 0);
+  if (totalDrawn === 0) {
+    lines.push('_No `composes`/`extends` relationships in the graph yet, so there is nothing to map._');
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  lines.push('```mermaid');
+  lines.push('flowchart TD');
+
+  // Subgraphs per tier (only non-empty ones), in TIERS order then Unlayered.
+  for (const tier of [...TIERS, UNLAYERED]) {
+    const ids = buckets.get(tier);
+    if (!ids.length) continue;
+    lines.push(`  subgraph ${tier}`);
+    for (const id of ids.sort()) {
+      const node = byId.get(id);
+      lines.push(`    ${mermaidKey(id)}["${mermaidLabel(node)}"]`);
+    }
+    lines.push('  end');
+  }
+
+  // Assembly edges (composes = solid arrow; extends = thick "extends" arrow).
+  const seenEdge = new Set();
+  for (const e of edges) {
+    if (!e || !ASSEMBLY_EDGE_TYPES.has(e.type)) continue;
+    if (!byId.has(e.source) || !byId.has(e.target)) continue;
+    const key = `${e.source}--${e.type}-->${e.target}`;
+    if (seenEdge.has(key)) continue;
+    seenEdge.add(key);
+    const a = mermaidKey(e.source);
+    const b = mermaidKey(e.target);
+    if (e.type === 'extends') lines.push(`  ${a} -. extends .-> ${b}`);
+    else lines.push(`  ${a} --> ${b}`);
+  }
+
+  lines.push('```');
+  lines.push('');
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Atomic write (inlined twin of scripts/lib/graph/atomic-write.mjs for a text
+// payload; that helper is JSON-only and the map is markdown). Same tmp+rename
+// invariant: tmp lives in the SAME dir as target (Windows-atomic rename).
+// ---------------------------------------------------------------------------
+
+function atomicWriteText(target, body) {
+  const parent = dirname(target);
+  const base = basename(target);
+  const tmp = join(
+    parent,
+    `.${base}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`,
+  );
+  if (resolve(dirname(tmp)) !== resolve(parent)) {
+    throw new Error(`atomicWriteText invariant: tmp not in same dir as target (tmp=${tmp}, target=${target})`);
+  }
+  mkdirSync(parent, { recursive: true });
+  try {
+    writeFileSync(tmp, body, 'utf8');
+    renameSync(tmp, target);
+  } catch (err) {
+    if (existsSync(tmp)) {
+      try { unlinkSync(tmp); } catch { /* swallow cleanup error; original throw wins */ }
+    }
+    throw err;
+  }
+}
+
+/**
+ * CLI entry. Reads the graph (argv[0] or the default path), renders the map, and
+ * atomic-writes it (argv[1] or the default out). Non-fatal when the graph is
+ * absent or unreadable: prints a notice and returns 0.
+ * @returns {number} process exit code (0 always, by design; this is advisory).
+ */
+export function main(argv = process.argv.slice(2)) {
+  const graphPath = argv[0] || DEFAULT_GRAPH;
+  const outPath = argv[1] || DEFAULT_OUT;
+
+  if (!fs.existsSync(graphPath)) {
+    process.stderr.write(`integration-map: no graph at ${graphPath} (skipping, non-fatal)\n`);
+    return 0;
+  }
+  let graph;
+  try {
+    graph = JSON.parse(fs.readFileSync(graphPath, 'utf8'));
+  } catch (err) {
+    process.stderr.write(`integration-map: unreadable graph ${graphPath} (${err.message}) (skipping, non-fatal)\n`);
+    return 0;
+  }
+
+  const md = render(graph);
+  const stamp = `<!-- generated ${new Date().toISOString()} by scripts/lib/design-context/integration-map.mjs -->\n`;
+  atomicWriteText(outPath, stamp + md);
+  process.stderr.write(`integration-map: wrote ${outPath}\n`);
+  return 0;
+}
+
+// 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) process.exit(main());