@thinkwise/testwise 0.2.67 → 0.2.103

package/scripts/diagram.js

@@ -0,0 +1,2267 @@
+#!/usr/bin/env node
+/* eslint-disable @typescript-eslint/naming-convention */
+/** biome-ignore-all lint/suspicious/noAssignInExpressions: reason42 */
+/**
+ * Testwise Architecture Diagram
+ * Serves a living structured SVG diagram that rescans source files on every refresh.
+ * Run via: testwise diagram  OR  npm run diagram
+ */
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+
+// ─── Filesystem helpers ───────────────────────────────────────────────────────
+
+/** Scan a flat folder for .ts source files; skip index.ts, *.d.ts, *Objects.ts */
+function scanTs(relDir) {
+  const dir = path.join(ROOT, relDir);
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter(
+      (e) =>
+        e.isFile() &&
+        e.name.endsWith('.ts') &&
+        !e.name.endsWith('.d.ts') &&
+        e.name !== 'index.ts' &&
+        !e.name.endsWith('Objects.ts')
+    )
+    .map((e) => e.name.replace(/\.ts$/, ''));
+}
+
+/** Scan components/ subfolders and categorise into subject / screen / overlay */
+function scanComponentFolders() {
+  const dir = path.join(ROOT, 'components');
+  if (!fs.existsSync(dir)) return { subject: [], screen: [], overlay: [] };
+
+  const SUBJECT = new Set(['form', 'grid']);
+  const OVERLAY = new Set(['pop-up', 'export', 'snackbar', 'topbar', 'menu', 'task']);
+
+  const subject = [],
+    screen = [],
+    overlay = [];
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (!e.isDirectory()) continue;
+    const label = e.name
+      .split('-')
+      .map((w) => w[0].toUpperCase() + w.slice(1))
+      .join('');
+    if (SUBJECT.has(e.name)) subject.push(label);
+    else if (OVERLAY.has(e.name)) overlay.push(label);
+    else screen.push(label);
+  }
+  return { subject, screen, overlay };
+}
+
+// ─── JSDoc parser ─────────────────────────────────────────────────────────────
+
+/**
+ * Parse JSDoc comments from a TypeScript source file.
+ * Returns { summary, members } where members is an array of { name, kind, doc }.
+ * - summary: the first top-level file/class/function JSDoc block
+ * - members: all exported functions, methods, classes, and constants with their JSDoc
+ */
+function parseJsDoc(absPath) {
+  if (!fs.existsSync(absPath)) return { summary: '', members: [] };
+  const src = fs.readFileSync(absPath, 'utf8');
+
+  // Strip single-line // comments to avoid false-positive matches
+  const stripped = src.replace(/\/\/[^\n]*/g, '');
+
+  // Extract all /** … */ blocks with the code line that follows them
+  const blockRe =
+    /\/\*\*([\s\S]*?)\*\/([ \t]*\n[ \t]*(?:export\s+)?((?:async\s+)?(?:class|function|const|interface|type|enum|abstract\s+class)\s+(\w+)|(?:(?:public|protected|private|static|async|readonly|override)\s+)*(\w+)\s*[(<]))/g;
+
+  const members = [];
+  let summary = '';
+  let summaryFromExport = false;
+  let m;
+
+  while ((m = blockRe.exec(stripped)) !== null) {
+    const rawDoc = m[1];
+    const followingLine = m[2].trim();
+    const isExported = /^\s*export\s/.test(m[2]);
+
+    // Clean the JSDoc text: remove leading * on each line, collapse whitespace
+    // Strip @example sections (and the code lines that follow) before filtering
+    const docLines = rawDoc.split('\n').map((l) => l.replace(/^\s*\*\s?/, '').trim());
+    let inExample = false;
+    const filteredLines = docLines.filter((l) => {
+      if (l.startsWith('@example')) {
+        inExample = true;
+        return false;
+      }
+      if (inExample && l.startsWith('@')) inExample = false;
+      if (inExample) return false;
+      return l && !l.startsWith('@param') && !l.startsWith('@returns') && !l.startsWith('@template');
+    });
+    const doc = filteredLines.join(' ').replace(/\s+/g, ' ').trim();
+
+    if (!doc) continue;
+
+    // Determine the exported name
+    const nameMatch =
+      followingLine.match(/(?:class|function|const|interface|type|enum|abstract\s+class)\s+(\w+)/) ||
+      followingLine.match(/^(?:(?:public|protected|private|static|async|readonly|override)\s+)*(\w+)\s*[(<]/);
+    const name = nameMatch ? nameMatch[1] : null;
+
+    // Determine kind for display
+    let kind = 'member';
+    if (/\bclass\b/.test(followingLine)) kind = 'class';
+    else if (/\bfunction\b/.test(followingLine)) kind = 'function';
+    else if (/\bconst\b/.test(followingLine)) kind = 'const';
+    else if (/\binterface\b/.test(followingLine)) kind = 'interface';
+    else if (/\benum\b/.test(followingLine)) kind = 'enum';
+    else if (/\btype\b/.test(followingLine)) kind = 'type';
+    else if (/\basync\b/.test(followingLine)) kind = 'method';
+    else kind = 'method';
+
+    // Prefer exported symbols as summary; accept non-exported only if nothing found yet
+    if (!summary || (!summaryFromExport && isExported)) {
+      if (
+        doc.length <= 600 &&
+        !doc.startsWith('biome-') &&
+        !doc.startsWith('eslint-') &&
+        !doc.includes('=>') &&
+        !doc.includes('await ') &&
+        !doc.includes('Promise<') &&
+        !doc.includes('this.')
+      ) {
+        summary = doc;
+        if (isExported) summaryFromExport = true;
+      }
+    }
+
+    if (name && name !== 'constructor') {
+      // Skip members whose doc looks like code
+      if (!doc.includes('=>') && !doc.includes('await ') && !doc.includes('Promise<') && !doc.includes('this.')) {
+        members.push({ name, kind, doc });
+      }
+    }
+  }
+
+  // If no JSDoc found at all, try to get the first block regardless of what follows
+  if (!summary) {
+    const firstBlock = stripped.match(/\/\*\*([\s\S]*?)\*\//);
+    if (firstBlock) {
+      const candidate = firstBlock[1]
+        .split('\n')
+        .map((l) => l.replace(/^\s*\*\s?/, '').trim())
+        .filter(Boolean)
+        .join(' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+      // Only use it if it looks like a real summary (not a code dump or lint directive)
+      if (
+        candidate.length <= 600 &&
+        !candidate.includes('=>') &&
+        !candidate.includes('await ') &&
+        !candidate.startsWith('biome-') &&
+        !candidate.startsWith('eslint-')
+      ) {
+        summary = candidate;
+      }
+    }
+  }
+
+  return { summary, members };
+}
+
+/**
+ * Build a tips map for all scanned source files.
+ * Keys are bare file names (no extension), values are tooltip HTML strings.
+ * Reads JSDoc live from each .ts file on every call (living docs).
+ */
+function buildTipsMap(fileMap) {
+  // fileMap: { 'relDir/fileName': absPath, ... }
+  const tips = {};
+  for (const [key, absPath] of Object.entries(fileMap)) {
+    const name = key.split('/').pop();
+    const { summary, members } = parseJsDoc(absPath);
+    if (!summary && members.length === 0) continue;
+
+    let text = summary || '';
+    if (members.length > 0) {
+      const lines = members.map((mem) => {
+        const kindLabel = mem.kind === 'method' || mem.kind === 'function' ? `${mem.name}()` : mem.name;
+        const doc = mem.doc.length > 120 ? `${mem.doc.slice(0, 117)}…` : mem.doc;
+        return `• ${kindLabel} — ${doc}`;
+      });
+      text += (text ? '\n\n' : '') + lines.join('\n');
+    }
+    tips[name] = text;
+  }
+  return tips;
+}
+
+/** Scan a directory recursively for all .ts files (not .d.ts, not node_modules/dist) */
+function scanAllTsFiles() {
+  const SKIP_DIRS = new Set(['node_modules', 'dist', 'coverage', '.git', 'test-artifacts', 'seed-data', 'logs']);
+  const results = [];
+  function walk(dir) {
+    if (!fs.existsSync(dir)) return;
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (SKIP_DIRS.has(e.name)) continue;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) walk(full);
+      else if (e.isFile() && e.name.endsWith('.ts') && !e.name.endsWith('.d.ts')) {
+        results.push(full);
+      }
+    }
+  }
+  walk(ROOT);
+  return results;
+}
+
+/**
+ * Parse the import statements from a TypeScript file.
+ * Returns an array of relative paths that this file imports.
+ */
+function parseImports(absPath) {
+  try {
+    const src = fs.readFileSync(absPath, 'utf8');
+    const importRe = /from\s+['"]([^'"]+)['"]/g;
+    const imports = [];
+    let m;
+    while ((m = importRe.exec(src)) !== null) {
+      const spec = m[1];
+      if (spec.startsWith('.')) imports.push(spec);
+    }
+    return imports;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Build the full living dependency graph from all .ts files in the project.
+ * Returns { nodes, links } where links use actual parsed imports.
+ */
+function buildDepGraph() {
+  const MOD_COLOR = {
+    services: '#9b59b6',
+    interfaces: '#5a8abf',
+    types: '#9a8a50',
+    enums: '#9a8a50',
+    'artifact-builder/helpers': '#c9a558',
+    'artifact-builder': '#d4910a',
+    controls: '#c084fc',
+    helpers: '#27ae60',
+    'page-overrides': '#c0392b',
+    'page-extensions': '#16a085',
+    components: '#4a90d9',
+    mcp: '#f97316',
+    tests: '#64748b',
+    scripts: '#94a3b8',
+    root: '#58a6ff'
+  };
+
+  const allFiles = scanAllTsFiles();
+  // Map from absolute path → { id, name, group, relPath }
+  const byPath = new Map();
+  const nodes = [];
+
+  for (const absFile of allFiles) {
+    const rel = path.relative(ROOT, absFile).replace(/\\/g, '/');
+    const parts = rel.split('/');
+    // Determine group: first folder, or 'root' for top-level files
+    let group = parts.length > 1 ? parts[0] : 'root';
+    // Sub-group artifact-builder/helpers separately
+    if (parts[0] === 'artifact-builder' && parts[1] === 'helpers') group = 'artifact-builder/helpers';
+    const name = parts[parts.length - 1].replace(/\.ts$/, '');
+    const id = rel.replace(/\.ts$/, '');
+    const node = {
+      id,
+      name,
+      group,
+      rel,
+      absPath: absFile,
+      tip: '',
+      color: MOD_COLOR[group] || '#8b949e'
+    };
+    nodes.push(node);
+    byPath.set(absFile, node);
+  }
+
+  const links = [];
+  const seen = new Set();
+
+  for (const node of nodes) {
+    const imports = parseImports(node.absPath);
+    for (const imp of imports) {
+      // Resolve the import relative to the importing file's directory
+      const impDir = path.dirname(node.absPath);
+      // Strip .js extension — TS ESM imports use .js but the actual files are .ts
+      const impNoExt = imp.replace(/\.js$/, '');
+      const resolved = path.resolve(impDir, impNoExt).replace(/\\/g, '/');
+      // Try .ts, then /index.ts
+      const candidates = [`${resolved}.ts`, `${resolved}/index.ts`];
+      for (const cand of candidates) {
+        const target = byPath.get(cand.replace(/\//g, path.sep));
+        if (target && target.id !== node.id) {
+          const key = `${node.id}->${target.id}`;
+          if (!seen.has(key)) {
+            seen.add(key);
+            links.push({ source: node.id, target: target.id });
+          }
+          break;
+        }
+      }
+    }
+  }
+
+  return { nodes, links };
+}
+
+// ─── HTML page generation ────────────────────────────────────────────────────
+
+/** Dep graph computed once at server start (not per request). */
+const _cachedDepGraph = buildDepGraph();
+
+function esc(s) {
+  return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+// ─── HTML page generation ────────────────────────────────────────────────────
+
+function generateHtml() {
+  const components = scanComponentFolders();
+  const controls = scanTs('controls');
+  const helpers = scanTs('helpers');
+  const pageExts = scanTs('page-extensions').filter((f) => f !== 'SubjectRegistry');
+  const pageOvr = scanTs('page-overrides');
+  const interfaces = scanTs('interfaces');
+  const types = [...scanTs('types'), ...scanTs('enums')];
+  const services = scanTs('services');
+  const pipeline = scanTs('artifact-builder');
+  const pipeHelpers = scanTs('artifact-builder/helpers');
+  const scripts =
+    scanTs('scripts').length > 0 ? scanTs('scripts') : ['main', 'postinstall', 'setup', 'sync', 'diagram'];
+  const mcpFiles = scanTs('mcp').length > 0 ? scanTs('mcp') : ['ArtifactResolver'];
+  const generatedAt = new Date().toLocaleString();
+  const ROOT_ESC = ROOT.replace(/\\/g, '/');
+
+  // TIPS are used only for data-tip attributes on arch card items.
+  // They are also served via /api/data for client-side use.
+  // Build them here so card HTML can include them.
+  function absPath(relDir, name) {
+    return path.join(ROOT, relDir, `${name}.ts`);
+  }
+  const fileMap = {};
+  const addGroup = (relDir, list) => {
+    for (const name of list) fileMap[`${relDir}/${name}`] = absPath(relDir, name);
+  };
+  addGroup('services', services);
+  addGroup('interfaces', interfaces);
+  addGroup('types', scanTs('types'));
+  addGroup('enums', scanTs('enums'));
+  addGroup('artifact-builder', pipeline);
+  addGroup('artifact-builder/helpers', pipeHelpers);
+  addGroup('controls', controls);
+  addGroup('helpers', helpers);
+  addGroup('page-overrides', pageOvr);
+  addGroup('page-extensions', [...pageExts, 'SubjectRegistry']);
+  addGroup('mcp', mcpFiles);
+  // Scripts are .js not .ts — add them separately with correct extension
+  for (const name of scripts) {
+    const jsPath = path.join(ROOT, 'scripts', `${name}.js`);
+    if (fs.existsSync(jsPath)) fileMap[`scripts/${name}`] = jsPath;
+  }
+  const compDir = path.join(ROOT, 'components');
+  if (fs.existsSync(compDir)) {
+    for (const e of fs.readdirSync(compDir, { withFileTypes: true })) {
+      if (!e.isDirectory()) continue;
+      // Add ALL non-Objects, non-index .ts files in each component folder
+      const folderDir = path.join(compDir, e.name);
+      for (const f of fs.readdirSync(folderDir)) {
+        if (!f.endsWith('.ts') || f.endsWith('.d.ts') || f.endsWith('Objects.ts') || f === 'index.ts') continue;
+        const name = f.replace(/\.ts$/, '');
+        fileMap[`components/${name}`] = path.join(folderDir, f);
+      }
+    }
+  }
+  const TIPS = buildTipsMap(fileMap);
+
+  const items = (list, color = '#8b949e') =>
+    list
+      .map((x) => {
+        const tip = TIPS[String(x)] || '';
+        const tipAttr = tip ? ` data-tip="${esc(tip)}"` : '';
+        return `<div class="item" style="color:${color}"${tipAttr}>${esc(String(x))}</div>`;
+      })
+      .join('');
+
+  // fileItems variant that resolves across multiple candidate dirs (first match wins)
+  const fileItemsAny = (list, dirs, color = '#8b949e') =>
+    list
+      .map((name) => {
+        const tip = TIPS[name] || '';
+        const tipAttr = tip ? ` data-tip="${esc(tip)}"` : '';
+        // Find first dir where the file actually exists
+        const relDir = dirs.find((d) => fs.existsSync(path.join(ROOT, d, `${name}.ts`))) || dirs[0];
+        const p = `${ROOT_ESC}/${relDir}/${name}.ts`;
+        return `<div class="item file-item" style="color:${color}" data-path="${p}"${tipAttr}>${esc(name)}</div>`;
+      })
+      .join('');
+
+  // Component items — files live in components/<kebab-name>/<PascalName>.ts
+  const toKebab = (s) => s.replace(/([A-Z])/g, (_m, c, i) => (i > 0 ? `-${c.toLowerCase()}` : c.toLowerCase()));
+  const compItems = (list, color = '#8b949e') =>
+    list
+      .flatMap((folderLabel) => {
+        const folderName = toKebab(folderLabel);
+        const folderDir = path.join(ROOT, 'components', folderName);
+        let files = [];
+        if (fs.existsSync(folderDir)) {
+          files = fs
+            .readdirSync(folderDir)
+            .filter((f) => f.endsWith('.ts') && !f.endsWith('.d.ts') && !f.endsWith('Objects.ts') && f !== 'index.ts')
+            .map((f) => f.replace(/\.ts$/, ''));
+        }
+        if (files.length === 0) files = [folderLabel];
+        return files.map((name) => {
+          const tip = TIPS[name] || '';
+          const tipAttr = tip ? ` data-tip="${esc(tip)}"` : '';
+          const p = `${ROOT_ESC}/components/${folderName}/${name}.ts`;
+          return `<div class="item file-item" style="color:${color}" data-path="${p}"${tipAttr}>${esc(name)}</div>`;
+        });
+      })
+      .join('');
+
+  // Root-level file links (no extension in list, but path includes extension)
+  const rootItems = (list, color = '#8b949e') =>
+    list
+      .map((name) => {
+        const tip = TIPS[name] || '';
+        const tipAttr = tip ? ` data-tip="${esc(tip)}"` : '';
+        const absPath = path.join(ROOT, name);
+        if (!fs.existsSync(absPath)) return `<div class="item" style="color:${color}">${esc(name)}</div>`;
+        const p = `${ROOT_ESC}/${name}`;
+        return `<div class="item file-item" style="color:${color}" data-path="${p}"${tipAttr}>${esc(name)}</div>`;
+      })
+      .join('');
+
+  // .js file items — links into the scripts/ folder
+  const jsFileItems = (list, relDir, color = '#8b949e') =>
+    list
+      .map((name) => {
+        const tip = TIPS[name] || '';
+        const tipAttr = tip ? ` data-tip="${esc(tip)}"` : '';
+        const p = `${ROOT_ESC}/${relDir}/${name}.js`;
+        return `<div class="item file-item" style="color:${color}" data-path="${p}"${tipAttr}>${esc(`${name}.js`)}</div>`;
+      })
+      .join('');
+
+  // Render file items — always clickable, tooltip from JSDoc if available
+  const fileItems = (list, relDir, color = '#8b949e') =>
+    list
+      .map((name) => {
+        const tip = TIPS[name] || '';
+        const tipAttr = tip ? ` data-tip="${esc(tip)}"` : '';
+        const p = `${ROOT_ESC}/${relDir}/${name}.ts`;
+        return `<div class="item file-item" style="color:${color}" data-path="${p}"${tipAttr}>${esc(name)}</div>`;
+      })
+      .join('');
+
+  // Dashed inner sub-box
+  const subbox = (title, accent, content, foot = '') =>
+    `<div class="subbox" style="--sa:${accent}">` +
+    `<div class="subbox-head">${esc(title)}</div>` +
+    `<div class="subbox-body">${content}</div>` +
+    (foot ? `<div class="subbox-foot">${esc(foot)}</div>` : '') +
+    `</div>`;
+
+  // Main card  (tip = optional tooltip on the card header)
+  const card = (id, accent, titleBg, bodyBg, title, body, foot = '', tip = '') =>
+    `<div class="card" id="${id}" style="--ca:${accent};--ct:${titleBg};--cb:${bodyBg}">` +
+    `<div class="card-head"${tip ? ` data-tip="${esc(tip)}"` : ''}>${esc(title)}</div>` +
+    `<div class="card-body">${body}</div>` +
+    (foot ? `<div class="card-foot">${esc(foot)}</div>` : '') +
+    `</div>`;
+
+  // ── Data ─────────────────────────────────────────────────────────────────
+  const svcList = services.length > 0 ? services : ['ConfigBuilder', 'IndiciumApi.service', 'Logger'];
+
+  const ifaceList =
+    interfaces.length > 0
+      ? interfaces
+      : [
+          'ISubject',
+          'IProperty',
+          'IRegisteredSubjects',
+          'IStoredTestResults',
+          'IComponentObjects',
+          'IComponentSchemaMeta',
+          'ISeedSubjectDraft'
+        ];
+
+  const typeList = types.length > 0 ? types : ['Components', 'Test', 'ElementTypes', 'ExportFormat', 'LogLevel'];
+
+  const stepList =
+    pipeline.length > 0
+      ? pipeline
+      : [
+          'ArtifactManager',
+          'ModelDataBuilder',
+          'ModelDataRefiner',
+          'SchemaGenerator',
+          'InterfaceGenerator',
+          'ScreenInterfaceRefiner',
+          'SelectorBuilder',
+          'SubjectClassModelBuilder',
+          'ComponentClassModelBuilder',
+          'SubjectGenerator',
+          'SubjectComponentGenerator',
+          'SubjectRegistration',
+          'TsFileModel',
+          'TsFileSerializer'
+        ];
+
+  const pipeHList =
+    pipeHelpers.length > 0 ? pipeHelpers : ['DataRetriever', 'NamingHandler', 'Stopwatch', 'PipelinePaths'];
+
+  const ctrlList =
+    controls.length > 0
+      ? controls
+      : ['InputFieldControl', 'FormComboBox', 'DateControl', 'LookupDropdown', 'GridColumnControl'];
+
+  const helpList =
+    helpers.length > 0
+      ? helpers
+      : [
+          'FlightTracker',
+          'GlobalWaitEventHandler',
+          'LoginHelper',
+          'SubjectNavigator',
+          'Ensure',
+          'Poll',
+          'RegexHelper',
+          'PathResolver',
+          'UserSimulationHelper',
+          'ConfigChecker'
+        ];
+
+  const ovrList = pageOvr.length > 0 ? pageOvr : ['ClickOverride', 'FillOverride'];
+  const extList =
+    pageExts.length > 0
+      ? pageExts
+      : ['GlobalComponents', 'GoToDeepLink', 'LoginFeatures', 'WaitEventHandler', 'UserSimulation'];
+
+  // ── Section cards ─────────────────────────────────────────────────────────
+  const extCard = card(
+    'sec-ext',
+    '#3fb950',
+    '#163320',
+    '#0d2018',
+    '📦 External Dependencies',
+    items(
+      ['@playwright/test', 'playwright-bdd', 'quicktype-core', 'prettier', 'axios', 'ts-morph', 'chalk'],
+      '#7cc97e'
+    ),
+    '',
+    'Third-party npm packages that Testwise depends on. @playwright/test is the core test runner; quicktype-core generates TypeScript interfaces from JSON schemas.'
+  );
+
+  const cfgCard = card(
+    'sec-cfg',
+    '#4a90d9',
+    '#152238',
+    '#0d1829',
+    '⚙ Configuration',
+    rootItems(['Testwise.json', 'config.json', '.env'], '#7db3d9'),
+    'provided by consumer project',
+    'Configuration files supplied by the consuming project. Testwise.json holds base-URL and credentials; config.json holds environment-specific overrides; .env provides secrets.'
+  );
+
+  const svcCard = card(
+    'sec-svc',
+    '#9b59b6',
+    '#261040',
+    '#16082a',
+    '🔌 Services',
+    fileItems(svcList, 'services', '#c39cdf'),
+    '',
+    'Service classes used internally by the library: configuration access, API calls, and logging.'
+  );
+
+  const ifaceCard = card(
+    'sec-iface',
+    '#5a8abf',
+    '#152238',
+    '#0d1829',
+    '🔷 Interfaces',
+    fileItems(ifaceList, 'interfaces', '#7db3d9'),
+    '',
+    'TypeScript contracts (interfaces) that define the shape of subjects, properties, and components across the library.'
+  );
+
+  const typeCard = card(
+    'sec-types',
+    '#9a8a50',
+    '#2e2810',
+    '#1c1808',
+    '🏷 Types & Enums',
+    fileItemsAny(typeList, ['types', 'enums'], '#c9b96e'),
+    '',
+    'Shared TypeScript type aliases and enumerations used across components, controls, and the artifact pipeline.'
+  );
+
+  const pipeCard = card(
+    'sec-pipe',
+    '#d4910a',
+    '#2c1c0a',
+    '#1a1108',
+    '⚙ Build-Time: Artifact Generation Pipeline',
+    `<div class="pipe-layout">` +
+      `<div class="pipe-steps">${fileItems(stepList, 'artifact-builder', '#c9a558')}</div>` +
+      `<div class="stack" style="gap:10px">` +
+      subbox('Builder Helpers', '#d4910a', fileItems(pipeHList, 'artifact-builder/helpers', '#c9a558')) +
+      subbox(
+        'Templates',
+        '#a07830',
+        items(['SubjectRegistry.template.ts'], '#c9a558'),
+        'source-of-truth for generated files'
+      ) +
+      `</div>` +
+      `</div>`,
+    'Input: seed-data/  →  Output: test-artifacts/',
+    'Reads the Thinkwise application model via API and generates typed TypeScript subject classes and screen interfaces. Run via the testwise sync CLI command.'
+  );
+
+  const genCard = card(
+    'sec-gen',
+    '#c9c258',
+    '#28280e',
+    '#1a1a08',
+    '✨ Generated Artifacts',
+    items(['SubjectPageBase', 'screens/*.ts', 'subjects/<Name>/*.ts', 'SubjectRegistry.ts'], '#c9c258'),
+    'test-artifacts/ — never edit directly',
+    'Output of the artifact pipeline. Contains typed subject classes (one per Thinkwise subject), screen interfaces, and the SubjectRegistry. Never edit these files — they are regenerated on every sync.'
+  );
+
+  const scriptsCard = card(
+    'sec-scripts',
+    '#94a3b8',
+    '#1a1f2e',
+    '#10141e',
+    '📜 Scripts (scripts/)',
+    jsFileItems(scripts, 'scripts', '#94a3b8'),
+    'CLI entry points',
+    'Plain JavaScript CLI scripts. main.js is the testwise CLI entry; sync.js runs the full artifact pipeline; postinstall.js runs after npm install; diagram.js serves this living architecture diagram.'
+  );
+
+  const mcpCard = card(
+    'sec-mcp',
+    '#f97316',
+    '#2a1400',
+    '#180d00',
+    '🤖 AI / MCP',
+    fileItems(mcpFiles, 'mcp', '#fb923c') +
+      items(['@thinkwise/testwise-mcp', 'GitHub Copilot Agents', 'VS Code MCP integration'], '#fb923c'),
+    '',
+    'ArtifactResolver exposes generated subjects and components to AI tooling via the Model Context Protocol. The MCP server is consumed by @thinkwise/testwise-mcp and powers GitHub Copilot agent workflows.'
+  );
+
+  const devCard = card(
+    'sec-dev',
+    '#64748b',
+    '#1a1f28',
+    '#10141a',
+    '🛠 Dev Tooling',
+    items(['ESLint', 'Biome (format/lint)', 'vitest (unit tests)', 'ts-morph', 'prettier'], '#94a3b8') +
+      `<div style="margin-top:6px">${items(['tests/ (mirrors src structure)', 'coverage/'], '#64748b')}</div>`,
+    'npm test  ·  npm run format:fix',
+    'Development quality tools. ESLint and Biome handle linting and formatting. Vitest runs unit tests (no browser required). Tests live in tests/ and mirror the source structure.'
+  );
+
+  const fixCard = card(
+    'sec-fix',
+    '#4a90d9',
+    '#152238',
+    '#0d1829',
+    '⛓ Fixture Chain (Testwise.ts)',
+    items(
+      [
+        '1. @playwright/test base',
+        '2. playwright-bdd',
+        '3. ClickOverride',
+        '4. FillOverride',
+        '5. GlobalComponents',
+        '6. GoToDeepLink',
+        '7. LoginFeatures',
+        '8. UserSimulation',
+        '9. WaitEventHandler',
+        '10. SubjectRegistry',
+        '↓ export: test'
+      ],
+      '#7db3d9'
+    ),
+    '',
+    'The ordered chain of Playwright test.extend() calls that compose the final test fixture exported by this library. Each layer adds capabilities to the page object. playwright-bdd adds BDD step support.'
+  );
+
+  const consCard = card(
+    'sec-cons',
+    '#58a6ff',
+    '#0d1828',
+    '#08101a',
+    '🧪 Consumer Test Project',
+    `<pre class="code-block">${esc("import { test } from '@thinkwise/testwise'\n\ntest('scenario', async ({ page }) => {\n  const emp = await\n    page.subjects\n      .Employee.goTo();\n  // use components ...\n});")}</pre>`,
+    '',
+    'How a consuming project uses Testwise. Import the test fixture, access generated subjects via page.subjects, and interact with components using typed methods.'
+  );
+
+  const compCard = card(
+    'sec-comp',
+    '#4a90d9',
+    '#152238',
+    '#0d1829',
+    '🧩 Components (components/)',
+    `<div class="comp-row">` +
+      subbox('Subject Components', '#4a90d9', compItems(components.subject, '#7db3d9'), 'typed field/col access') +
+      subbox('Screen Components', '#4a90d9', `<div class="two-col">${compItems(components.screen, '#8b949e')}</div>`) +
+      subbox('Overlay / Global', '#5a8abf', `<div class="two-col">${compItems(components.overlay, '#8b949e')}</div>`) +
+      `</div>`,
+    'Each: <Name>.ts (public API) + <Name>Objects.ts (locators)  ·  extends BaseComponentObjects',
+    'Typed wrappers around every Thinkwise UI control. Subject Components (Form, Grid) expose typed field and column accessors. Screen Components handle navigation and layout elements. Overlay/Global components handle pop-ups, menus, and toasts.'
+  );
+
+  const ctrlCard = card(
+    'sec-ctrl',
+    '#9b59b6',
+    '#221042',
+    '#14082a',
+    '🎛 Controls (controls/)',
+    fileItems(ctrlList, 'controls', '#c39cdf'),
+    'Proxy: Locator + typed methods',
+    'Fine-grained input helpers. Each wraps a specific Thinkwise form field type and exposes typed methods. Acts as both a Playwright Locator and a typed control via Proxy.'
+  );
+
+  const helpCard = card(
+    'sec-help',
+    '#27ae60',
+    '#102810',
+    '#081808',
+    '🛠 Helpers (helpers/)',
+    fileItems(helpList, 'helpers', '#7cc98a'),
+    '',
+    'Standalone utility classes used by test code and page extensions. Handle navigation, waiting, assertions, and user simulation.'
+  );
+
+  const ovrCard = card(
+    'sec-ovr',
+    '#c0392b',
+    '#2e1010',
+    '#1a0808',
+    '🔧 Page Overrides',
+    fileItems(ovrList, 'page-overrides', '#e07070'),
+    'patch Playwright timing for Thinkwise',
+    "Low-level patches that override Playwright's native click() and fill() to inject the extra waits that Thinkwise's event-driven UI requires."
+  );
+
+  const extPageCard = card(
+    'sec-pext',
+    '#16a085',
+    '#102828',
+    '#081818',
+    '🔌 Page Extensions',
+    fileItems(extList, 'page-extensions', '#60c0b0'),
+    'extend page fixture with typed methods',
+    "Each class calls test.extend() to bolt a new property or method onto Playwright's page fixture — e.g. page.login(), page.subjects, page.topbar."
+  );
+
+  // ── Full HTML ─────────────────────────────────────────────────────────────
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8"/>
+  <meta name="viewport" content="width=device-width,initial-scale=1"/>
+  <title>Testwise Architecture</title>
+  <script src="https://html2canvas.hertzen.com/dist/html2canvas.min.js"></script>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+    body {
+      background: #0d1117;
+      color: #e6edf3;
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      overflow: hidden;
+      height: 100vh;
+      display: flex;
+      flex-direction: column;
+    }
+
+    /* ── Header ── */
+    header {
+      padding: 8px 16px;
+      background: #161b22;
+      border-bottom: 1px solid #30363d;
+      display: flex;
+      align-items: center;
+      gap: 12px;
+      flex-shrink: 0;
+    }
+    header h1 { font-size: 0.88rem; font-weight: 700; color: #58a6ff; }
+    .meta { font-size: 0.68rem; color: #8b949e; }
+    .hbtn {
+      padding: 4px 12px;
+      border: none;
+      border-radius: 5px;
+      color: #fff;
+      font-size: 0.75rem;
+      cursor: pointer;
+      transition: filter 0.15s;
+    }
+    .hbtn:hover   { filter: brightness(1.15); }
+    .hbtn:disabled { opacity: 0.5; cursor: wait; }
+    #export-btn { background: #1f6feb; }
+    #reload-btn  { background: #238636; }
+    #recenter-btn { background: #6e40c9; display: none; }
+    #clear-sel-btn { background: #6e40c9; display: none; }
+
+    /* ── Viewport / zoom ── */
+    #viewport {
+      flex: 1;
+      overflow: hidden;
+      position: relative;
+      cursor: grab;
+    }
+    #viewport.dragging { cursor: grabbing; }
+
+    #diagram {
+      position: absolute;
+      top: 0; left: 0;
+      transform-origin: 0 0;
+      padding: 40px 36px;
+      display: flex;
+      flex-direction: column;
+      gap: 32px;
+    }
+
+    .top-row, .bot-row {
+      display: flex;
+      flex-direction: row;
+      gap: 28px;
+      align-items: flex-start;
+    }
+
+    .stack {
+      display: flex;
+      flex-direction: column;
+      gap: 24px;
+      flex-shrink: 0;
+    }
+
+    /* ── Cards ── */
+    .card {
+      background: var(--cb, #161b22);
+      border: 1.5px solid var(--ca, #30363d);
+      border-radius: 7px;
+      display: flex;
+      flex-direction: column;
+      flex-shrink: 0;
+      min-width: 150px;
+      position: relative;
+      z-index: 1;
+    }
+
+    .card-head {
+      background: var(--ct, #1e2a3a);
+      color: var(--ca, #e6edf3);
+      font-size: 10.5px;
+      font-weight: 700;
+      padding: 7px 11px;
+      border-radius: 5px 5px 0 0;
+      border-bottom: 1px solid var(--ca);
+      white-space: nowrap;
+    }
+
+    .card-body {
+      padding: 9px 11px;
+      flex: 1;
+    }
+
+    .card-foot {
+      font-size: 9px;
+      color: #6e8098;
+      font-style: italic;
+      padding: 5px 11px 8px;
+      border-top: 1px solid rgba(255,255,255,0.06);
+    }
+
+    /* ── Items ── */
+    .item {
+      font-family: ui-monospace, 'Cascadia Code', Consolas, monospace;
+      font-size: 10.5px;
+      padding: 2px 0;
+      white-space: nowrap;
+    }
+
+    /* ── Sub-boxes ── */
+    .subbox {
+      border: 1px dashed var(--sa, #555);
+      border-radius: 5px;
+      margin: 4px 0;
+    }
+    .subbox-head {
+      font-size: 9.5px;
+      font-weight: 600;
+      color: var(--sa);
+      padding: 4px 8px;
+      border-bottom: 1px dashed var(--sa);
+    }
+    .subbox-body { padding: 6px 8px; }
+    .subbox-foot {
+      font-size: 9px;
+      color: #6e8098;
+      font-style: italic;
+      padding: 3px 8px 6px;
+      border-top: 1px dashed rgba(255,255,255,0.07);
+    }
+
+    /* ── Pipeline ── */
+    .pipe-layout {
+      display: flex;
+      gap: 16px;
+      align-items: flex-start;
+    }
+    .pipe-steps {
+      display: grid;
+      grid-template-columns: 1fr 1fr;
+      column-gap: 20px;
+      flex-shrink: 0;
+    }
+
+    /* ── Components ── */
+    .comp-row {
+      display: flex;
+      gap: 14px;
+      align-items: flex-start;
+    }
+    .comp-row .subbox { flex-shrink: 0; }
+    .two-col {
+      display: grid;
+      grid-template-columns: 1fr 1fr;
+      column-gap: 12px;
+    }
+
+    /* ── Code block ── */
+    .code-block {
+      font-family: ui-monospace, 'Cascadia Code', Consolas, monospace;
+      font-size: 10px;
+      color: #79c0ff;
+      line-height: 1.6;
+      white-space: pre;
+    }
+
+    /* ── Tabs ── */
+    #tab-bar {
+      display: flex;
+      gap: 2px;
+      background: #161b22;
+      border-bottom: 1px solid #30363d;
+      padding: 0 12px;
+      flex-shrink: 0;
+    }
+    .tab-btn {
+      padding: 6px 16px;
+      border: none;
+      background: transparent;
+      color: #8b949e;
+      font-size: 0.78rem;
+      cursor: pointer;
+      border-bottom: 2px solid transparent;
+      margin-bottom: -1px;
+      transition: color 0.15s, border-color 0.15s;
+    }
+    .tab-btn:hover { color: #e6edf3; }
+    .tab-btn.active { color: #58a6ff; border-bottom-color: #58a6ff; }
+
+    .tab-panel { display: none; flex: 1; overflow: hidden; position: relative; }
+    .tab-panel.active { display: flex; flex-direction: column; }
+
+    /* ── Tooltip ── */
+    #tw-tooltip {
+      position: fixed;
+      z-index: 9999;
+      pointer-events: none;
+      background: #1c2333;
+      border: 1px solid #388bfd;
+      border-radius: 6px;
+      padding: 8px 12px;
+      max-width: 520px;
+      font-size: 11px;
+      line-height: 1.55;
+      color: #e6edf3;
+      box-shadow: 0 4px 18px rgba(0,0,0,0.5);
+      display: none;
+      white-space: pre-wrap;
+    }
+
+    /* ── File item hover ── */
+    .file-item { cursor: pointer; border-radius: 3px; padding: 2px 3px; margin: 0 -3px; text-decoration: underline; text-decoration-style: dotted; text-underline-offset: 3px; }
+    .file-item:hover { background: rgba(88,166,255,0.12); text-decoration-style: solid; }
+    .card-head[data-tip] { cursor: help; }
+    .card-head[data-tip]:hover { filter: brightness(1.12); }
+
+    /* ── D3 graph ── */
+    #deps-panel {
+      width: 0; flex-shrink: 0; overflow: hidden;
+      background: #161b22; border-left: 1px solid #30363d;
+      padding: 0; display: flex; flex-direction: column; gap: 6px;
+      font-size: 11px; line-height: 1.55; color: #e6edf3;
+      opacity: 0; pointer-events: none;
+      transition: opacity 0.2s ease, width 0.2s ease, padding 0.2s ease;
+    }
+    #deps-panel.visible { width: 240px; padding: 14px 12px; padding-top: 18px; opacity: 1; pointer-events: auto; overflow-y: auto; }
+    #deps-panel .dp-name { font-weight: 700; font-size: 13px; color: #58a6ff; margin-bottom: 4px; }
+    #deps-panel .dp-meta { color: #8b949e; font-size: 10px; margin-bottom: 8px; }
+    #deps-panel .dp-jsdoc { color: #c9d1d9; white-space: pre-wrap; margin-bottom: 8px; }
+    #deps-panel .dp-connected { color: #8b949e; white-space: pre-wrap; font-size: 10px; }
+    #deps-layout { display: flex; flex: 1; overflow: hidden; }
+    #deps-legend {
+      width: 180px; flex-shrink: 0;
+      background: #161b22; border-right: 1px solid #30363d;
+      padding: 0; overflow: hidden;
+      display: flex; flex-direction: column;
+    }
+    #deps-legend .leg-title {
+      font-size: 10px; font-weight: 600; color: #8b949e;
+      text-transform: uppercase; letter-spacing: 0.06em;
+      padding: 8px 10px 6px; flex-shrink: 0;
+      border-bottom: 1px solid #30363d;
+    }
+    #deps-legend-rows { padding: 6px 10px; display: flex; flex-direction: column; gap: 2px; overflow-y: auto; flex: 1; min-height: 0; }
+    #deps-legend .leg-row {
+      display: flex; align-items: center; gap: 8px;
+      padding: 5px 6px; border-radius: 5px;
+      cursor: pointer; user-select: none;
+    }
+    #deps-legend .leg-row:hover { background: rgba(255,255,255,0.07); }
+    #deps-legend .leg-row:hover .leg-label { color: #ffffff; }
+    #deps-legend .leg-row.leg-selected { background: rgba(255,255,255,0.12); }
+    #deps-legend .leg-row.leg-selected .leg-label { color: #ffffff; font-weight: 700; }
+    #deps-panel .dp-open-btn { margin-top: 12px; padding: 6px 10px; border: 1px solid #388bfd; background: transparent; color: #58a6ff; border-radius: 5px; font-size: 11px; cursor: pointer; width: 100%; }
+    #deps-panel .dp-open-btn:hover { background: rgba(56,139,253,0.15); }
+    #deps-legend .leg-dot {
+      width: 12px; height: 12px; border-radius: 50%; flex-shrink: 0;
+      border: 1.5px solid transparent;
+    }
+    #deps-legend .leg-label { font-size: 13px; color: #c9d1d9; font-family: system-ui; }
+    #deps-search-wrap {
+      padding: 10px 12px; flex-shrink: 0;
+      border-bottom: 1px solid #30363d;
+    }
+    #deps-search {
+      width: 100%; padding: 6px 8px; border-radius: 5px;
+      border: 1px solid #444c56; background: #2d333b; color: #e6edf3;
+      font-size: 11px; outline: none; display: block; box-sizing: border-box;
+    }
+    #deps-search::placeholder { color: #768390; }
+    #deps-search:focus { border-color: #388bfd; background: #353d47; }
+    #deps-search:focus { border-color: #388bfd; }
+    #deps-search-list {
+      display: none; position: absolute; left: 0; right: 0; top: 100%;
+      z-index: 200;
+      background: #161b22; border: 1px solid #388bfd; border-radius: 5px;
+      max-height: 220px; overflow-y: auto;
+      box-shadow: 0 4px 16px rgba(0,0,0,0.5);
+    }
+    #deps-search-list .sl-item {
+      padding: 6px 10px; font-size: 11px; font-family: ui-monospace, monospace;
+      cursor: pointer; color: #e6edf3; white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+    }
+    #deps-search-list .sl-item:hover, #deps-search-list .sl-item.sl-active { background: rgba(56,139,253,0.2); }
+    #deps-search-list .sl-item .sl-group { font-size: 9px; color: #8b949e; margin-left: 6px; }
+    #deps-viewport { flex: 1; min-width: 0; position: relative; overflow: hidden; }
+    #deps-viewport.dragging { cursor: grabbing; }
+    #deps-svg { width: 100%; height: 100%; opacity: 0; transition: opacity 0.4s ease; }
+    #deps-svg.settled { opacity: 1; }
+    #deps-loading {
+      position: absolute; inset: 0; display: flex; flex-direction: column;
+      align-items: center; justify-content: center; gap: 12px;
+      color: #8b949e; font-size: 0.8rem; pointer-events: none;
+    }
+    #deps-loading.hidden { display: none; }
+    .deps-spinner {
+      width: 32px; height: 32px; border-radius: 50%;
+      border: 3px solid #30363d; border-top-color: #58a6ff;
+      animation: spin 0.7s linear infinite;
+    }
+    @keyframes spin { to { transform: rotate(360deg); } }
+    .d3-node circle { stroke-width: 1.5; cursor: pointer; transition: fill 0.25s, stroke-width 0.25s, opacity 0.25s; }
+    .d3-node circle:hover { stroke-width: 3; filter: brightness(1.3); }
+    .d3-node text { font-size: 9.5px; fill: #e6edf3; pointer-events: none; font-family: ui-monospace, monospace; transition: opacity 0.25s; }
+    .d3-link { stroke-opacity: 0.45; fill: none; }
+  </style>
+</head>
+<body>
+  <header>
+    <h1>⬡ Testwise Architecture</h1>
+    <div class="meta">Generated ${esc(generatedAt)} &nbsp;·&nbsp; Refresh to update from source</div>
+  </header>
+
+  <div id="tab-bar">
+    <button class="tab-btn active" onclick="switchTab('arch')">Architecture</button>
+    <button class="tab-btn"        onclick="switchTab('deps')">Dependencies</button>
+    <div style="margin-left:auto;display:flex;gap:8px;align-items:center;padding:10px 8px 10px 0">
+    <button id="recenter-btn" class="hbtn" onclick="recenter()">⊙ Recenter</button>
+    <button id="clear-sel-btn" class="hbtn" onclick="clearSelection()">✕ Clear Selection</button>
+    <button id="export-btn" class="hbtn" onclick="exportPng()">⬇ Export PNG</button>
+    <button id="reload-btn" class="hbtn" onclick="location.reload()">↺ Refresh</button>
+    </div>
+  </div>
+
+  <!-- Architecture tab -->
+  <div id="tab-arch" class="tab-panel active">
+    <div id="viewport">
+      <div id="diagram">
+        <div class="top-row">
+          <div class="stack">
+            ${extCard}
+            ${cfgCard}
+            ${svcCard}
+          </div>
+          <div class="stack">
+            ${ifaceCard}
+            ${typeCard}
+          </div>
+          ${pipeCard}
+          ${genCard}
+          ${fixCard}
+          ${consCard}
+          <div class="stack">
+            ${scriptsCard}
+            ${mcpCard}
+          </div>
+        </div>
+        <div class="bot-row">
+          ${compCard}
+          ${ctrlCard}
+          ${helpCard}
+          <div class="stack">
+            ${ovrCard}
+            ${extPageCard}
+          </div>
+          ${devCard}
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <!-- Dependencies tab -->
+  <div id="tab-deps" class="tab-panel">
+    <div id="deps-layout">
+      <div id="deps-legend">
+        <div id="deps-search-wrap">
+          <div style="position:relative">
+            <input id="deps-search" type="text" placeholder="Search nodes..." autocomplete="new-password" spellcheck="false" autocorrect="off" autocapitalize="off" data-form-type="other"/>
+            <div id="deps-search-list"></div>
+          </div>
+        </div>
+        <div class="leg-title">Groups</div>
+        <div id="deps-legend-rows"></div>
+      </div>
+      <div id="deps-viewport">
+        <svg id="deps-svg"></svg>
+        <div id="deps-loading"><div class="deps-spinner"></div><span>Settling layout\u2026</span></div>
+      </div>
+      <div id="deps-panel"></div>
+    </div>
+  </div>
+
+  <!-- Shared tooltip -->
+  <div id="tw-tooltip"></div>
+
+  <script src="https://d3js.org/d3.v7.min.js"></script>
+  <script>
+    // ── Shared data (loaded async from /api/data to avoid any escaping issues) ──
+    let ROOT_PATH = '';
+    let TIPS = {};
+    let GRAPH_NODES = [];
+    let GRAPH_LINKS = [];
+
+    let selectedNode = null;
+    let selectedLegendGroup = null;
+    let selectedLegendRow = null;
+    let archIsCentered = true;
+    let depsIsCentered = false;
+    let _applyNodeHighlight = null;
+    let _legColors = {};
+
+    function updateButtons() {
+      const archActive = document.getElementById('tab-arch').classList.contains('active');
+      const recenterBtn = document.getElementById('recenter-btn');
+      const clearSelBtn = document.getElementById('clear-sel-btn');
+      if (archActive) {
+        recenterBtn.style.display = archIsCentered ? 'none' : 'inline-block';
+        clearSelBtn.style.display = 'none';
+      } else {
+        if (selectedNode || selectedLegendGroup) {
+          recenterBtn.style.display = 'none';
+          clearSelBtn.style.display = 'inline-block';
+        } else {
+          recenterBtn.style.display = depsIsCentered ? 'none' : 'inline-block';
+          clearSelBtn.style.display = 'none';
+        }
+      }
+    }
+
+    function openInVscode(filePath) {
+      window.location.href = 'vscode://file/' + filePath.replace(/\\\\/g, '/');
+    }
+
+    function clearSelection() {
+      selectedNode = null;
+      if (selectedLegendRow) {
+        selectedLegendRow.classList.remove('leg-selected');
+        selectedLegendRow.querySelector('.leg-dot').style.background = _legColors[selectedLegendGroup] + '55';
+        selectedLegendGroup = null;
+        selectedLegendRow = null;
+      }
+      if (_applyNodeHighlight) _applyNodeHighlight(null);
+      document.getElementById('deps-panel').classList.remove('visible');
+      recenter();
+      updateButtons();
+    }
+
+    fetch('/api/data')
+      .then(r => r.json())
+      .then(data => {
+        ROOT_PATH   = data.rootPath;
+        TIPS        = data.tips;
+        GRAPH_NODES = data.graphNodes;
+        GRAPH_LINKS = data.graphLinks;
+      })
+      .catch(err => console.error('Failed to load diagram data:', err));
+
+    // ── Tab switching ─────────────────────────────────────────────────────
+    function switchTab(name) {
+      document.querySelectorAll('.tab-btn').forEach((b, i) => {
+        const id = ['arch','deps'][i];
+        b.classList.toggle('active', id === name);
+      });
+      document.querySelectorAll('.tab-panel').forEach(p => {
+        p.classList.toggle('active', p.id === 'tab-' + name);
+      });
+      localStorage.setItem('tw-active-tab', name);
+      updateButtons();
+      if (name === 'arch') {
+        // fitToScreen recalculates scale and calls drawArrows — more reliable than rAF alone
+        requestAnimationFrame(() => requestAnimationFrame(fitToScreen));
+      } else if (name === 'deps') {
+        // Data may still be loading; wait for it then init
+        if (GRAPH_NODES.length > 0) {
+          initDepsGraph();
+        } else {
+          fetch('/api/data').then(r => r.json()).then(data => {
+            ROOT_PATH = data.rootPath; TIPS = data.tips;
+            GRAPH_NODES = data.graphNodes; GRAPH_LINKS = data.graphLinks;
+            initDepsGraph();
+          });
+        }
+      }
+    }
+
+    // Restore last active tab on load
+    const _savedTab = localStorage.getItem('tw-active-tab');
+    if (_savedTab && _savedTab !== 'arch') {
+      switchTab(_savedTab);
+    } else {
+      // Arch tab is active — fit and draw arrows after layout is fully painted
+      requestAnimationFrame(() => requestAnimationFrame(fitToScreen));
+    }
+
+    // ── Tooltip ───────────────────────────────────────────────────────────
+    const tooltip = document.getElementById('tw-tooltip');
+    function showTip(text, e) {
+      tooltip.textContent = text;
+      tooltip.style.display = 'block';
+      moveTip(e);
+    }
+    function moveTip(e) {
+      const pad = 14, margin = 8;
+      const tw = tooltip.offsetWidth, th = tooltip.offsetHeight;
+      const vw = window.innerWidth, vh = window.innerHeight;
+      // Prefer below-right; flip left if not enough room on right; flip above if not enough room below
+      let x = e.clientX + pad;
+      let y = e.clientY + pad;
+      if (x + tw > vw - margin) x = e.clientX - tw - pad;
+      if (y + th > vh - margin) y = e.clientY - th - pad;
+      // Clamp so tooltip never goes off the left or top edge
+      if (x < margin) x = margin;
+      if (y < margin) y = margin;
+      tooltip.style.left = x + 'px';
+      tooltip.style.top  = y + 'px';
+    }
+    function hideTip() { tooltip.style.display = 'none'; }
+
+    document.body.addEventListener('mouseover', e => {
+      // Don't interfere with D3 node tooltips in the deps graph
+      if (e.target.closest('#deps-svg')) return;
+      const el = e.target.closest('[data-tip]');
+      if (el) showTip(el.dataset.tip, e);
+      else hideTip();
+    });
+    document.body.addEventListener('mousemove', e => {
+      if (tooltip.style.display !== 'none') moveTip(e);
+    });
+    document.body.addEventListener('mouseout', e => {
+      if (e.target.closest('#deps-svg')) return;
+      if (!e.relatedTarget || !e.relatedTarget.closest('[data-tip]')) hideTip();
+    });
+
+    // ── Click file to open in VS Code ─────────────────────────────────────
+    document.body.addEventListener('click', e => {
+      const el = e.target.closest('.file-item[data-path]');
+      if (!el) return;
+      // normalise: forward-slashes → OS-native via URL encoding
+      const raw = el.dataset.path;
+      const uri = 'vscode://file/' + raw.replace(/\\\\/g, '/');
+      window.location.href = uri;
+    });
+
+    // ── Architecture viewport ─────────────────────────────────────────────
+    const viewport = document.getElementById('viewport');
+    const diagram  = document.getElementById('diagram');
+    let scale = 1, tx = 0, ty = 0;
+    let dragging = false, dragStartX = 0, dragStartY = 0, startTx = 0, startTy = 0;
+
+    function applyTransform() {
+      diagram.style.transform = \`translate(\${tx}px,\${ty}px) scale(\${scale})\`;
+    }
+
+    function fitToScreen() {
+      const vw = viewport.clientWidth, vh = viewport.clientHeight;
+      const dw = diagram.offsetWidth,  dh = diagram.offsetHeight;
+      scale = Math.min(vw / dw, vh / dh) * 0.92;
+      tx = (vw - dw * scale) / 2;
+      ty = Math.max((vh - dh * scale) / 2, 16);
+      applyTransform();
+      archIsCentered = true;
+      updateButtons();
+      requestAnimationFrame(drawArrows);
+    }
+
+    function recenter() {
+      const archActive = document.getElementById('tab-arch').classList.contains('active');
+      if (archActive) {
+        fitToScreen();
+      } else if (GRAPH_NODES.length > 0 && zoomBehaviour) {
+        // Fit deps graph to view
+        const svgEl = document.getElementById('deps-svg');
+        const W = svgEl.clientWidth || 1200, H = svgEl.clientHeight || 700;
+        const pad = 40;
+        const xs = GRAPH_NODES.map(d => d.x), ys = GRAPH_NODES.map(d => d.y);
+        const minX = Math.min(...xs), maxX = Math.max(...xs);
+        const minY = Math.min(...ys), maxY = Math.max(...ys);
+        const bw = maxX - minX || 1, bh = maxY - minY || 1;
+        const k = Math.min((W - pad * 2) / bw, (H - pad * 2) / bh, 2);
+        const tx2 = W / 2 - k * (minX + bw / 2);
+        const ty2 = H / 2 - k * (minY + bh / 2);
+        d3.select('#deps-svg').transition().duration(500)
+          .call(zoomBehaviour.transform, d3.zoomIdentity.translate(tx2, ty2).scale(k));
+        depsIsCentered = true;
+        updateButtons();
+      }
+    }
+
+    window.addEventListener('load', fitToScreen);
+    window.addEventListener('resize', () => {
+      if (document.getElementById('tab-arch').classList.contains('active')) fitToScreen();
+    });
+
+    viewport.addEventListener('wheel', (e) => {
+      e.preventDefault();
+      const rect = viewport.getBoundingClientRect();
+      const mx = e.clientX - rect.left, my = e.clientY - rect.top;
+      const delta = e.deltaY > 0 ? 0.92 : 1.08;
+      const ns = Math.min(Math.max(scale * delta, 0.05), 5);
+      tx = mx - (mx - tx) * (ns / scale);
+      ty = my - (my - ty) * (ns / scale);
+      scale = ns;
+      if (archIsCentered) { archIsCentered = false; updateButtons(); }
+      applyTransform();
+    }, { passive: false });
+
+    viewport.addEventListener('mousedown', (e) => {
+      dragging = true;
+      dragStartX = e.clientX; dragStartY = e.clientY;
+      startTx = tx; startTy = ty;
+      viewport.classList.add('dragging');
+    });
+    window.addEventListener('mousemove', (e) => {
+      if (!dragging) return;
+      tx = startTx + (e.clientX - dragStartX);
+      ty = startTy + (e.clientY - dragStartY);
+      if (archIsCentered) { archIsCentered = false; updateButtons(); }
+      applyTransform();
+    });
+    window.addEventListener('mouseup', () => {
+      dragging = false;
+      viewport.classList.remove('dragging');
+    });
+
+    // ── Arrow overlay ──────────────────────────────────────────────────────
+    function drawArrows() {
+      const old = document.getElementById('arrow-overlay');
+      if (old) old.remove();
+
+      const diagramEl = document.getElementById('diagram');
+      const dr = diagramEl.getBoundingClientRect();
+
+      // Convert a card's screen rect → diagram's own coordinate space (pre-transform)
+      function rel(id) {
+        const el = document.getElementById(id);
+        if (!el) return null;
+        const r = el.getBoundingClientRect();
+        const l = (r.left - dr.left) / scale;
+        const t = (r.top  - dr.top)  / scale;
+        const w = r.width  / scale;
+        const h = r.height / scale;
+        return { l, t, r: l + w, b: t + h, cx: l + w / 2, cy: t + h / 2 };
+      }
+
+      // ── Routing corridors ───────────────────────────────────────────────
+      const topRowEl = document.querySelector('.top-row');
+      const botRowEl = document.querySelector('.bot-row');
+      const aboveY   = topRowEl ? (topRowEl.getBoundingClientRect().top    - dr.top) / scale - 14 : 10;
+      const aboveYHi = aboveY - 14;
+      const belowY   = botRowEl ? (botRowEl.getBoundingClientRect().bottom - dr.top) / scale + 18 : 9999;
+      const belowYLo = belowY + 14;
+      // midY: horizontal corridor in the gap between top and bottom rows
+      const midY = (topRowEl && botRowEl)
+        ? ((topRowEl.getBoundingClientRect().bottom + botRowEl.getBoundingClientRect().top) / 2 - dr.top) / scale
+        : 500;
+      const midYLo = midY + 14;
+
+      // gapX12: vertical corridor between left-stack and iface/types-stack
+      // (guaranteed clear because nothing occupies this x between the two stacks)
+      const rSvcEl   = rel('sec-svc');
+      const rIfaceEl = rel('sec-iface');
+      const gapX12   = rSvcEl && rIfaceEl ? (rSvcEl.r + rIfaceEl.l) / 2 : 200;
+
+      // rightMarginX: x corridor to the RIGHT of ALL cards (both rows)
+      const everyId = ['sec-ext','sec-cfg','sec-svc','sec-iface','sec-types',
+                       'sec-pipe','sec-gen','sec-fix','sec-cons','sec-scripts','sec-mcp',
+                       'sec-comp','sec-ctrl','sec-help','sec-ovr','sec-pext','sec-dev'];
+      let rmx = 0;
+      for (const id of everyId) { const rr = rel(id); if (rr) rmx = Math.max(rmx, rr.r); }
+      const rightMarginX  = rmx + 20;   // first right-margin corridor
+      const rightMarginX2 = rmx + 36;   // second corridor (offset so two arrows don't overlap)
+
+      // ── Connection table ─────────────────────────────────────────────────
+      // Strategies:
+      //   'lr'       – adjacent cards, Z-bend in horizontal flex gap
+      //   'gap12'    – exit source right → gapX12 → up to aboveY  → right to target cx → down to target top
+      //   'gap12-hi' – same but uses aboveYHi
+      //   'rm'       – exit source right → rightMarginX  → up to aboveY  → left to (target.cx+8) → down to target top
+      //   'rm2'      – exit source right → rightMarginX2 → up to aboveYHi → left to target.cx   → down to target top
+      //
+      // Safety proofs:
+      //   'lr'       – vertical segment sits inside the flex gap; no card is there             ✓
+      //   'gap12'    – gapX12 < iface.l and > svc.r; nothing occupies that x between y=f.cy  ✓
+      //              – aboveY is 14px above top-row top; horizontal at aboveY clears all boxes ✓
+      //   'rm'/'rm2' – rightMarginX > ALL card right edges (both rows); vertical is always clear ✓
+      //              – aboveY / aboveYHi are above top-row top                                  ✓
+      const CONNS = [
+        ['sec-pipe',    'sec-gen',     '#d4910a', 'lr',   false],
+        ['sec-gen',     'sec-fix',     '#c9c258', 'lr',   false],
+        ['sec-fix',     'sec-cons',    '#4a90d9', 'lr',   false],
+        ['sec-iface',   'sec-pipe',    '#5a8abf', 'lr',   true ],
+        ['sec-svc',     'sec-pipe',    '#9b59b6', 'gap12',true ],
+        ['sec-ext',     'sec-fix',     '#3fb950', 'gap12-hi', true ],
+        ['sec-ovr',     'sec-fix',     '#c0392b', 'rm',       false],
+        ['sec-pext',    'sec-fix',     '#16a085', 'rm2',      false],
+        ['sec-comp',    'sec-ctrl',    '#4a90d9', 'lr',   true ],
+        ['sec-help',    'sec-pext',    '#27ae60', 'lr',   true ],
+        ['sec-scripts', 'sec-mcp',     '#f97316', 'tb',       false],
+      ];
+
+      const paths = [];
+      for (const [fid, tid, color, strat, dashed] of CONNS) {
+        const f = rel(fid), t = rel(tid);
+        if (!f || !t) continue;
+        let pts;
+        if (strat === 'lr') {
+          const midX = (f.r + t.l) / 2;
+          pts = [[f.r, f.cy], [midX, f.cy], [midX, t.cy], [t.l, t.cy]];
+        } else if (strat === 'tb') {
+          // straight top→bottom between vertically stacked cards
+          pts = [[f.cx, f.b], [f.cx, t.t]];
+        } else if (strat === 'above-tb') {
+          // exit source top, go above top-row, travel right to target cx, drop down
+          pts = [[f.cx, f.t], [f.cx, aboveYHi], [t.cx + 8, aboveYHi], [t.cx + 8, t.t]];
+        } else if (strat === 'bm') {
+          // exit source bottom → below all bottom-row cards → right margin → above top-row → target
+          pts = [[f.cx, f.b], [f.cx, belowY], [rightMarginX, belowY], [rightMarginX, aboveY], [t.cx + 8, aboveY], [t.cx + 8, t.t]];
+        } else if (strat === 'bm2') {
+          pts = [[f.cx, f.b], [f.cx, belowYLo], [rightMarginX2, belowYLo], [rightMarginX2, aboveYHi], [t.cx, aboveYHi], [t.cx, t.t]];
+        } else if (strat === 'gap-row') {
+          // exit source top → inter-row gap → left toward target cx → up into target
+          pts = [[f.cx, f.t], [f.cx, midY], [t.cx + 8, midY], [t.cx + 8, t.b]];
+        } else if (strat === 'gap-row2') {
+          pts = [[f.cx, f.t], [f.cx, midYLo], [t.cx, midYLo], [t.cx, t.b]];
+        } else if (strat === 'gap12') {
+          pts = [[f.r, f.cy], [gapX12, f.cy], [gapX12, aboveY], [t.cx, aboveY], [t.cx, t.t]];
+        } else if (strat === 'gap12-hi') {
+          pts = [[f.r, f.cy], [gapX12, f.cy], [gapX12, aboveYHi], [t.cx, aboveYHi], [t.cx, t.t]];
+        } else if (strat === 'rm') {
+          // Exit bottom → belowY (clear) → rightMarginX (clear) → aboveY (clear) → target
+          pts = [[f.cx, f.b], [f.cx, belowY], [rightMarginX, belowY], [rightMarginX, aboveY], [t.cx + 8, aboveY], [t.cx + 8, t.t]];
+        } else if (strat === 'rm2') {
+          pts = [[f.cx, f.b], [f.cx, belowYLo], [rightMarginX2, belowYLo], [rightMarginX2, aboveYHi], [t.cx, aboveYHi], [t.cx, t.t]];
+        }
+        if (pts) paths.push({ pts, color, label: '', dashed });
+      }
+
+      const NS = 'http://www.w3.org/2000/svg';
+      const svg = document.createElementNS(NS, 'svg');
+      svg.id = 'arrow-overlay';
+      svg.setAttribute('style', 'position:absolute;top:0;left:0;overflow:visible;pointer-events:none;z-index:0;');
+      svg.setAttribute('width',  diagramEl.scrollWidth);
+      svg.setAttribute('height', diagramEl.scrollHeight);
+
+      // Define arrowhead markers per colour
+      const defs = document.createElementNS(NS, 'defs');
+      for (const c of [...new Set(paths.map(p => p.color))]) {
+        const mk = document.createElementNS(NS, 'marker');
+        const mid = 'ah' + c.replace(/#/g, '');
+        mk.setAttribute('id', mid);
+        mk.setAttribute('markerWidth',  '7');
+        mk.setAttribute('markerHeight', '7');
+        mk.setAttribute('refX', '6');
+        mk.setAttribute('refY', '3.5');
+        mk.setAttribute('orient', 'auto');
+        const poly = document.createElementNS(NS, 'polygon');
+        poly.setAttribute('points', '0 0, 7 3.5, 0 7');
+        poly.setAttribute('fill', c);
+        mk.appendChild(poly);
+        defs.appendChild(mk);
+      }
+      svg.appendChild(defs);
+
+      for (const { pts, color, label, dashed } of paths) {
+        const markId = 'url(#ah' + color.replace(/#/g, '') + ')';
+
+        const path = document.createElementNS(NS, 'path');
+        const d = 'M ' + pts.map(([x, y]) => x.toFixed(1) + ' ' + y.toFixed(1)).join(' L ');
+        path.setAttribute('d', d);
+        path.setAttribute('fill', 'none');
+        path.setAttribute('stroke', color);
+        path.setAttribute('stroke-width', '1.5');
+        path.setAttribute('stroke-opacity', '0.75');
+        if (dashed) path.setAttribute('stroke-dasharray', '5,3');
+        path.setAttribute('marker-end', markId);
+        svg.appendChild(path);
+
+        if (label && pts.length >= 2) {
+          // Place label at the midpoint of the longest segment
+          let bestIdx = 0, bestLen = 0;
+          for (let i = 0; i < pts.length - 1; i++) {
+            const dx = pts[i+1][0] - pts[i][0], dy = pts[i+1][1] - pts[i][1];
+            const len = Math.sqrt(dx*dx + dy*dy);
+            if (len > bestLen) { bestLen = len; bestIdx = i; }
+          }
+          const lx = ((pts[bestIdx][0] + pts[bestIdx+1][0]) / 2).toFixed(1);
+          const ly = ((pts[bestIdx][1] + pts[bestIdx+1][1]) / 2 - 4).toFixed(1);
+          const txt = document.createElementNS(NS, 'text');
+          txt.setAttribute('x', lx);
+          txt.setAttribute('y', ly);
+          txt.setAttribute('fill', color);
+          txt.setAttribute('font-size', '9');
+          txt.setAttribute('text-anchor', 'middle');
+          txt.setAttribute('font-family', 'system-ui, sans-serif');
+          txt.setAttribute('opacity', '0.85');
+          txt.textContent = label;
+          svg.appendChild(txt);
+        }
+      }
+
+      diagramEl.appendChild(svg);
+    }
+
+    async function exportPng() {
+      const btn = document.getElementById('export-btn');
+      btn.disabled = true; btn.textContent = 'Exporting…';
+      try {
+        const archActive = document.getElementById('tab-arch').classList.contains('active');
+        if (archActive) {
+          // Architecture tab — use html2canvas on the diagram element
+          const saved = diagram.style.transform;
+          diagram.style.transform = 'none';
+          await new Promise(r => requestAnimationFrame(r));
+          const canvas = await html2canvas(diagram, {
+            backgroundColor: '#0d1117',
+            scale: 2,
+            useCORS: true,
+            logging: false,
+          });
+          diagram.style.transform = saved;
+          canvas.toBlob((blob) => {
+            const a = document.createElement('a');
+            a.href = URL.createObjectURL(blob);
+            a.download = 'testwise-architecture.png';
+            a.click();
+            URL.revokeObjectURL(a.href);
+            btn.disabled = false; btn.textContent = '⬇ Export PNG';
+          }, 'image/png');
+        } else {
+          // Dependencies tab — serialize the D3 SVG to a canvas
+          const svgEl = document.getElementById('deps-svg');
+          const { width, height } = svgEl.getBoundingClientRect();
+          // Clone and stamp explicit dimensions so the serialized SVG renders at viewport size
+          const clone = svgEl.cloneNode(true);
+          clone.setAttribute('width', width);
+          clone.setAttribute('height', height);
+          clone.setAttribute('overflow', 'hidden');
+          // Embed the font so text renders correctly
+          const style = document.createElement('style');
+          style.textContent = 'text { font-family: system-ui, sans-serif; font-size: 11px; fill: #c9d1d9; }';
+          clone.insertBefore(style, clone.firstChild);
+          const serializer = new XMLSerializer();
+          const svgStr = serializer.serializeToString(clone);
+          const svgBlob = new Blob([svgStr], { type: 'image/svg+xml;charset=utf-8' });
+          const url = URL.createObjectURL(svgBlob);
+          const img = new Image();
+          img.onload = () => {
+            const canvas = document.createElement('canvas');
+            const scale = 2;
+            canvas.width  = width  * scale;
+            canvas.height = height * scale;
+            const ctx = canvas.getContext('2d');
+            ctx.fillStyle = '#0d1117';
+            ctx.fillRect(0, 0, canvas.width, canvas.height);
+            ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
+            URL.revokeObjectURL(url);
+            canvas.toBlob((blob) => {
+              const a = document.createElement('a');
+              a.href = URL.createObjectURL(blob);
+              a.download = 'testwise-dependencies.png';
+              a.click();
+              URL.revokeObjectURL(a.href);
+              btn.disabled = false; btn.textContent = '⬇ Export PNG';
+            }, 'image/png');
+          };
+          img.onerror = (e) => {
+            URL.revokeObjectURL(url);
+            throw new Error('SVG render failed');
+          };
+          img.src = url;
+        }
+      } catch (e) {
+        alert('Export error: ' + e.message);
+        btn.disabled = false; btn.textContent = '⬇ Export PNG';
+      }
+    }
+
+    // ── D3 Dependency Graph ────────────────────────────────────────────────
+    // Data loaded via fetch('/api/data') above — GRAPH_NODES / GRAPH_LINKS
+    // are populated before initDepsGraph() is called.
+
+    let depsInited = false;
+    let zoomBehaviour = null;
+    function initDepsGraph() {
+      if (depsInited) return;
+      depsInited = true;
+      if (!GRAPH_NODES || GRAPH_NODES.length === 0) { depsInited = false; return; }
+
+      const svgEl = document.getElementById('deps-svg');
+      const W = svgEl.clientWidth  || 1200;
+      const H = svgEl.clientHeight || 700;
+
+      // Count in/out degree for sizing nodes
+      const inDeg  = new Map(GRAPH_NODES.map(n => [n.id, 0]));
+      const outDeg = new Map(GRAPH_NODES.map(n => [n.id, 0]));
+      for (const l of GRAPH_LINKS) {
+        outDeg.set(l.source, (outDeg.get(l.source) || 0) + 1);
+        inDeg.set(l.target,  (inDeg.get(l.target)  || 0) + 1);
+      }
+      // Total degree drives node radius
+      const totalDeg = id => (inDeg.get(id) || 0) + (outDeg.get(id) || 0);
+      const nodeR    = d  => 4 + Math.min(totalDeg(d.id) * 0.9, 18);
+
+      // Build index so d3 can use string ids
+      const nodeById = new Map(GRAPH_NODES.map(n => [n.id, n]));
+
+      const svg = d3.select('#deps-svg');
+      svg.selectAll('*').remove();
+      const g = svg.append('g');
+
+      zoomBehaviour = d3.zoom().scaleExtent([0.02, 6]).on('zoom', e => {
+        g.attr('transform', e.transform);
+        if (e.sourceEvent) { depsIsCentered = false; updateButtons(); }
+      });
+      svg.call(zoomBehaviour);
+
+      // Legend sidebar (HTML)
+      const groups = [...new Set(GRAPH_NODES.map(n => n.group))].sort();
+      const legendEl = document.getElementById('deps-legend-rows');
+      legendEl.innerHTML = '';
+      function applyLegendHighlight(grp) {
+        if (grp) {
+          node.select('circle').transition('hl').duration(150)
+            .attr('fill', n => n.group === grp ? n.color + 'ff' : n.color + '0d')
+            .attr('stroke-width', n => n.group === grp ? 2.5 : 0.5);
+          node.select('text').transition('hl').duration(150)
+            .attr('opacity', n => n.group === grp ? 1 : 0.05);
+          link.transition('hl').duration(150).attr('stroke-opacity', 0).attr('marker-end', 'none');
+        } else {
+          node.select('circle').transition('hl').duration(150)
+            .attr('fill', n => n.color + 'bb').attr('stroke-width', 1.8);
+          node.select('text').transition('hl').duration(150).attr('opacity', 1);
+        }
+      }
+
+      function applyNodeHighlight(d) {
+        if (d) {
+          const neighbours = new Set([d.id]);
+          GRAPH_LINKS.forEach(l => {
+            const sid = typeof l.source === 'object' ? l.source.id : l.source;
+            const tid = typeof l.target === 'object' ? l.target.id : l.target;
+            if (sid === d.id) neighbours.add(tid);
+            if (tid === d.id) neighbours.add(sid);
+          });
+          node.select('circle').transition('hl').duration(200)
+            .attr('fill', n => neighbours.has(n.id) ? n.color + 'ee' : n.color + '22')
+            .attr('stroke-width', n => n.id === d.id ? 2.5 : neighbours.has(n.id) ? 2 : 1);
+          node.select('text').transition('hl').duration(200)
+            .attr('opacity', n => neighbours.has(n.id) ? 1 : 0.2);
+          link.transition('hl').duration(200)
+            .attr('stroke-opacity', l => {
+              const sid = typeof l.source === 'object' ? l.source.id : l.source;
+              const tid = typeof l.target === 'object' ? l.target.id : l.target;
+              return (sid === d.id || tid === d.id) ? 1 : 0;
+            })
+            .attr('stroke-dasharray', 'none')
+            .attr('stroke-width', l => {
+              const sid = typeof l.source === 'object' ? l.source.id : l.source;
+              const tid = typeof l.target === 'object' ? l.target.id : l.target;
+              return (sid === d.id || tid === d.id) ? 2 : 1.5;
+            })
+            .attr('marker-end', l => {
+              const sid = typeof l.source === 'object' ? l.source.id : l.source;
+              const tid = typeof l.target === 'object' ? l.target.id : l.target;
+              return (sid === d.id || tid === d.id) ? 'url(#deps-arrow)' : 'none';
+            });
+        } else {
+          node.select('circle').transition('hl').duration(200)
+            .attr('fill', n => n.color + 'bb').attr('stroke-width', 1.8);
+          node.select('text').transition('hl').duration(200).attr('opacity', 1).attr('fill', '#e6edf3').attr('font-weight', '500');
+          link.transition('hl').duration(200).attr('stroke-opacity', 0).attr('stroke-dasharray', 'none').attr('stroke-width', 1.5).attr('marker-end', 'none');
+        }
+      }
+      _applyNodeHighlight = applyNodeHighlight;
+
+      function showNodePanel(d, showOpenBtn = false) {
+        const neighbours = new Set([d.id]);
+        GRAPH_LINKS.forEach(l => {
+          const sid = typeof l.source === 'object' ? l.source.id : l.source;
+          const tid = typeof l.target === 'object' ? l.target.id : l.target;
+          if (sid === d.id) neighbours.add(tid);
+          if (tid === d.id) neighbours.add(sid);
+        });
+        const connectedNames = GRAPH_NODES
+          .filter(n => neighbours.has(n.id) && n.id !== d.id)
+          .map(n => n.name).sort();
+        const jsdoc = TIPS[d.name] || '';
+        const safePath = d.path.replace(/\\\\/g, '/');
+        const panel = document.getElementById('deps-panel');
+        panel.innerHTML =
+          \`<div class="dp-name">\${d.name}</div>\` +
+          \`<div class="dp-meta">Imports: \${outDeg.get(d.id)||0} &nbsp;&middot;&nbsp; Imported by: \${inDeg.get(d.id)||0}</div>\` +
+          (jsdoc ? \`<div class="dp-jsdoc">\${jsdoc}</div>\` : '') +
+          \`<div class="dp-connected"><strong>Connected (\${connectedNames.length}):</strong>\\n\${connectedNames.join('\\n') || '\u2014'}</div>\` +
+          (showOpenBtn ? \`<button class="dp-open-btn" onclick="openInVscode('\${safePath}')">&#8599; Open File</button>\` : '');
+        panel.classList.add('visible');
+      }
+
+      function zoomToNodes(nodeList) {
+        const pad = 80;
+        const xs = nodeList.map(d => d.x), ys = nodeList.map(d => d.y);
+        const minX = Math.min(...xs), maxX = Math.max(...xs);
+        const minY = Math.min(...ys), maxY = Math.max(...ys);
+        const bw = maxX - minX || 1, bh = maxY - minY || 1;
+        const k = Math.min((W - pad * 2) / bw, (H - pad * 2) / bh, 4);
+        const tx2 = W / 2 - k * (minX + bw / 2);
+        const ty2 = H / 2 - k * (minY + bh / 2);
+        svg.transition().duration(500)
+          .call(zoomBehaviour.transform, d3.zoomIdentity.translate(tx2, ty2).scale(k));
+        depsIsCentered = false;
+        updateButtons();
+      }
+
+      const legColors = _legColors;
+      groups.forEach(grp => {
+        const color = (nodeById.get(GRAPH_NODES.find(n => n.group === grp)?.id) || {}).color || '#888';
+        legColors[grp] = color;
+        _legColors[grp] = color;
+        const row = document.createElement('div');
+        row.className = 'leg-row';
+        row.innerHTML = \`<span class="leg-dot" style="background:\${color}55;border-color:\${color}"></span><span class="leg-label">\${grp}</span>\`;
+        row.addEventListener('click', () => {
+          if (!document.getElementById('deps-svg').classList.contains('settled')) return;
+          if (selectedLegendGroup === grp) {
+            row.classList.remove('leg-selected');
+            row.querySelector('.leg-dot').style.background = color + '55';
+            selectedLegendGroup = null;
+            selectedLegendRow = null;
+            if (selectedNode) applyNodeHighlight(selectedNode); else applyLegendHighlight(null);
+          } else {
+            if (selectedLegendRow) {
+              selectedLegendRow.classList.remove('leg-selected');
+              selectedLegendRow.querySelector('.leg-dot').style.background = legColors[selectedLegendGroup] + '55';
+            }
+            selectedNode = null;
+            selectedLegendGroup = grp;
+            selectedLegendRow = row;
+            row.classList.add('leg-selected');
+            row.querySelector('.leg-dot').style.background = color + 'cc';
+            applyLegendHighlight(grp);
+            const groupNodes = GRAPH_NODES.filter(n => n.group === grp);
+            if (groupNodes.length) zoomToNodes(groupNodes);
+          }
+          // Close side panel when switching legend selection
+          document.getElementById('deps-panel').classList.remove('visible');
+          updateButtons();
+        });
+        row.addEventListener('mouseover', () => {
+          if (!document.getElementById('deps-svg').classList.contains('settled')) return;
+          if (selectedLegendGroup || selectedNode) return;
+          row.querySelector('.leg-dot').style.background = color + 'cc';
+          applyLegendHighlight(grp);
+        });
+        row.addEventListener('mouseout', () => {
+          if (selectedLegendGroup || selectedNode) return;
+          row.querySelector('.leg-dot').style.background = color + '55';
+          applyLegendHighlight(null);
+        });
+        legendEl.appendChild(row);
+      });
+
+      // ── Search box ────────────────────────────────────────────────────
+      const searchInput = document.getElementById('deps-search');
+      const searchList  = document.getElementById('deps-search-list');
+      const sortedNodes = [...GRAPH_NODES].sort((a, b) => a.name.localeCompare(b.name));
+
+      function selectNodeById(id) {
+        const d = GRAPH_NODES.find(n => n.id === id);
+        if (!d) return;
+        // Clear legend selection
+        if (selectedLegendRow) {
+          selectedLegendRow.classList.remove('leg-selected');
+          selectedLegendRow.querySelector('.leg-dot').style.background = _legColors[selectedLegendGroup] + '55';
+          selectedLegendGroup = null;
+          selectedLegendRow = null;
+        }
+        selectedNode = d;
+        applyNodeHighlight(d);
+        showNodePanel(d, true);
+        const neighbours = new Set([d.id]);
+        GRAPH_LINKS.forEach(l => {
+          const sid = typeof l.source === 'object' ? l.source.id : l.source;
+          const tid = typeof l.target === 'object' ? l.target.id : l.target;
+          if (sid === d.id) neighbours.add(tid);
+          if (tid === d.id) neighbours.add(sid);
+        });
+        const relatedNodes = GRAPH_NODES.filter(n => neighbours.has(n.id));
+        if (relatedNodes.length) zoomToNodes(relatedNodes);
+        updateButtons();
+      }
+
+      function renderSearchList(q) {
+        const matches = q.length === 0 ? [] :
+          sortedNodes.filter(n => n.name.toLowerCase().includes(q.toLowerCase())).slice(0, 50);
+        if (matches.length === 0) { searchList.style.display = 'none'; return; }
+        searchList.innerHTML = matches.map((n, i) =>
+          \`<div class="sl-item" data-id="\${n.id}" data-idx="\${i}">\${n.name}<span class="sl-group">\${n.group}</span></div>\`
+        ).join('');
+        searchList.style.display = 'block';
+        searchList.querySelectorAll('.sl-item').forEach(el => {
+          el.addEventListener('mousedown', ev => {
+            ev.preventDefault();
+            searchInput.value = '';
+            searchInput.blur();
+            searchList.style.display = 'none';
+            if (document.getElementById('deps-svg').classList.contains('settled')) {
+              selectNodeById(el.dataset.id);
+            }
+          });
+        });
+      }
+
+      searchInput.addEventListener('input', () => renderSearchList(searchInput.value));
+      searchInput.addEventListener('blur', () => setTimeout(() => { searchList.style.display = 'none'; }, 150));
+      searchInput.addEventListener('focus', () => { if (searchInput.value) renderSearchList(searchInput.value); });
+      // Keyboard navigation
+      searchInput.addEventListener('keydown', ev => {
+        const items = searchList.querySelectorAll('.sl-item');
+        const active = searchList.querySelector('.sl-active');
+        if (ev.key === 'ArrowDown') {
+          ev.preventDefault();
+          const next = active ? active.nextElementSibling : items[0];
+          if (active) active.classList.remove('sl-active');
+          if (next) { next.classList.add('sl-active'); next.scrollIntoView({ block: 'nearest' }); }
+        } else if (ev.key === 'ArrowUp') {
+          ev.preventDefault();
+          const prev = active ? active.previousElementSibling : items[items.length - 1];
+          if (active) active.classList.remove('sl-active');
+          if (prev) { prev.classList.add('sl-active'); prev.scrollIntoView({ block: 'nearest' }); }
+        } else if (ev.key === 'Enter') {
+          ev.preventDefault();
+          const target = active || items[0];
+          if (target) {
+            searchInput.value = '';
+            searchInput.blur();
+            searchList.style.display = 'none';
+            if (document.getElementById('deps-svg').classList.contains('settled')) {
+              selectNodeById(target.dataset.id);
+            }
+          }
+        } else if (ev.key === 'Escape') {
+          searchInput.value = '';
+          searchInput.blur();
+          searchList.style.display = 'none';
+        }
+      });
+
+      // Stats label
+      svg.append('text')
+        .attr('x', W - 8).attr('y', 18)
+        .attr('fill', '#6e8098').attr('font-size', '10px').attr('text-anchor', 'end')
+        .attr('font-family', 'system-ui')
+        .text(\`\${GRAPH_NODES.length} nodes · \${GRAPH_LINKS.length} edges\`);
+
+      svg.append('defs').append('marker')
+        .attr('id', 'deps-arrow')
+        .attr('viewBox', '0 -4 8 8').attr('refX', 8).attr('refY', 0)
+        .attr('markerWidth', 5).attr('markerHeight', 5).attr('orient', 'auto')
+        .append('path').attr('d', 'M0,-4L8,0L0,4').attr('fill', '#5a7a9a');
+
+      const link = g.append('g').selectAll('line')
+        .data(GRAPH_LINKS).join('line')
+        .attr('stroke', '#7ca8cc').attr('stroke-width', 1.5)
+        .attr('stroke-opacity', 0);
+
+      const node = g.append('g').selectAll('g')
+        .data(GRAPH_NODES).join('g')
+        .attr('class', 'd3-node');
+
+      // Radius scaled by total degree (imports + imported-by)
+      node.append('circle')
+        .attr('r', d => nodeR(d))
+        .attr('fill', d => d.color + 'bb').attr('stroke', d => d.color).attr('stroke-width', 1.8);
+
+      node.append('text').attr('dx', d => nodeR(d) + 3)
+        .attr('dy', 4).attr('font-weight', '500').text(d => d.name);
+
+      // Node hover / click / selection
+      node.on('mouseover', (ev, d) => {
+        if (!document.getElementById('deps-svg').classList.contains('settled')) return;
+        if (selectedNode) {
+          if (selectedNode.id === d.id) return;
+          // Compute selected node neighbours (keep solid) and hovered neighbours (dotted)
+          const selNeighbours = new Set([selectedNode.id]);
+          const hovNeighbours = new Set([d.id]);
+          GRAPH_LINKS.forEach(l => {
+            const sid = typeof l.source === 'object' ? l.source.id : l.source;
+            const tid = typeof l.target === 'object' ? l.target.id : l.target;
+            if (sid === selectedNode.id) selNeighbours.add(tid);
+            if (tid === selectedNode.id) selNeighbours.add(sid);
+            if (sid === d.id) hovNeighbours.add(tid);
+            if (tid === d.id) hovNeighbours.add(sid);
+          });
+          link.transition('hover').duration(100)
+            .attr('stroke-opacity', l => {
+              const sid = typeof l.source === 'object' ? l.source.id : l.source;
+              const tid = typeof l.target === 'object' ? l.target.id : l.target;
+              const isSel = (sid === selectedNode.id || tid === selectedNode.id);
+              const isHov = (sid === d.id || tid === d.id);
+              return (isSel || isHov) ? (isSel ? 1 : 0.7) : 0;
+            })
+            .attr('stroke-dasharray', l => {
+              const sid = typeof l.source === 'object' ? l.source.id : l.source;
+              const tid = typeof l.target === 'object' ? l.target.id : l.target;
+              const isSel = (sid === selectedNode.id || tid === selectedNode.id);
+              return isSel ? 'none' : '5,3';
+            })
+            .attr('stroke-width', l => {
+              const sid = typeof l.source === 'object' ? l.source.id : l.source;
+              const tid = typeof l.target === 'object' ? l.target.id : l.target;
+              return (sid === selectedNode.id || tid === selectedNode.id) ? 2 : 1.5;
+            })
+            .attr('marker-end', l => {
+              const sid = typeof l.source === 'object' ? l.source.id : l.source;
+              const tid = typeof l.target === 'object' ? l.target.id : l.target;
+              return (sid === selectedNode.id || tid === selectedNode.id) ? 'url(#deps-arrow)' : 'none';
+            });
+          // Brighten hovered node + its neighbours; keep selected node bright; dim rest
+          const allVisible = new Set([...selNeighbours, ...hovNeighbours]);
+          node.select('circle').transition('hover').duration(100)
+            .attr('fill', n => {
+              if (selNeighbours.has(n.id)) return n.color + (n.id === selectedNode.id ? 'ff' : 'ee');
+              if (hovNeighbours.has(n.id)) return n.color + 'cc';
+              return n.color + '15';
+            })
+            .attr('stroke-width', n => {
+              if (n.id === selectedNode.id) return 2.5;
+              if (n.id === d.id) return 2;
+              return hovNeighbours.has(n.id) ? 1.5 : 0.5;
+            });
+          node.select('text').transition('hover').duration(100)
+            .attr('opacity', n => allVisible.has(n.id) ? 1 : 0.12)
+            .attr('fill', n => hovNeighbours.has(n.id) && !selNeighbours.has(n.id) ? '#fff' : '#e6edf3')
+            .attr('font-weight', n => (n.id === d.id || hovNeighbours.has(n.id)) ? '700' : '500');
+          return;
+        }
+        if (selectedLegendGroup) {
+          // Legend is selected — show this node's links + brighten hovered node text
+          const neighbours = new Set([d.id]);
+          GRAPH_LINKS.forEach(l => {
+            const sid = typeof l.source === 'object' ? l.source.id : l.source;
+            const tid = typeof l.target === 'object' ? l.target.id : l.target;
+            if (sid === d.id) neighbours.add(tid);
+            if (tid === d.id) neighbours.add(sid);
+          });
+          node.select('text').transition('hover').duration(100)
+            .attr('opacity', n => neighbours.has(n.id) ? 1 : (n.group === selectedLegendGroup ? 0.3 : 0.05))
+            .attr('font-weight', n => n.id === d.id ? '700' : '500');
+          link.transition('hover').duration(100)
+            .attr('stroke-opacity', l => {
+              const sid = typeof l.source === 'object' ? l.source.id : l.source;
+              const tid = typeof l.target === 'object' ? l.target.id : l.target;
+              return (sid === d.id || tid === d.id) ? 0.8 : 0;
+            })
+            .attr('stroke-dasharray', 'none')
+            .attr('stroke-width', 1.8)
+            .attr('marker-end', l => {
+              const sid = typeof l.source === 'object' ? l.source.id : l.source;
+              const tid = typeof l.target === 'object' ? l.target.id : l.target;
+              return (sid === d.id || tid === d.id) ? 'url(#deps-arrow)' : 'none';
+            });
+          showNodePanel(d);
+          return;
+        }
+        applyNodeHighlight(d);
+        showNodePanel(d);
+      })
+      .on('mouseout', () => {
+        if (selectedNode) {
+          // Restore selected node highlight (remove hover dotted lines)
+          applyNodeHighlight(selectedNode);
+          return;
+        }
+        document.getElementById('deps-panel').classList.remove('visible');
+        if (selectedLegendGroup) {
+          // Restore legend highlight — reset links and text brightening
+          node.select('text').transition('hover').duration(100)
+            .attr('opacity', n => n.group === selectedLegendGroup ? 1 : 0.05)
+            .attr('font-weight', '500');
+          link.transition('hover').duration(100).attr('stroke-opacity', 0).attr('marker-end', 'none').attr('stroke-dasharray', 'none');
+        } else {
+          applyNodeHighlight(null);
+        }
+      })
+      .on('click', (ev, d) => {
+        ev.stopPropagation();
+        if (!document.getElementById('deps-svg').classList.contains('settled')) return;
+        if (selectedNode && selectedNode.id === d.id) {
+          selectedNode = null;
+          if (selectedLegendGroup) applyLegendHighlight(selectedLegendGroup);
+          else applyNodeHighlight(null);
+          document.getElementById('deps-panel').classList.remove('visible');
+          updateButtons();
+        } else {
+          selectedNode = d;
+          // Clear any legend selection
+          if (selectedLegendRow) {
+            selectedLegendRow.classList.remove('leg-selected');
+            selectedLegendRow.querySelector('.leg-dot').style.background = legColors[selectedLegendGroup] + '55';
+            selectedLegendGroup = null;
+            selectedLegendRow = null;
+          }
+          applyNodeHighlight(d);
+          showNodePanel(d, true);
+          const neighbours = new Set([d.id]);
+          GRAPH_LINKS.forEach(l => {
+            const sid = typeof l.source === 'object' ? l.source.id : l.source;
+            const tid = typeof l.target === 'object' ? l.target.id : l.target;
+            if (sid === d.id) neighbours.add(tid);
+            if (tid === d.id) neighbours.add(sid);
+          });
+          const relatedNodes = GRAPH_NODES.filter(n => neighbours.has(n.id));
+          if (relatedNodes.length) zoomToNodes(relatedNodes);
+          updateButtons();
+        }
+      });
+
+      // Click SVG background to deselect
+      svg.on('click', () => {
+        if (!selectedNode) return;
+        selectedNode = null;
+        if (selectedLegendGroup) applyLegendHighlight(selectedLegendGroup);
+        else applyNodeHighlight(null);
+        document.getElementById('deps-panel').classList.remove('visible');
+        updateButtons();
+      });
+
+      const sim = d3.forceSimulation(GRAPH_NODES)
+        .force('link',    d3.forceLink(GRAPH_LINKS).id(d => d.id).distance(70).strength(0.35))
+        .force('charge',  d3.forceManyBody().strength(-180))
+        .force('center',  d3.forceCenter(W / 2, H / 2).strength(0.08))
+        .force('x',       d3.forceX(W / 2).strength(0.04))
+        .force('y',       d3.forceY(H / 2).strength(0.04))
+        .force('collide', d3.forceCollide(d => nodeR(d) + (d.name.length * 3.5) + 4))
+        .on('tick', () => {
+          link.attr('x1', d => {
+                const dx = d.target.x - d.source.x, dy = d.target.y - d.source.y;
+                const dist = Math.sqrt(dx * dx + dy * dy);
+                return dist ? d.source.x + (dx / dist) * nodeR(d.source) : d.source.x;
+              })
+              .attr('y1', d => {
+                const dx = d.target.x - d.source.x, dy = d.target.y - d.source.y;
+                const dist = Math.sqrt(dx * dx + dy * dy);
+                return dist ? d.source.y + (dy / dist) * nodeR(d.source) : d.source.y;
+              })
+              .attr('x2', d => {
+                const dx = d.target.x - d.source.x, dy = d.target.y - d.source.y;
+                const dist = Math.sqrt(dx * dx + dy * dy);
+                return dist ? d.target.x - (dx / dist) * nodeR(d.target) : d.target.x;
+              })
+              .attr('y2', d => {
+                const dx = d.target.x - d.source.x, dy = d.target.y - d.source.y;
+                const dist = Math.sqrt(dx * dx + dy * dy);
+                return dist ? d.target.y - (dy / dist) * nodeR(d.target) : d.target.y;
+              });
+          node.attr('transform', d => \`translate(\${d.x},\${d.y})\`);
+        })
+        .on('end', () => {
+          // Fit all nodes into view with padding
+          const pad = 40;
+          const xs = GRAPH_NODES.map(d => d.x);
+          const ys = GRAPH_NODES.map(d => d.y);
+          const minX = Math.min(...xs), maxX = Math.max(...xs);
+          const minY = Math.min(...ys), maxY = Math.max(...ys);
+          const bw = maxX - minX || 1, bh = maxY - minY || 1;
+          const scaleX = (W - pad * 2) / bw;
+          const scaleY = (H - pad * 2) / bh;
+          const k = Math.min(scaleX, scaleY, 2);
+          const tx = W / 2 - k * (minX + bw / 2);
+          const ty = H / 2 - k * (minY + bh / 2);
+          svg.transition().duration(600)
+            .call(zoomBehaviour.transform, d3.zoomIdentity.translate(tx, ty).scale(k));
+          document.getElementById('deps-svg').classList.add('settled');
+          depsIsCentered = true;
+          updateButtons();
+          const loader = document.getElementById('deps-loading');
+          if (loader) loader.classList.add('hidden');
+        });
+    }
+  </script>
+</body>
+</html>`;
+}
+
+// ─── HTTP server ──────────────────────────────────────────────────────────────
+
+/** Build the /api/data payload — called per-request so it's always fresh. */
+function buildApiData() {
+  const ROOT_ESC = ROOT.replace(/\\/g, '/');
+  const TIPS = buildTipsMap(
+    (() => {
+      // Build the same fileMap as generateHtml uses, without duplicating all the scan logic
+      const fileMap = {};
+      const add = (dir, list) => {
+        for (const n of list) fileMap[`${dir}/${n}`] = path.join(ROOT, dir, `${n}.ts`);
+      };
+      add('services', scanTs('services'));
+      add('interfaces', scanTs('interfaces'));
+      add('types', scanTs('types'));
+      add('enums', scanTs('enums'));
+      add('artifact-builder', scanTs('artifact-builder'));
+      add('artifact-builder/helpers', scanTs('artifact-builder/helpers'));
+      add('controls', scanTs('controls'));
+      add('helpers', scanTs('helpers'));
+      add('page-overrides', scanTs('page-overrides'));
+      add('page-extensions', [...scanTs('page-extensions'), 'SubjectRegistry']);
+      const compDir = path.join(ROOT, 'components');
+      if (fs.existsSync(compDir)) {
+        for (const e of fs.readdirSync(compDir, { withFileTypes: true })) {
+          if (!e.isDirectory()) continue;
+          const label = e.name
+            .split('-')
+            .map((w) => w[0].toUpperCase() + w.slice(1))
+            .join('');
+          const cand = path.join(compDir, e.name, `${label}.ts`);
+          if (fs.existsSync(cand)) fileMap[`components/${label}`] = cand;
+        }
+      }
+      return fileMap;
+    })()
+  );
+
+  const graph = _cachedDepGraph;
+  return {
+    rootPath: ROOT_ESC,
+    tips: TIPS,
+    graphNodes: graph.nodes.map((n) => ({
+      id: n.id,
+      name: n.name,
+      group: n.group,
+      path: `${ROOT_ESC}/${n.rel}`,
+      tip: TIPS[n.name] || '',
+      color: n.color
+    })),
+    graphLinks: graph.links
+  };
+}
+
+export async function diagram(port = 3333) {
+  const server = http.createServer((req, res) => {
+    try {
+      if (req.url === '/api/data') {
+        const data = buildApiData();
+        const json = JSON.stringify(data);
+        res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+        res.end(json);
+        return;
+      }
+      const html = generateHtml();
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+      res.end(html);
+    } catch (err) {
+      res.writeHead(500, { 'Content-Type': 'text/plain' });
+      res.end(`Error: ${err.message}\n${err.stack}`);
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    server.listen(port, '127.0.0.1', resolve);
+    server.on('error', reject);
+  });
+
+  const url = `http://localhost:${port}`;
+  console.log(`\n✔  Testwise Architecture Diagram → ${url}`);
+  console.log('   Refresh the page to regenerate from current source files.\n');
+  console.log('   Ctrl+C to stop.\n');
+
+  try {
+    const { execSync } = await import('node:child_process');
+    const open =
+      process.platform === 'win32'
+        ? `start "" "${url}"`
+        : process.platform === 'darwin'
+          ? `open "${url}"`
+          : `xdg-open "${url}"`;
+    execSync(open);
+  } catch {
+    /* best-effort */
+  }
+
+  await new Promise(() => {});
+}