c4-architect-mcp 0.2.0-alpha.1 → 0.2.0-alpha.2

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 User-visible changes are recorded here. Unreleased work is not a published package or release.
 
+## 0.2.0-alpha.2 — 2026-11-06
+
+### Added
+
+- Render a focused neighborhood from a saved graph through `render_architecture_graph` or CLI `render --node`. Choose a direction and set depth, node, and relationship limits. Focused artifacts show the view's scope and include relationship source locations.
+
+### Fixed
+
+- Recognize TypeScript `export type *` re-exports as type-only dependencies.
+- Parse UTF-8, UTF-16LE, and UTF-16BE sources that start with a byte order mark and preserve the hash of the original bytes.
+- Report existing local assets reached through relative imports, TypeScript `paths` aliases, or `baseUrl` as unsupported local modules.
+- Compare snapshots across checkout directories and reconcile equivalent import spellings by resolved endpoints, kind, label, and protocol while preserving relationship multiplicity.
+
 ## 0.2.0-alpha.1 — 2026-11-06
 
 ### Added

package/README.md

@@ -6,7 +6,7 @@
 
 C4 Architect is a local [Model Context Protocol](https://modelcontextprotocol.io/) server that turns source imports into a versioned dependency graph, lets you review and name its architectural boundaries, and produces compact C4 diagrams. Use it from Codex, Claude Code, Claude Desktop, or another client that supports local MCP servers over `stdio`.
 
-**0.2.0-alpha.1 · TypeScript / TSX · Local parsing · MIT licensed**
+**0.2.0-alpha.2 · TypeScript / TSX · Local parsing · MIT licensed**
 
 [Get started](#get-started) · [npm package](https://www.npmjs.com/package/c4-architect-mcp) · [See the diagrams](#read-the-diagram) · [Contribute](https://github.com/zrack/c4-architect-mcp/blob/main/CONTRIBUTING.md) · [Roadmap](https://github.com/zrack/c4-architect-mcp/blob/main/ROADMAP.md)
 
@@ -36,10 +36,10 @@ Draw.io, Structurizr DSL, wiki publishing, cross-repository mapping, additional
 Use Node.js 22 or 24 and npm. Run the pinned alpha without a checkout:
 
 ```sh
-npx -y c4-architect-mcp@0.2.0-alpha.1 --help
+npx -y c4-architect-mcp@0.2.0-alpha.2 --help
 ```
 
-The examples pin `0.2.0-alpha.1` so a later release does not silently change your MCP setup. Alpha releases are an opt-in prerelease channel: `c4-architect-mcp@alpha` selects the version currently assigned to that tag and can advance over time. Use the explicit version for a repeatable setup.
+The examples pin `0.2.0-alpha.2` for a repeatable setup. `c4-architect-mcp@alpha` follows the prerelease channel and currently selects `0.2.0-alpha.2`. npm's `latest` tag remains on `0.2.0-alpha.1`, the initial prerelease. There is no stable release yet.
 
 The server communicates over `stdio`; starting it without a subcommand waits for an MCP client rather than opening a browser page or an HTTP port. The following configurations let your client start it through `npx`.
 
@@ -51,13 +51,13 @@ Add this to `~/.codex/config.toml`, or use the MCP server settings in the Codex
 ```toml
 [mcp_servers.c4-architect]
 command = "npx"
-args = ["-y", "c4-architect-mcp@0.2.0-alpha.1"]
+args = ["-y", "c4-architect-mcp@0.2.0-alpha.2"]
 ```
 
 You can also register it from the Codex CLI:
 
 ```sh
-codex mcp add c4-architect -- npx -y c4-architect-mcp@0.2.0-alpha.1
+codex mcp add c4-architect -- npx -y c4-architect-mcp@0.2.0-alpha.2
 ```
 
 Reconnect the server after configuration changes. See the [official Codex MCP setup guide](https://learn.chatgpt.com/docs/extend/mcp).
@@ -68,7 +68,7 @@ Reconnect the server after configuration changes. See the [official Codex MCP se
 <summary><strong>Claude Code</strong></summary>
 
 ```sh
-claude mcp add --transport stdio c4-architect -- npx -y c4-architect-mcp@0.2.0-alpha.1
+claude mcp add --transport stdio c4-architect -- npx -y c4-architect-mcp@0.2.0-alpha.2
 ```
 
 Use `/mcp` to inspect the connection. See the [official Claude Code MCP documentation](https://code.claude.com/docs/en/mcp).
@@ -85,7 +85,7 @@ Open **Settings → Developer → Edit Config** and merge this entry with your e
   "mcpServers": {
     "c4-architect": {
       "command": "npx",
-      "args": ["-y", "c4-architect-mcp@0.2.0-alpha.1"]
+      "args": ["-y", "c4-architect-mcp@0.2.0-alpha.2"]
     }
   }
 }
@@ -95,12 +95,12 @@ Completely restart Claude Desktop after saving. For Windows JSON paths, use forw
 
 </details>
 
-These are local `stdio` configurations. Verify the connection in your chosen client. If a desktop app cannot find `npx`, use the executable's absolute path. On Windows, a client that cannot launch `npx` directly can use `command: "cmd"` with `args: ["/c", "npx", "-y", "c4-architect-mcp@0.2.0-alpha.1"]`.
+These are local `stdio` configurations. Verify the connection in your chosen client. If a desktop app cannot find `npx`, use the executable's absolute path. On Windows, a client that cannot launch `npx` directly can use `command: "cmd"` with `args: ["/c", "npx", "-y", "c4-architect-mcp@0.2.0-alpha.2"]`.
 
 ### Optional global installation
 
 ```sh
-npm install -g c4-architect-mcp@0.2.0-alpha.1
+npm install -g c4-architect-mcp@0.2.0-alpha.2
 c4-architect-mcp --help
 ```
 
@@ -111,9 +111,9 @@ With a global installation, use `c4-architect-mcp` as the MCP command with no ar
 You can analyze and render without an MCP client:
 
 ```sh
-npx -y c4-architect-mcp@0.2.0-alpha.1 analyze /absolute/path/to/project/src --level Component --out /absolute/path/to/project/architecture.graph.json --summary
-npx -y c4-architect-mcp@0.2.0-alpha.1 summary /absolute/path/to/project/architecture.graph.json
-npx -y c4-architect-mcp@0.2.0-alpha.1 render /absolute/path/to/project/architecture.graph.json --out /absolute/path/to/project/ARCHITECTURE.md
+npx -y c4-architect-mcp@0.2.0-alpha.2 analyze /absolute/path/to/project/src --level Component --out /absolute/path/to/project/architecture.graph.json --summary
+npx -y c4-architect-mcp@0.2.0-alpha.2 summary /absolute/path/to/project/architecture.graph.json
+npx -y c4-architect-mcp@0.2.0-alpha.2 render /absolute/path/to/project/architecture.graph.json --out /absolute/path/to/project/ARCHITECTURE.md
 ```
 
 Replace `/absolute/path/to/project` with your project's location. Open the generated `ARCHITECTURE.html` beside the Markdown to explore the diagram.
@@ -158,6 +158,8 @@ Use absolute paths: an MCP client's working directory may differ from the reposi
 
 The current parser covers `.ts` and `.tsx`, excluding declaration files, dependency/build/output directories, and symlink trees. It uses one nearest or explicitly supplied `tsconfig.json` per scan; nested project configurations are not orchestrated automatically. Static imports, re-exports, and literal `import()` / `require()` dependencies are supported; computed dependencies and parse problems remain visible through diagnostics.
 
+Existing CSS, SVG, and other local assets found through relative imports, `paths` aliases, or `baseUrl` produce an `UNSUPPORTED_MODULE_TYPE` diagnostic. The graph contains the TypeScript/TSX dependencies. An unresolved specifier that matches a configured alias produces an `UNRESOLVED_IMPORT` diagnostic.
+
 To name architectural boundaries, supply `configPath` explicitly. The [example configuration](https://github.com/zrack/c4-architect-mcp/blob/main/examples/c4-architect.config.json) demonstrates the format:
 
 ```json
@@ -197,7 +199,7 @@ To name architectural boundaries, supply `configPath` explicitly. The [example c
 | `get_architecture_summary` | `graphPath` | A compact overview of a saved graph and its diagnostics. |
 | `query_architecture_graph` | `graphPath`; optional `nodeId`, `search`, `direction`, `maxDepth`, `maxNodes`, `maxEdges`, `maxBytes`, `includeEvidence` | A bounded neighborhood or search, with truncation reported. |
 | `compare_architecture_graphs` | `beforePath`, `afterPath`; optional `limit`, `maxBytes` | Change counts and bounded details for snapshots at the same C4 level. |
-| `render_architecture_graph` | `graphPath`; optional `title`, `outputPath` | Render a saved, validated graph without passing the graph through the model. |
+| `render_architecture_graph` | `graphPath`; optional `title`, `outputPath`, `focus` | Render a saved graph or a focused neighborhood. |
 | `render_c4_mermaid` | `title`, `c4Level`, `nodes`, `relationships`, optional `outputPath` | Mermaid source and a compact server-rendered PNG; saved SVG, PNG, HTML, and Markdown when requested. |
 
 Queries default to `direction: "both"`, `maxDepth: 1`, `maxNodes: 25`, `maxEdges: 50`, and `maxBytes: 16000`. Source evidence is opt-in. Start with a summary, then search for a component or request its incoming or outgoing dependencies. Smaller views are usually easier to review than a complete repository drawing.
@@ -224,6 +226,35 @@ const relationships = analysis.edges.map(edge => ({
 
 Analysis levels are `Context`, `Container`, and `Component`; renderer levels are `C4Context`, `C4Container`, and `C4Component`. Do not invent a protocol when the analysis has no evidence for it.
 
+### Focus a diagram on one node
+
+Use `query --search` to find the exact node ID for a focused diagram. These commands use the graph from the checkout example and show the outgoing dependencies of Order orchestration.
+
+```sh
+npx -y c4-architect-mcp@0.2.0-alpha.2 query output/order-service.graph.json --search "Order orchestration" --depth 0
+npx -y c4-architect-mcp@0.2.0-alpha.2 render output/order-service.graph.json --node component:orders --direction outgoing --out output/ORDER-SERVICE.outgoing.md
+```
+
+With `--node`, render defaults to both directions, depth 1, 25 nodes, and 50 relationships. Use `--direction incoming` or `--direction outgoing` to trace one direction. Set `--depth`, `--nodes`, and `--edges` to adjust the view. The diagram caption shows how much of the saved graph is included. The render result reports omitted nodes and relationships and whether a node or relationship limit was reached.
+
+The focused Markdown relationship table and interactive HTML details show up to three source locations per relationship. Use the saved graph for the full evidence.
+
+For MCP, pass `focus` to `render_architecture_graph`. Find the ID with `query_architecture_graph` using `search`.
+
+```json
+{
+  "graphPath": "/absolute/path/to/project/architecture.graph.json",
+  "outputPath": "/absolute/path/to/project/ARCHITECTURE.orders.md",
+  "focus": {
+    "nodeId": "component:orders",
+    "direction": "outgoing",
+    "maxDepth": 1,
+    "maxNodes": 25,
+    "maxEdges": 50
+  }
+}
+```
+
 ## Read the diagram
 
 ![Five-component order-service diagram derived from the checked-in TypeScript example](https://raw.githubusercontent.com/zrack/c4-architect-mcp/main/docs/images/component-example.png)

package/dist/cli.js

@@ -2,14 +2,15 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { analyzeDirectory } from "./parsers/astParser.js";
 import { compareArchitectureGraphs, queryArchitectureGraph, readArchitectureGraph, summarizeArchitectureGraph, writeArchitectureGraph } from "./model/graph.js";
-import { graphToDiagram, renderArtifacts } from "./renderers/artifacts.js";
+import { graphFocusSchema } from "./model/neighborhood.js";
+import { renderArchitectureGraph } from "./renderers/artifacts.js";
 import { version } from "./version.js";
 const help = `C4-Architect ${version}
 
 No arguments: start the MCP server over stdio.
 
   analyze <directory> --level Component --out graph.json [--config config.json] [--tsconfig tsconfig.json] [--summary]
-  render <graph.json> --out ARCHITECTURE.md [--title "Architecture"]
+  render <graph.json> --out ARCHITECTURE.md [--title "Architecture"] [--node ID [--direction both] [--depth 1] [--nodes 25] [--edges 50]]
   summary <graph.json>
   query <graph.json> [--node ID | --search TEXT] [--direction both] [--depth 1] [--nodes 25] [--edges 50] [--bytes 16000] [--evidence]
   diff <before.json> <after.json> [--limit 25] [--bytes 16000]
@@ -32,7 +33,7 @@ export async function runCli(args) {
     }
     const [command, ...rest] = args;
     const specs = {
-        analyze: ["level", "out", "config", "tsconfig", "summary"], render: ["out", "title"], summary: [],
+        analyze: ["level", "out", "config", "tsconfig", "summary"], render: ["out", "title", "node", "direction", "depth", "nodes", "edges"], summary: [],
         query: ["node", "search", "direction", "depth", "nodes", "edges", "bytes", "evidence"], diff: ["limit", "bytes"],
     };
     if (!Object.hasOwn(specs, command))
@@ -76,7 +77,13 @@ export async function runCli(args) {
         const out = str("out");
         if (!out)
             throw new Error("render requires --out ARCHITECTURE.md");
-        const result = await renderArtifacts(graphToDiagram(await readArchitectureGraph(positional[0]), str("title")), out);
+        const nodeId = str("node");
+        if (!nodeId && ["direction", "depth", "nodes", "edges"].some(flag => flags.has(flag)))
+            throw new Error("Render scope options require --node ID");
+        const focus = nodeId ? graphFocusSchema.parse({
+            nodeId, direction: str("direction"), maxDepth: num("depth"), maxNodes: num("nodes"), maxEdges: num("edges"),
+        }) : undefined;
+        const result = await renderArchitectureGraph(await readArchitectureGraph(positional[0]), { title: str("title"), outputPath: out, focus });
         json(result.structuredContent);
     }
     else if (command === "summary")

package/dist/index.js

@@ -6,7 +6,8 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { analyzeDirectory } from "./parsers/astParser.js";
 import { compareArchitectureGraphs, queryArchitectureGraph, readArchitectureGraph, summarizeArchitectureGraph, writeArchitectureGraph } from "./model/graph.js";
-import { graphToDiagram, renderArtifacts } from "./renderers/artifacts.js";
+import { graphFocusSchema } from "./model/neighborhood.js";
+import { renderArchitectureGraph, renderArtifacts } from "./renderers/artifacts.js";
 import { runCli } from "./cli.js";
 import { version } from "./version.js";
 const server = new McpServer({ name: "c4-architect-mcp", version });
@@ -35,7 +36,8 @@ server.tool("query_architecture_graph", "Read a bounded neighborhood or search r
     includeEvidence: z.boolean().default(false), maxBytes: z.number().int().min(2048).max(64000).default(16000),
 }, async ({ graphPath, ...options }) => textResult(queryArchitectureGraph(await readArchitectureGraph(graphPath), options)));
 server.tool("compare_architecture_graphs", "Compare two saved graphs at the same abstraction level. Reports full change counts with bounded detail; timestamps and scan-root location do not create changes.", { beforePath: z.string(), afterPath: z.string(), limit: z.number().int().min(1).max(100).default(25), maxBytes: z.number().int().min(2048).max(64000).default(16000) }, async ({ beforePath, afterPath, ...options }) => textResult(compareArchitectureGraphs(await readArchitectureGraph(beforePath), await readArchitectureGraph(afterPath), options)));
-server.tool("render_architecture_graph", "Render a saved validated graph directly to a compact C4 image, Mermaid source, and optional Markdown/SVG/PNG/interactive HTML files. Inferred boundaries are labeled.", { graphPath: z.string(), title: z.string().optional(), outputPath: z.string().optional() }, async ({ graphPath, title, outputPath }) => renderArtifacts(graphToDiagram(await readArchitectureGraph(graphPath), title), outputPath));
+server.tool("render_architecture_graph", "Render a saved graph or a focused node neighborhood as a compact C4 image, Mermaid source, and optional Markdown/SVG/PNG/interactive HTML files.", { graphPath: z.string(), title: z.string().optional(), outputPath: z.string().optional(),
+    focus: graphFocusSchema.optional().describe("Render only a node and its neighbors. Use query_architecture_graph to find the node ID.") }, async ({ graphPath, ...options }) => renderArchitectureGraph(await readArchitectureGraph(graphPath), options));
 server.tool("render_c4_mermaid", "Renders a compact C4 PNG using server-side orthogonal layout, plus Mermaid source. With outputPath saves Markdown, SVG, PNG and interactive HTML with connection highlighting and full-diagram PNG/SVG exports.", {
     title: z.string(), c4Level: z.enum(["C4Context", "C4Container", "C4Component"]),
     nodes: z.array(z.object({ id: z.string(), label: z.string(), type: z.enum(["Person", "System", "System_Ext", "ExternalSystem", "Container", "ContainerDb", "Component"]), technology: z.string().optional(), description: z.string().optional() })),

package/dist/model/graph.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
+import path from "node:path";
 import { z } from "zod";
 export const GRAPH_SCHEMA_VERSION = "1.0";
 const nonempty = z.string().min(1);
@@ -267,10 +268,41 @@ export function queryArchitectureGraph(input, options = {}) {
 export const queryGraph = queryArchitectureGraph;
 const canonical = (value) => JSON.stringify(value, (_key, item) => item && typeof item === "object" && !Array.isArray(item)
     ? Object.fromEntries(Object.entries(item).filter(([, value]) => value !== undefined).sort(([a], [b]) => a.localeCompare(b))) : item);
-const nodeSemantics = (node) => ({ id: node.id, label: node.label, type: node.type, technology: node.technology,
+function labelForComparison(element, scanDirectory) {
+    if (element.type !== "System" || element.classification.basis !== "inferred"
+        || element.classification.rule !== "default-scan-scope-boundary")
+        return element.label;
+    const localPath = path.win32.isAbsolute(scanDirectory) && !path.posix.isAbsolute(scanDirectory) ? path.win32 : path.posix;
+    const generatedLabel = localPath.basename(scanDirectory) || "Scanned system";
+    return element.label === generatedLabel ? undefined : element.label;
+}
+const nodeSemantics = (node, scanDirectory) => ({ id: node.id, label: labelForComparison(node, scanDirectory), type: node.type, technology: node.technology,
     path: node.path, exports: [...(node.exports ?? [])].sort(), parentId: node.parentId, description: node.description, classification: node.classification });
-const edgeSemantics = (edge) => ({ id: edge.id, source: edge.source, target: edge.target,
+const edgeSemantics = (edge) => ({ source: edge.source, target: edge.target,
     label: edge.label, protocol: edge.protocol, kind: edge.kind });
+function reconcileUnmatchedEdges(before, after) {
+    const beforeIds = new Set(before.map(edge => edge.id));
+    const afterIds = new Set(after.map(edge => edge.id));
+    const unmatchedByDependency = new Map();
+    for (const edge of before) {
+        if (afterIds.has(edge.id))
+            continue;
+        const key = JSON.stringify(edgeSemantics(edge));
+        const ids = unmatchedByDependency.get(key) ?? [];
+        ids.push(edge.id);
+        unmatchedByDependency.set(key, ids);
+    }
+    for (const ids of unmatchedByDependency.values())
+        ids.sort().reverse();
+    // Existing IDs take precedence. Pair leftover equivalent dependencies once
+    // each so a specifier spelling change does not hide a parallel edge change.
+    return [...after].sort((left, right) => left.id.localeCompare(right.id)).map(edge => {
+        if (beforeIds.has(edge.id))
+            return edge;
+        const previousId = unmatchedByDependency.get(JSON.stringify(edgeSemantics(edge)))?.pop();
+        return previousId === undefined ? edge : { ...edge, id: previousId };
+    });
+}
 export function compareArchitectureGraphs(beforeInput, afterInput, options = {}) {
     const before = validateArchitectureGraph(beforeInput), after = validateArchitectureGraph(afterInput);
     if (before.metadata.abstractionLevel !== after.metadata.abstractionLevel)
@@ -280,15 +312,16 @@ export function compareArchitectureGraphs(beforeInput, afterInput, options = {})
         const previous = new Map(left.map(item => [key(item), item])), next = new Map(right.map(item => [key(item), item]));
         const added = [...next.keys()].filter(id => !previous.has(id)).sort();
         const removed = [...previous.keys()].filter(id => !next.has(id)).sort();
-        const changed = [...next.keys()].filter(id => previous.has(id) && canonical(value(previous.get(id))) !== canonical(value(next.get(id)))).sort();
+        const changed = [...next.keys()].filter(id => previous.has(id)
+            && canonical(value(previous.get(id), before.metadata.scannedDirectory)) !== canonical(value(next.get(id), after.metadata.scannedDirectory))).sort();
         return { counts: { added: added.length, removed: removed.length, changed: changed.length },
             added: added.slice(0, limit), removed: removed.slice(0, limit), changed: changed.slice(0, limit) };
     };
     const result = {
         graphVersion: before.schemaVersion, abstractionLevel: before.metadata.abstractionLevel,
         nodes: compare(before.nodes, after.nodes, node => node.id, nodeSemantics),
-        edges: compare(before.edges, after.edges, edge => edge.id, edgeSemantics),
-        hierarchy: compare(before.hierarchy, after.hierarchy, boundary => boundary.id, boundary => boundary),
+        edges: compare(before.edges, reconcileUnmatchedEdges(before.edges, after.edges), edge => edge.id, edgeSemantics),
+        hierarchy: compare(before.hierarchy, after.hierarchy, boundary => boundary.id, (boundary, scanDirectory) => ({ ...boundary, label: labelForComparison(boundary, scanDirectory) })),
         sources: compare(before.sources, after.sources, source => source.path, source => source),
         truncated: false,
     };

package/dist/model/neighborhood.js

@@ -0,0 +1,64 @@
+import { z } from "zod";
+export const graphFocusSchema = z.object({
+    nodeId: z.string().min(1),
+    direction: z.enum(["incoming", "outgoing", "both"]).default("both"),
+    maxDepth: z.number().int().min(0).max(5).default(1),
+    maxNodes: z.number().int().min(1).max(100).default(25),
+    maxEdges: z.number().int().min(0).max(200).default(50),
+});
+export function selectGraphNeighborhood(graph, input) {
+    const options = graphFocusSchema.parse(input);
+    const center = graph.nodes.find(node => node.id === options.nodeId);
+    if (!center)
+        throw new Error(`Unknown node ID: ${options.nodeId}`);
+    const adjacent = new Map();
+    function connect(id, edge, neighbor) {
+        const entries = adjacent.get(id) ?? [];
+        entries.push({ edge, neighbor });
+        adjacent.set(id, entries);
+    }
+    for (const edge of graph.edges) {
+        if (options.direction !== "incoming")
+            connect(edge.source, edge, edge.target);
+        if (options.direction !== "outgoing")
+            connect(edge.target, edge, edge.source);
+    }
+    const selectedNodes = new Set([center.id]);
+    const selectedEdges = new Set();
+    const queue = [{ id: center.id, depth: 0 }];
+    const truncated = { nodes: false, edges: false };
+    for (let cursor = 0; cursor < queue.length; cursor++) {
+        const { id, depth } = queue[cursor];
+        if (depth >= options.maxDepth)
+            continue;
+        for (const { edge, neighbor } of adjacent.get(id) ?? []) {
+            if (selectedEdges.has(edge.id))
+                continue;
+            const isNewNode = !selectedNodes.has(neighbor);
+            if (isNewNode && selectedNodes.size >= options.maxNodes) {
+                truncated.nodes = true;
+                continue;
+            }
+            if (selectedEdges.size >= options.maxEdges) {
+                truncated.edges = true;
+                continue;
+            }
+            selectedEdges.add(edge.id);
+            if (isNewNode) {
+                selectedNodes.add(neighbor);
+                queue.push({ id: neighbor, depth: depth + 1 });
+            }
+        }
+    }
+    return {
+        center,
+        nodes: graph.nodes.filter(node => selectedNodes.has(node.id)),
+        edges: graph.edges.filter(edge => selectedEdges.has(edge.id)),
+        focus: {
+            ...options,
+            omittedNodes: graph.nodes.length - selectedNodes.size,
+            omittedEdges: graph.edges.length - selectedEdges.size,
+            truncated,
+        },
+    };
+}

package/dist/parsers/astParser.js

@@ -83,6 +83,12 @@ function relationshipLabel(fact, external) {
         return "Literal require syntax";
     return external ? "Imports package" : "Imports module";
 }
+function decodeSource(bytes) {
+    const encoding = bytes[0] === 0xff && bytes[1] === 0xfe ? "utf-16le"
+        : bytes[0] === 0xfe && bytes[1] === 0xff ? "utf-16be" : "utf-8";
+    // Strip the BOM for source positions, while hashing the original bytes.
+    return new TextDecoder(encoding, { fatal: true }).decode(bytes);
+}
 /** Build a source-backed, versioned graph. Analysis reads source/configuration
  * data only; it never imports scanned code or executes repository scripts. */
 export async function analyzeDirectory(targetDir, c4Level, options = {}) {
@@ -112,19 +118,30 @@ export async function analyzeDirectory(targetDir, c4Level, options = {}) {
                 message: `Could not read source file: ${error instanceof Error ? error.message : String(error)}` });
             continue;
         }
-        const sourceCode = sourceBytes.toString("utf8");
+        const isTsx = absolutePath.endsWith(".tsx");
+        const sourceRecord = { path: relativePath, contentHash: createHash("sha256").update(sourceBytes).digest("hex"),
+            language: isTsx ? "TSX" : "TypeScript" };
+        let sourceCode;
+        try {
+            sourceCode = decodeSource(sourceBytes);
+        }
+        catch {
+            diagnostics.push({ code: "SOURCE_ENCODING_ERROR", severity: "error", path: relativePath,
+                message: "Source is not valid UTF-8 or BOM-marked UTF-16; it could not be parsed." });
+            sources.push({ ...sourceRecord, parseStatus: "error" });
+            continue;
+        }
         let facts;
         try {
-            facts = extractSourceFacts(sourceCode, relativePath, absolutePath.endsWith(".tsx"));
+            facts = extractSourceFacts(sourceCode, relativePath, isTsx);
         }
         catch (error) {
             diagnostics.push({ code: "PARSER_ERROR", severity: "error", path: relativePath,
                 message: `Source parsing failed: ${error instanceof Error ? error.message : String(error)}` });
-            sources.push({ path: relativePath, contentHash: createHash("sha256").update(sourceBytes).digest("hex"), parseStatus: "error" });
+            sources.push({ ...sourceRecord, parseStatus: "error" });
             continue;
         }
-        sources.push({ path: relativePath, contentHash: createHash("sha256").update(sourceBytes).digest("hex"), parseStatus: facts.parseStatus,
-            language: absolutePath.endsWith(".tsx") ? "TSX" : "TypeScript" });
+        sources.push({ ...sourceRecord, parseStatus: facts.parseStatus });
         diagnostics.push(...facts.diagnostics);
         const assignment = mapper.forFile(relativePath);
         const selected = nodeForFile(relativePath, assignment, c4Level);
@@ -164,6 +181,10 @@ export async function analyzeDirectory(targetDir, c4Level, options = {}) {
                 connect(file.nodeId, targetFile.nodeId, fact, false);
                 continue;
             }
+            if (resolved.localAsset) {
+                diagnostic(fact, "UNSUPPORTED_MODULE_TYPE", "warning", "Module specifier names an existing local asset outside supported TypeScript/TSX source; no dependency node was fabricated.");
+                continue;
+            }
             if (resolved.builtin) {
                 diagnostic(fact, "BUILTIN_MODULE", "info", "Observed a platform built-in import; a built-in library is not inferred to be an external system.");
                 continue;

package/dist/parsers/moduleResolver.js

@@ -123,22 +123,58 @@ export function createModuleResolver(scanRoot, manifestFiles, explicitTsconfig)
         return mode;
     }
     const outputDirectories = [options.outDir, options.declarationDir].filter((item) => Boolean(item) && path.resolve(item) !== scanRoot).map(item => path.resolve(item));
-    function matchesPathAlias(specifier) {
-        return Object.keys(options.paths ?? {}).some(pattern => {
+    const aliases = options.paths ?? {};
+    function pathAliasTargets(specifier) {
+        if (Object.hasOwn(aliases, specifier))
+            return aliases[specifier];
+        let best;
+        for (const [pattern, targets] of Object.entries(aliases)) {
             const star = pattern.indexOf("*");
-            return star < 0 ? specifier === pattern : specifier.startsWith(pattern.slice(0, star)) && specifier.endsWith(pattern.slice(star + 1));
-        });
+            if (star < 0 || pattern.indexOf("*", star + 1) >= 0)
+                continue;
+            const prefix = pattern.slice(0, star), suffix = pattern.slice(star + 1);
+            if (specifier.length >= prefix.length + suffix.length && specifier.startsWith(prefix) && specifier.endsWith(suffix)
+                && (!best || prefix.length > best.prefixLength)) {
+                best = { prefixLength: prefix.length, wildcard: specifier.slice(prefix.length, specifier.length - suffix.length), targets };
+            }
+        }
+        if (!best)
+            return undefined;
+        const { targets, wildcard } = best;
+        return targets.map(target => target.replace("*", () => wildcard));
+    }
+    function existingLocalAsset(specifier, containingFile, mapped) {
+        // TS resolves source/declaration modules, but bundlers may accept these
+        // literal asset imports as well. Check existence without reading the asset.
+        if (/[?#]/.test(specifier))
+            return undefined;
+        function isExistingAsset(candidate) {
+            const extension = path.extname(candidate);
+            return Boolean(extension) && !/^\.[cm]?[jt]sx?$/i.test(extension) && ts.sys.fileExists(candidate);
+        }
+        if (path.isAbsolute(specifier) || specifier.startsWith("./") || specifier.startsWith("../")) {
+            const candidate = path.resolve(path.dirname(containingFile), specifier);
+            return isExistingAsset(candidate) ? candidate : undefined;
+        }
+        const pathsBase = options.baseUrl ?? (typeof options.pathsBasePath === "string" ? options.pathsBasePath : undefined)
+            ?? (configPath ? path.dirname(configPath) : undefined);
+        const candidates = pathsBase ? (mapped ?? []).map(target => path.resolve(pathsBase, target)) : [];
+        if (options.baseUrl)
+            candidates.push(path.resolve(options.baseUrl, specifier));
+        return candidates.find(isExistingAsset);
     }
     return { configPath, outputDirectories, diagnostics, resolve(specifier, containingFile, kind, modeOverride) {
             const resolved = ts.resolveModuleName(specifier, containingFile, options, host, cache, undefined, resolutionMode(containingFile, modeOverride === "require" ? "require" : kind)).resolvedModule;
-            const resolvedPath = resolved ? path.resolve(host.realpath?.(resolved.resolvedFileName) ?? resolved.resolvedFileName) : undefined;
             const bare = !specifier.startsWith(".") && !path.isAbsolute(specifier) && !specifier.startsWith("#");
+            const aliasTargets = bare ? pathAliasTargets(specifier) : undefined;
+            const localAsset = !resolved ? existingLocalAsset(specifier, containingFile, aliasTargets) : undefined;
+            const resolvedPath = resolved ? path.resolve(host.realpath?.(resolved.resolvedFileName) ?? resolved.resolvedFileName) : localAsset;
             // URL/runtime schemes and invalid package names are not npm packages.
             const candidate = bare ? packageName(specifier) : undefined;
             const name = candidate && /^(?:@[^/\s:]+\/)?[^/\s:]+$/.test(candidate) ? candidate : undefined;
-            const localSpecifier = !bare || specifier.startsWith("node:") || matchesPathAlias(specifier) && (!resolved || !resolved.isExternalLibraryImport)
+            const localSpecifier = !bare || Boolean(localAsset) || specifier.startsWith("node:") || Boolean(aliasTargets && (!resolved || !resolved.isExternalLibraryImport))
                 || Boolean(name && (workspacePackages.has(name) || ambiguousPackages.has(name)));
-            return { ...(resolvedPath ? { resolvedPath } : {}), ...(name ? { packageName: name } : {}),
+            return { ...(resolvedPath ? { resolvedPath } : {}), ...(name ? { packageName: name } : {}), ...(localAsset ? { localAsset: true } : {}),
                 externalPackage: bare && !localSpecifier && (!resolved || Boolean(resolved.isExternalLibraryImport && resolvedPath?.split(path.sep).includes("node_modules"))), localSpecifier,
                 builtin: isBuiltin(specifier) };
         } };

package/dist/parsers/syntaxFacts.js

@@ -30,6 +30,23 @@ function allSpecifiersAreTypes(node, kind) {
     const specifiers = container?.namedChildren.filter(child => child.type === `${kind}_specifier`) ?? [];
     return specifiers.length > 0 && specifiers.every(child => hasKeyword(child, "type"));
 }
+function recoverTypeStarExport(node) {
+    if (!node.hasError)
+        return undefined;
+    // The current native grammar recovers TypeScript 5's type-only star export
+    // as a regular star export with a single ERROR for the `type` token. Match
+    // that exact shape so unrelated syntax errors remain visible.
+    const tokens = node.children.filter(child => child.type !== "comment");
+    const [keyword, modifier, star, from, source, terminator] = tokens;
+    if (tokens.length < 5 || tokens.length > 6 || keyword.type !== "export"
+        || modifier.type !== "ERROR" || modifier.text !== "type"
+        || !["*", "namespace_export"].includes(star.type) || star.hasError
+        || from.type !== "from" || source.type !== "string" || source.hasError
+        || (terminator && terminator.type !== ";")
+        || tokens.some(token => token.isMissing))
+        return undefined;
+    return modifier;
+}
 function inTypeContext(node) {
     for (let ancestor = node.parent; ancestor; ancestor = ancestor.parent) {
         if (["type_alias_declaration", "type_annotation", "type_query", "type_arguments", "interface_declaration"].includes(ancestor.type))
@@ -62,6 +79,7 @@ export function extractSourceFacts(sourceCode, filePath, isTsx = false) {
     const exportEvidence = [];
     const seen = new Set();
     let syntaxErrors = 0;
+    let recoveredTypeStars = 0;
     function addDependency(source, node, kind, typeOnly, resolutionMode) {
         const specifier = literalValue(source);
         if (specifier === undefined) {
@@ -77,6 +95,7 @@ export function extractSourceFacts(sourceCode, filePath, isTsx = false) {
         dependencies.push({ specifier, kind, typeOnly, ...(resolutionMode ? { resolutionMode } : {}), evidence: location(source ?? node, filePath, kind, specifier, typeOnly) });
     }
     function walk(node) {
+        let recoveredModifier;
         if ((node.type === "ERROR" || node.isMissing) && syntaxErrors++ < 10) {
             diagnostics.push({ code: "PARSE_ERROR", severity: "error", path: filePath,
                 line: node.startPosition.row + 1, column: node.startPosition.column + 1,
@@ -90,7 +109,8 @@ export function extractSourceFacts(sourceCode, filePath, isTsx = false) {
         }
         else if (node.type === "export_statement") {
             const source = node.childForFieldName("source");
-            const typeOnly = hasKeyword(node, "type") || allSpecifiersAreTypes(node, "export");
+            recoveredModifier = recoverTypeStarExport(node);
+            const typeOnly = Boolean(recoveredModifier) || hasKeyword(node, "type") || allSpecifiersAreTypes(node, "export");
             if (source)
                 addDependency(source, node, "re-export", typeOnly);
             // Namespace member exports do not become exports of the containing file.
@@ -136,13 +156,18 @@ export function extractSourceFacts(sourceCode, filePath, isTsx = false) {
                 addDependency(source, node, typeOnly ? "type-import" : dynamic ? "dynamic-import" : "require", typeOnly);
             }
         }
-        for (const child of node.namedChildren)
-            walk(child);
+        for (const child of node.hasError ? node.children : node.namedChildren) {
+            if (recoveredModifier && child.id === recoveredModifier.id)
+                recoveredTypeStars++;
+            else
+                walk(child);
+        }
     }
     walk(tree.rootNode);
-    if (tree.rootNode.hasError && !diagnostics.some(item => item.code === "PARSE_ERROR")) {
+    if (tree.rootNode.hasError && syntaxErrors === 0 && recoveredTypeStars === 0) {
+        syntaxErrors++;
         diagnostics.push({ code: "PARSE_ERROR", severity: "error", path: filePath, line: 1, column: 1,
             message: "Tree-sitter found invalid or incomplete syntax; extracted dependencies may be partial." });
     }
-    return { dependencies, exports: [...exports].sort(), exportEvidence, diagnostics, parseStatus: tree.rootNode.hasError ? "partial" : "complete" };
+    return { dependencies, exports: [...exports].sort(), exportEvidence, diagnostics, parseStatus: syntaxErrors > 0 ? "partial" : "complete" };
 }

package/dist/renderers/artifacts.js

@@ -3,23 +3,62 @@ import path from "node:path";
 import { renderC4Mermaid } from "./c4Mermaid.js";
 import { renderCompactC4 } from "./compactC4.js";
 import { validateArchitectureGraph } from "../model/graph.js";
+import { selectGraphNeighborhood } from "../model/neighborhood.js";
 export function graphToDiagram(input, title) {
-    const graph = validateArchitectureGraph(input);
+    return diagramFromView(validateArchitectureGraph(input), title);
+}
+function diagramFromView(graph, title, view) {
     const boundaries = new Map(graph.hierarchy.map(item => [item.id, item]));
+    const { nodes, edges } = view ?? graph;
+    const labelCounts = new Map();
+    const labelKey = (edge) => JSON.stringify([edge.source, edge.target, edge.label]);
+    if (view)
+        for (const edge of edges) {
+            const key = labelKey(edge);
+            labelCounts.set(key, (labelCounts.get(key) ?? 0) + 1);
+        }
+    let caption;
+    if (view) {
+        const { direction, maxDepth, truncated } = view.focus;
+        const directionLabel = direction === "both" ? "Both directions" : direction === "incoming" ? "Incoming" : "Outgoing";
+        caption = `${nodes.length} of ${graph.nodes.length} nodes · ${edges.length} of ${graph.edges.length} relationships · ${directionLabel} · Depth ${maxDepth}`;
+        if (truncated.nodes || truncated.edges)
+            caption += " · Limit reached";
+    }
     return {
-        title: title ?? `${graph.hierarchy.find(item => item.type === "System")?.label ?? "Architecture"} — ${graph.metadata.abstractionLevel}`,
+        title: title ?? (view ? `${view.center.label} · Neighborhood`
+            : `${graph.hierarchy.find(item => item.type === "System")?.label ?? "Architecture"} — ${graph.metadata.abstractionLevel}`),
+        caption,
         c4Level: `C4${graph.metadata.abstractionLevel}`,
-        nodes: graph.nodes.map(node => ({
+        nodes: nodes.map(node => ({
             id: node.id, label: node.classification.basis === "inferred" && !node.label.includes("(inferred)") ? `${node.label} (inferred)` : node.label, type: node.type,
             technology: node.technology,
             description: [node.classification.basis === "inferred" ? "Inferred boundary" : undefined,
                 node.parentId ? `Within ${boundaries.get(node.parentId)?.label ?? node.parentId}${boundaries.get(node.parentId)?.classification.basis === "inferred" ? " (inferred)" : ""}` : undefined,
                 node.description].filter(Boolean).join(" · ") || undefined,
         })),
-        relationships: graph.edges.map(edge => ({ from: edge.source, to: edge.target, label: edge.label,
-            technology: edge.protocol === "unknown" ? undefined : edge.protocol })),
+        relationships: edges.map(edge => {
+            const specifier = (labelCounts.get(labelKey(edge)) ?? 0) > 1
+                ? edge.evidence.find(item => item.specifier)?.specifier : undefined;
+            const evidence = view ? edge.evidence.slice(0, 3).map(item => `${item.path}:${item.line}:${item.column}${item.specifier ? ` (${item.specifier})` : ""}`) : [];
+            if (view && edge.evidence.length > evidence.length)
+                evidence.push(`+${edge.evidence.length - evidence.length} more in the saved graph`);
+            return {
+                from: edge.source,
+                to: edge.target,
+                label: specifier ? `${edge.label} · ${specifier}` : edge.label,
+                technology: edge.protocol === "unknown" ? undefined : edge.protocol,
+                description: evidence.length ? evidence.join("\n") : undefined,
+            };
+        }),
     };
 }
+export async function renderArchitectureGraph(input, options = {}) {
+    const graph = validateArchitectureGraph(input);
+    const view = options.focus ? selectGraphNeighborhood(graph, options.focus) : undefined;
+    const result = await renderArtifacts(diagramFromView(graph, options.title, view), options.outputPath);
+    return view ? { ...result, structuredContent: { ...result.structuredContent, focus: view.focus } } : result;
+}
 export async function renderArtifacts(diagram, outputPath) {
     const mermaidOutput = renderC4Mermaid(diagram);
     const compact = await renderCompactC4(diagram);
@@ -34,9 +73,17 @@ export async function renderArtifacts(diagram, outputPath) {
         await Promise.all([fs.writeFile(artifacts.svg, compact.svg), fs.writeFile(artifacts.png, compact.png), fs.writeFile(artifacts.html, compact.html)]);
         const fileLink = (filename) => encodeURIComponent(path.basename(filename));
         const cell = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/[\\`*_{}\[\]|]/g, "\\$&").replace(/\s+/g, " ");
-        const key = diagram.relationships.map((r, i) => `| R${String(i + 1).padStart(2, "0")} | ${cell(r.from)} | ${cell(r.to)} | ${cell(r.label)} | ${cell(r.technology ?? "")} |`).join("\n");
+        const hasEvidence = diagram.relationships.some(r => r.description);
+        const labels = new Map(diagram.nodes.map(node => [node.id, node.label]));
+        const key = diagram.relationships.map((r, i) => {
+            const from = hasEvidence ? labels.get(r.from) : r.from;
+            const to = hasEvidence ? labels.get(r.to) : r.to;
+            const row = `| R${String(i + 1).padStart(2, "0")} | ${cell(from)} | ${cell(to)} | ${cell(r.label)} | ${cell(r.technology ?? "")} |`;
+            return hasEvidence ? `${row} ${cell(r.description ?? "")} |` : row;
+        }).join("\n");
+        const scope = diagram.caption ? `${cell(diagram.caption)}\n\n` : "";
         const heading = diagram.title.replace(/\s+/g, " ").trim().replace(/[\\`*_{}\[\]<>]/g, "\\$&");
-        await fs.writeFile(markdown, `# ${heading}\n\n![Compact C4 diagram](${fileLink(artifacts.png)})\n\n[Interactive view](${fileLink(artifacts.html)}) · [Scalable SVG](${fileLink(artifacts.svg)})\n\n<details>\n<summary>Mermaid source export</summary>\n\n${mermaidOutput}\n\n</details>\n\n## Relationships\n\n| ID | From | To | Action | Technology |\n|---|---|---|---|---|\n${key}\n`, "utf8");
+        await fs.writeFile(markdown, `# ${heading}\n\n${scope}![Compact C4 diagram](${fileLink(artifacts.png)})\n\n[Interactive view](${fileLink(artifacts.html)}) · [Scalable SVG](${fileLink(artifacts.svg)})\n\n<details>\n<summary>Mermaid source export</summary>\n\n${mermaidOutput}\n\n</details>\n\n## Relationships\n\n| ID | From | To | Action | Technology |${hasEvidence ? " Source evidence |" : ""}\n|---|---|---|---|---|${hasEvidence ? "---|" : ""}\n${key}\n`, "utf8");
     }
     return {
         content: [{ type: "text", text: mermaidOutput }, { type: "image", data: compact.png.toString("base64"), mimeType: "image/png" }],

package/dist/renderers/compactC4.js

@@ -91,7 +91,8 @@ async function layoutDiagram(diagram) {
     const { graph, direction } = candidates.sort((a, b) => a.score - b.score)[0];
     const titleLines = wrap(diagram.title.replace(/\s+/g, " "), 90);
     const headerExtra = Math.max(0, titleLines.length - 1) * 24;
-    const width = Math.ceil(Math.max(graph.width + 48, await textWidth(titleLines, 21) + 48));
+    const captionWidth = diagram.caption ? await textWidth([diagram.caption], 12) : 0;
+    const width = Math.ceil(Math.max(graph.width, await textWidth(titleLines, 21), captionWidth) + 48);
     const offset = { x: (width - graph.width) / 2, y: 88 + headerExtra };
     const positionedNodes = nodes.map(node => {
         const position = graph.children.find(candidate => candidate.id === node.alias);
@@ -106,7 +107,7 @@ async function layoutDiagram(diagram) {
             .map(point => ({ x: point.x + offset.x, y: point.y + offset.y }));
         const box = edge.labels[0];
         return { id: relationship.id, from: relationship.from, to: relationship.to, label: relationship.label,
-            technology: relationship.technology, displayLines: relationship.displayLines, points,
+            technology: relationship.technology, description: relationship.description, displayLines: relationship.displayLines, points,
             labelBox: { x: box.x + offset.x, y: box.y + offset.y, width: box.width, height: box.height } };
     });
     return { width, height: Math.ceil(graph.height + 112 + headerExtra), direction,
@@ -115,9 +116,10 @@ async function layoutDiagram(diagram) {
 function drawSvg(diagram, layout) {
     const titleLines = wrap(diagram.title.replace(/\s+/g, " "), 90);
     const title = svgText(titleLines, layout.width / 2, 28, 21, 24, "diagram-title");
+    const caption = diagram.caption ?? `${layout.nodes.length} nodes · ${layout.relationships.length} relationships · R IDs identify individual arrows`;
     const paths = layout.relationships.map(relationship => {
         const d = relationship.points.map((point, index) => `${index ? "L" : "M"}${point.x},${point.y}`).join(" ");
-        const description = `${relationship.id}: ${relationship.from} → ${relationship.to}. ${relationship.label}${relationship.technology ? ` [${relationship.technology}]` : ""}`;
+        const description = [`${relationship.id}: ${relationship.from} → ${relationship.to}. ${relationship.label}${relationship.technology ? ` [${relationship.technology}]` : ""}`, relationship.description].filter(Boolean).join("\n");
         return `<g class="edge" data-edge-id="${relationship.id}"><title>${xml(description)}</title><path class="edge-halo" d="${d}"/><path class="flowchart-link" id="${relationship.id}" data-edge-id="${relationship.id}" d="${d}" marker-end="url(#arrow)"/></g>`;
     }).join("");
     const nodeShapes = layout.nodes.map(node => {
@@ -129,11 +131,12 @@ function drawSvg(diagram, layout) {
     }).join("");
     const labels = layout.relationships.map(relationship => {
         const box = relationship.labelBox;
-        return `<g class="edgeLabel" data-edge-id="${relationship.id}"><title>${xml(`${relationship.id}: ${relationship.label}${relationship.technology ? ` [${relationship.technology}]` : ""}`)}</title><g class="label" data-id="${relationship.id}"><rect x="${box.x}" y="${box.y}" width="${box.width}" height="${box.height}" rx="3"/>${svgText(relationship.displayLines, box.x + box.width / 2, box.y + 16, 14, 18, "edge-label-text")}</g></g>`;
+        const description = [`${relationship.id}: ${relationship.label}${relationship.technology ? ` [${relationship.technology}]` : ""}`, relationship.description].filter(Boolean).join("\n");
+        return `<g class="edgeLabel" data-edge-id="${relationship.id}"><title>${xml(description)}</title><g class="label" data-id="${relationship.id}"><rect x="${box.x}" y="${box.y}" width="${box.width}" height="${box.height}" rx="3"/>${svgText(relationship.displayLines, box.x + box.width / 2, box.y + 16, 14, 18, "edge-label-text")}</g></g>`;
     }).join("");
     return `<svg xmlns="http://www.w3.org/2000/svg" width="${layout.width}" height="${layout.height}" viewBox="0 0 ${layout.width} ${layout.height}" data-engine="elk" role="img" aria-labelledby="diagram-title diagram-description"><title id="diagram-title">${xml(diagram.title)}</title><desc id="diagram-description">${layout.nodes.length} architecture nodes and ${layout.relationships.length} directed relationships. Select a component in the interactive view to trace its connections.</desc><defs><marker id="arrow" viewBox="0 0 8 8" refX="8" refY="4" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L8 4L0 8Z" fill="#4d657c"/></marker></defs><style>
 text{font-family:Arial,Helvetica,sans-serif;fill:#172b43}.diagram-title{font-weight:500}.node rect{fill:#e7f0fb;stroke:#5381b7;stroke-width:1.2}.node.external rect{fill:#f0f2f5;stroke:#818d9d}.node-kind,.node-technology{fill:#4a5e76}.edge-halo,.flowchart-link{fill:none;stroke-linejoin:round}.edge-halo{stroke:white;stroke-width:5}.flowchart-link{stroke:#4d657c;stroke-width:1.5}.edgeLabel rect{fill:white}.node:focus rect{stroke:#174fbb;stroke-width:2.5}.node{cursor:pointer}.edge,.edgeLabel{cursor:pointer}.dimmed{opacity:.12}.selected rect{stroke:#174fbb;stroke-width:2.5}.outgoing .flowchart-link{stroke:#155dd5;stroke-width:2.5}.incoming .flowchart-link{stroke:#a94a10;stroke-width:2.5}.outgoing .edge-label-text{fill:#124da7}.incoming .edge-label-text{fill:#8f3e0d}
-</style><rect class="background" width="100%" height="100%" fill="white"/>${title}<text x="${layout.width / 2}" y="${55 + Math.max(0, titleLines.length - 1) * 24}" text-anchor="middle" font-size="12">${layout.nodes.length} nodes · ${layout.relationships.length} relationships · R IDs identify individual arrows</text>${paths}${nodeShapes}${labels}</svg>`;
+</style><rect class="background" width="100%" height="100%" fill="white"/>${title}<text x="${layout.width / 2}" y="${55 + Math.max(0, titleLines.length - 1) * 24}" text-anchor="middle" font-size="12">${xml(caption)}</text>${paths}${nodeShapes}${labels}</svg>`;
 }
 function drawHtml(diagram, svg, layout) {
     const data = JSON.stringify(layout).replace(/</g, "\\u003c").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
@@ -151,7 +154,7 @@ function show(selection){
  root.querySelectorAll('.node').forEach(element=>{const id=element.dataset.nodeId;element.classList.toggle('dimmed',!!selection&&!visibleNodes.has(id));element.classList.toggle('selected',selection?.kind==='node'&&id===selection.id);});
  root.querySelectorAll('.edge,.edgeLabel').forEach(element=>{const edge=graph.relationships.find(edge=>edge.id===element.dataset.edgeId),active=ids.has(edge.id);element.classList.toggle('dimmed',!!selection&&!active);element.classList.toggle('outgoing',!!selection&&active&&(selection.kind==='edge'||edge.from===selection.id));element.classList.toggle('incoming',!!selection&&active&&selection.kind==='node'&&edge.to===selection.id&&edge.from!==selection.id);});
  const node=selection?.kind==='node'?nodes.get(selection.id):null,edge=selection?.kind==='edge'?related[0]:null;
- title.textContent=node?.label??(edge?edge.id+' · '+edge.label:'All connections');details.textContent=node?[node.technology,node.description,related.length+' connected relationships'].filter(Boolean).join('\\n'):edge?[nodes.get(edge.from).label+' → '+nodes.get(edge.to).label,edge.technology].filter(Boolean).join('\\n'):'Select a component to highlight its incoming and outgoing arrows. Select an arrow or relationship below to isolate it.';
+ title.textContent=node?.label??(edge?edge.id+' · '+edge.label:'All connections');details.textContent=node?[node.technology,node.description,related.length+' connected relationships'].filter(Boolean).join('\\n'):edge?[nodes.get(edge.from).label+' → '+nodes.get(edge.to).label,edge.technology,edge.description].filter(Boolean).join('\\n'):'Select a component to highlight its incoming and outgoing arrows. Select an arrow or relationship below to isolate it.';
  list.replaceChildren();for(const edge of related){const item=document.createElement('li'),button=document.createElement('button'),small=document.createElement('small');button.textContent=edge.id+' · '+nodes.get(edge.from).label+' → '+nodes.get(edge.to).label;small.textContent=edge.label+(edge.technology?' · '+edge.technology:'');button.append(small);button.addEventListener('click',()=>{locked={kind:'edge',id:edge.id};show(locked);});item.append(button);list.append(item);}
 }
 root.querySelectorAll('.node').forEach(element=>{const select=()=>{locked={kind:'node',id:element.dataset.nodeId};show(locked);};element.addEventListener('click',select);element.addEventListener('keydown',event=>{if(event.key==='Enter'||event.key===' '){event.preventDefault();select();}});element.addEventListener('mouseenter',()=>{if(!locked)show({kind:'node',id:element.dataset.nodeId});});element.addEventListener('mouseleave',()=>{if(!locked)show(null);});});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c4-architect-mcp",
-  "version": "0.2.0-alpha.1",
+  "version": "0.2.0-alpha.2",
   "description": "Local TypeScript architecture analysis with source evidence, C4 diagrams, and interactive exports over MCP",
   "type": "module",
   "bin": {