@fairfox/polly 0.73.0 → 0.74.0

package/dist/tools/visualize/src/cli.js

@@ -667,7 +667,7 @@ function detectProjectConfig(projectRoot) {
 var init_project_detector = () => {};
 
 // tools/visualize/src/cli.ts
-import * as fs6 from "node:fs";
+import * as fs7 from "node:fs";
 import * as path6 from "node:path";
 
 // tools/analysis/src/extract/architecture.ts
@@ -1864,14 +1864,37 @@ class HandlerExtractor {
       return null;
     const key = keyArg.getLiteralValue();
     const variableName = this.getVariableNameFromParent(node) || key;
+    const access = this.extractMeshAccess(args[2]);
     return {
       kind,
       key,
       variableName,
       filePath,
-      line: node.getStartLineNumber()
+      line: node.getStartLineNumber(),
+      ...access ? { access } : {}
     };
   }
+  extractMeshAccess(optionsArg) {
+    if (!optionsArg || !Node4.isObjectLiteralExpression(optionsArg))
+      return;
+    const accessProp = optionsArg.getProperty("access");
+    if (!accessProp || !Node4.isPropertyAssignment(accessProp))
+      return;
+    const accessObj = accessProp.getInitializer();
+    if (!accessObj || !Node4.isObjectLiteralExpression(accessObj))
+      return;
+    const predicateText = (name) => {
+      const prop = accessObj.getProperty(name);
+      if (!prop || !Node4.isPropertyAssignment(prop))
+        return;
+      return prop.getInitializer()?.getText().replace(/\s+/g, " ").trim();
+    };
+    const read = predicateText("read");
+    const write = predicateText("write");
+    if (read === undefined && write === undefined)
+      return;
+    return { read: read ?? "unset", write: write ?? "unset" };
+  }
   analyzeFileAndImports(sourceFile, handlers, messageTypes, invalidMessageTypes, stateConstraints, globalStateConstraints, verifiedStates, resources) {
     const filePath = sourceFile.getFilePath();
     if (this.analyzedFiles.has(filePath)) {
@@ -4567,6 +4590,122 @@ async function analyzeArchitecture(options) {
   return analyzer.analyze();
 }
 
+// src/shared/lib/derive-document-id.ts
+import {
+  interpretAsDocumentId
+} from "@automerge/automerge-repo/slim";
+import nacl from "tweetnacl";
+var DOC_ID_DOMAIN = "polly/meshState/v1";
+var keyEncoder = new TextEncoder;
+function deriveDocumentId(key) {
+  const digest = nacl.hash(keyEncoder.encode(`${DOC_ID_DOMAIN}:${key}`));
+  const bytes = digest.slice(0, 16);
+  return interpretAsDocumentId(bytes);
+}
+
+// tools/visualize/src/mesh-snapshot.ts
+import * as fs5 from "node:fs";
+
+class MeshSnapshotError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MeshSnapshotError";
+  }
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireStringArray(value, path5) {
+  if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
+    throw new MeshSnapshotError(`${path5} must be an array of strings`);
+  }
+  return value;
+}
+function validateHandle(value, path5) {
+  if (!isObject(value)) {
+    throw new MeshSnapshotError(`${path5} must be an object`);
+  }
+  if (typeof value["docSynchronizerExists"] !== "boolean") {
+    throw new MeshSnapshotError(`${path5}.docSynchronizerExists must be a boolean`);
+  }
+  const knowsPeer = value["docSynchronizerKnowsPeer"];
+  if (knowsPeer !== undefined && typeof knowsPeer !== "boolean") {
+    throw new MeshSnapshotError(`${path5}.docSynchronizerKnowsPeer must be a boolean or absent`);
+  }
+  const status = value["peerDocumentStatus"];
+  if (status !== undefined && typeof status !== "string") {
+    throw new MeshSnapshotError(`${path5}.peerDocumentStatus must be a string or absent`);
+  }
+  return value;
+}
+function validatePeer(value, path5) {
+  if (!isObject(value)) {
+    throw new MeshSnapshotError(`${path5} must be an object`);
+  }
+  if (typeof value["peerId"] !== "string") {
+    throw new MeshSnapshotError(`${path5}.peerId must be a string`);
+  }
+  const slot = value["slot"];
+  if (slot !== undefined && slot !== null) {
+    if (!isObject(slot)) {
+      throw new MeshSnapshotError(`${path5}.slot must be an object or absent`);
+    }
+    const handles = slot["handles"];
+    if (!isObject(handles)) {
+      throw new MeshSnapshotError(`${path5}.slot.handles must be an object`);
+    }
+    for (const [docId, handle] of Object.entries(handles)) {
+      validateHandle(handle, `${path5}.slot.handles[${docId}]`);
+    }
+  }
+  return value;
+}
+function validateMeshSnapshot(data) {
+  if (!isObject(data)) {
+    throw new MeshSnapshotError("snapshot must be a JSON object");
+  }
+  if (typeof data["localPeerId"] !== "string") {
+    throw new MeshSnapshotError("snapshot.localPeerId must be a string");
+  }
+  requireStringArray(data["knownPeerIds"], "snapshot.knownPeerIds");
+  requireStringArray(data["presentPeerIds"], "snapshot.presentPeerIds");
+  const peers = data["peers"];
+  if (!Array.isArray(peers)) {
+    throw new MeshSnapshotError("snapshot.peers must be an array");
+  }
+  peers.forEach((peer, i) => {
+    validatePeer(peer, `snapshot.peers[${i}]`);
+  });
+  return data;
+}
+function loadMeshSnapshot(filePath) {
+  let raw;
+  try {
+    raw = fs5.readFileSync(filePath, "utf-8");
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new MeshSnapshotError(`cannot read snapshot file '${filePath}': ${reason}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new MeshSnapshotError(`snapshot file '${filePath}' is not valid JSON: ${reason}`);
+  }
+  return validateMeshSnapshot(parsed);
+}
+function collectSnapshotPeerIds(snapshot) {
+  const ids = new Set([snapshot.localPeerId]);
+  for (const id of snapshot.knownPeerIds)
+    ids.add(id);
+  for (const id of snapshot.presentPeerIds)
+    ids.add(id);
+  for (const peer of snapshot.peers)
+    ids.add(peer.peerId);
+  return [...ids];
+}
+
 // tools/visualize/src/types/structurizr.ts
 var DEFAULT_COLORS = {
   messageHandler: "#1168bd",
@@ -4639,6 +4778,11 @@ var DEFAULT_ELEMENT_STYLES = {
     shape: "Cylinder",
     background: DEFAULT_COLORS.queryHandler,
     color: DEFAULT_COLORS.textDark
+  },
+  "Mesh Transport": {
+    shape: "Pipe",
+    background: DEFAULT_COLORS.service,
+    color: DEFAULT_COLORS.textLight
   }
 };
 var DEFAULT_RELATIONSHIP_STYLES = {
@@ -4662,12 +4806,83 @@ var DEFAULT_RELATIONSHIP_STYLES = {
     color: DEFAULT_COLORS.database
   }
 };
+var MESH_OVERLAY_ELEMENT_STYLES = {
+  "Mesh Peer": {
+    shape: "Person",
+    background: "#495057",
+    color: DEFAULT_COLORS.textLight
+  },
+  "Local Mesh Peer": {
+    shape: "Person",
+    background: DEFAULT_COLORS.messageHandler,
+    color: DEFAULT_COLORS.textLight
+  },
+  "Snapshot Document": {
+    shape: "Cylinder",
+    background: "#adb5bd",
+    color: DEFAULT_COLORS.textDark,
+    border: "Dashed"
+  }
+};
+var MESH_OVERLAY_RELATIONSHIP_STYLES = {
+  "sync:has": {
+    color: "#2f9e44",
+    style: "Solid",
+    thickness: 3
+  },
+  "sync:wants": {
+    color: "#f08c00",
+    style: "Dashed",
+    thickness: 2
+  },
+  "sync:unavailable": {
+    color: "#e03131",
+    style: "Dashed",
+    thickness: 2
+  },
+  "sync:unknown": {
+    color: "#868e96",
+    style: "Dotted",
+    thickness: 2
+  }
+};
 var DEFAULT_THEME = "https://static.structurizr.com/themes/default/theme.json";
 
 // tools/visualize/src/codegen/structurizr.ts
+var MESH_TRANSPORT_NODES = [
+  {
+    id: "mesh_net_adapter",
+    name: "MeshNetworkAdapter",
+    description: "Signs and encrypts every mesh operation"
+  },
+  {
+    id: "mesh_webrtc_adapter",
+    name: "MeshWebRTCAdapter",
+    description: "Peer-to-peer WebRTC data channels"
+  },
+  {
+    id: "mesh_signaling_client",
+    name: "MeshSignalingClient",
+    description: "WebRTC offer/answer signalling"
+  },
+  {
+    id: "mesh_signaling_endpoint",
+    name: "Signalling endpoint",
+    description: "The rendezvous server peers exchange WebRTC offers through"
+  }
+];
+function syncStatusOf(handle) {
+  const status = handle.peerDocumentStatus;
+  if (status === "has" || status === "wants" || status === "unavailable") {
+    return status;
+  }
+  return "unknown";
+}
+
 class StructurizrDSLGenerator {
   analysis;
   options;
+  overlayPlanCache;
   constructor(analysis, options = {}) {
     this.analysis = analysis;
     this.options = {
@@ -4686,10 +4901,12 @@ class StructurizrDSLGenerator {
         theme: options.styles?.theme || DEFAULT_THEME,
         elements: {
           ...DEFAULT_ELEMENT_STYLES,
+          ...options.snapshot ? MESH_OVERLAY_ELEMENT_STYLES : {},
           ...options.styles?.elements
         },
         relationships: {
           ...DEFAULT_RELATIONSHIP_STYLES,
+          ...options.snapshot ? MESH_OVERLAY_RELATIONSHIP_STYLES : {},
           ...options.styles?.relationships
         }
       }
@@ -4723,6 +4940,9 @@ class StructurizrDSLGenerator {
     const parts = [];
     parts.push("  model {");
     parts.push(this.generatePeople());
+    const meshPeers = this.generateMeshPeers();
+    if (meshPeers)
+      parts.push(meshPeers);
     parts.push(this.generateExternalSystems());
     parts.push(this.generateMainSystem());
     if (this.options.deploymentNodes && this.options.deploymentNodes.length > 0) {
@@ -4763,6 +4983,12 @@ class StructurizrDSLGenerator {
     const meshDocs = this.generateMeshDocuments();
     if (meshDocs)
       parts.push(meshDocs);
+    const snapshotDocs = this.generateSnapshotOnlyDocuments();
+    if (snapshotDocs)
+      parts.push(snapshotDocs);
+    const meshTransport = this.generateMeshTransport();
+    if (meshTransport)
+      parts.push(meshTransport);
     parts.push(this.generateContainerRelationships());
     parts.push("    }");
     return parts.join(`
@@ -4794,7 +5020,8 @@ class StructurizrDSLGenerator {
         continue;
       seen.add(sig.key);
       const kindLabel = sig.kind === "mesh" ? "Mesh Document" : "Peer Document";
-      const description = `${kindLabel} — deriveDocumentId('${sig.key}')`;
+      const access = sig.access ? ` · access read=${this.clip(sig.access.read)} write=${this.clip(sig.access.write)}` : "";
+      const description = `${kindLabel} — deriveDocumentId('${sig.key}')${access}`;
       parts.push(`      ${this.meshDocId(sig.key)} = container "${this.escape(sig.key)}" "${this.escape(description)}" "$${sig.kind}State" {`);
       parts.push(`        tags "${kindLabel}"`);
       parts.push("      }");
@@ -4805,6 +5032,9 @@ class StructurizrDSLGenerator {
   meshDocId(key) {
     return `mesh_doc_${this.toId(key)}`;
   }
+  clip(text, max = 32) {
+    return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+  }
   contextForFilePath(filePath) {
     const contextKeys = Object.keys(this.analysis.contexts);
     if (contextKeys.length === 1)
@@ -5143,6 +5373,8 @@ class StructurizrDSLGenerator {
     parts.push(...this.generateMessageFlowRelationships());
     parts.push(...this.generateExternalAPIRelationships());
     parts.push(...this.generateMeshRelationships());
+    parts.push(...this.generateMeshTransportRelationships());
+    parts.push(...this.generateMeshOverlayRelationships());
     return parts.join(`
 `);
   }
@@ -5162,6 +5394,177 @@ class StructurizrDSLGenerator {
     }
     return parts;
   }
+  meshSignalKinds() {
+    const signals = this.analysis.meshOrPeerSignals ?? [];
+    return {
+      mesh: signals.some((s) => s.kind === "mesh"),
+      peer: signals.some((s) => s.kind === "peer")
+    };
+  }
+  generateMeshTransport() {
+    const { mesh, peer } = this.meshSignalKinds();
+    if (!mesh && !peer)
+      return "";
+    const parts = [];
+    if (mesh) {
+      for (const node of MESH_TRANSPORT_NODES) {
+        parts.push(`      ${node.id} = container "${node.name}" "${this.escape(node.description)}" "Mesh Transport" {`);
+        parts.push('        tags "Mesh Transport"');
+        parts.push("      }");
+      }
+    }
+    if (peer) {
+      parts.push(`      peer_relay = container "Peer relay" "${this.escape("The always-on relay $peerState syncs through")}" "Peer Transport" {`);
+      parts.push('        tags "Mesh Transport"');
+      parts.push("      }");
+    }
+    return parts.join(`
+`);
+  }
+  generateMeshTransportRelationships() {
+    const { mesh, peer } = this.meshSignalKinds();
+    const parts = [];
+    if (mesh) {
+      parts.push('      extension.mesh_net_adapter -> extension.mesh_webrtc_adapter "wraps"');
+      parts.push('      extension.mesh_webrtc_adapter -> extension.mesh_signaling_client "negotiates via"');
+      parts.push('      extension.mesh_signaling_client -> extension.mesh_signaling_endpoint "connects to"');
+    }
+    if (!mesh && !peer)
+      return parts;
+    const seen = new Set;
+    for (const sig of this.analysis.meshOrPeerSignals ?? []) {
+      if (seen.has(sig.key))
+        continue;
+      seen.add(sig.key);
+      const target = sig.kind === "mesh" ? "mesh_net_adapter" : "peer_relay";
+      parts.push(`      extension.${this.meshDocId(sig.key)} -> extension.${target} "syncs through"`);
+    }
+    return parts;
+  }
+  getOverlayPlan() {
+    const snapshot = this.options.snapshot;
+    if (!snapshot)
+      return;
+    if (!this.overlayPlanCache) {
+      this.overlayPlanCache = this.buildOverlayPlan(snapshot);
+    }
+    return this.overlayPlanCache;
+  }
+  buildOverlayPlan(snapshot) {
+    const docIdToNode = this.buildDocIdNodeMap();
+    const { peers, peerDslById } = this.buildOverlayPeers(snapshot);
+    const { edges, snapshotOnlyDocs } = this.buildOverlayEdges(snapshot, docIdToNode, peerDslById);
+    return { peers, edges, snapshotOnlyDocs };
+  }
+  buildDocIdNodeMap() {
+    const docIdToNode = new Map;
+    const seenKeys = new Set;
+    for (const sig of this.analysis.meshOrPeerSignals ?? []) {
+      if (seenKeys.has(sig.key))
+        continue;
+      seenKeys.add(sig.key);
+      docIdToNode.set(String(deriveDocumentId(sig.key)), this.meshDocId(sig.key));
+    }
+    return docIdToNode;
+  }
+  buildOverlayPeers(snapshot) {
+    const peers = [];
+    const peerDslById = new Map;
+    const usedPeerIds = new Set;
+    for (const peerId of collectSnapshotPeerIds(snapshot)) {
+      const base = `peer_${this.toId(peerId)}`;
+      let id = base;
+      let suffix = 2;
+      while (usedPeerIds.has(id))
+        id = `${base}_${suffix++}`;
+      usedPeerIds.add(id);
+      peerDslById.set(peerId, id);
+      peers.push({ id, peerId, isLocal: peerId === snapshot.localPeerId });
+    }
+    return { peers, peerDslById };
+  }
+  buildOverlayEdges(snapshot, docIdToNode, peerDslById) {
+    const edges = [];
+    const snapshotOnlyDocs = [];
+    const snapshotOnlyById = new Map;
+    for (const peer of snapshot.peers) {
+      const handles = peer.slot?.handles;
+      const fromId = peerDslById.get(peer.peerId);
+      if (!handles || !fromId)
+        continue;
+      for (const [docId, handle] of Object.entries(handles)) {
+        const nodeId = this.resolveOverlayDocNode(docId, docIdToNode, snapshotOnlyById, snapshotOnlyDocs);
+        const status = syncStatusOf(handle);
+        edges.push({
+          fromId,
+          toRef: `extension.${nodeId}`,
+          status,
+          label: this.overlayEdgeLabel(status, handle)
+        });
+      }
+    }
+    return { edges, snapshotOnlyDocs };
+  }
+  resolveOverlayDocNode(docId, docIdToNode, snapshotOnlyById, snapshotOnlyDocs) {
+    const staticNode = docIdToNode.get(docId);
+    if (staticNode)
+      return staticNode;
+    const existing = snapshotOnlyById.get(docId);
+    if (existing)
+      return existing;
+    const nodeId = `mesh_doc_${this.toId(docId)}`;
+    snapshotOnlyById.set(docId, nodeId);
+    snapshotOnlyDocs.push({ id: nodeId, docId });
+    return nodeId;
+  }
+  overlayEdgeLabel(status, handle) {
+    if (!handle.docSynchronizerExists)
+      return `${status} · no synchronizer`;
+    if (handle.docSynchronizerKnowsPeer === false)
+      return `${status} · peer not added`;
+    return status;
+  }
+  generateMeshPeers() {
+    const plan = this.getOverlayPlan();
+    if (!plan || plan.peers.length === 0)
+      return "";
+    const parts = [];
+    for (const peer of plan.peers) {
+      const tag = peer.isLocal ? "Local Mesh Peer" : "Mesh Peer";
+      const description = peer.isLocal ? "Local mesh peer (this node)" : "Runtime mesh peer";
+      parts.push(`    ${peer.id} = person "${this.escape(peer.peerId)}" "${description}" {`);
+      parts.push(`      tags "${tag}"`);
+      parts.push("    }");
+    }
+    return parts.join(`
+`);
+  }
+  generateSnapshotOnlyDocuments() {
+    const plan = this.getOverlayPlan();
+    if (!plan || plan.snapshotOnlyDocs.length === 0)
+      return "";
+    const parts = [];
+    for (const doc of plan.snapshotOnlyDocs) {
+      const description = `Mesh document seen only in the runtime snapshot — docId ${doc.docId}`;
+      parts.push(`      ${doc.id} = container "${this.escape(doc.docId)}" "${this.escape(description)}" "snapshot" {`);
+      parts.push('        tags "Snapshot Document"');
+      parts.push("      }");
+    }
+    return parts.join(`
+`);
+  }
+  generateMeshOverlayRelationships() {
+    const plan = this.getOverlayPlan();
+    if (!plan)
+      return [];
+    const parts = [];
+    for (const edge of plan.edges) {
+      parts.push(`      ${edge.fromId} -> ${edge.toRef} "${this.escape(edge.label)}" {`);
+      parts.push(`        tags "sync:${edge.status}"`);
+      parts.push("      }");
+    }
+    return parts;
+  }
   generateUserRelationships() {
     const parts = [];
     const uiContexts = ["popup", "options", "devtools"];
@@ -5909,7 +6312,7 @@ function generateStructurizrDSL(analysis, options) {
 
 // tools/visualize/src/runner/export.ts
 import { spawn } from "node:child_process";
-import * as fs5 from "node:fs";
+import * as fs6 from "node:fs";
 import * as path5 from "node:path";
 
 class DiagramExporter {
@@ -5917,15 +6320,15 @@ class DiagramExporter {
   static DEFAULT_TIMEOUT = 120000;
   async export(options) {
     const { dslPath, outputDir, timeout = DiagramExporter.DEFAULT_TIMEOUT } = options;
-    if (!fs5.existsSync(dslPath)) {
+    if (!fs6.existsSync(dslPath)) {
       return {
         success: false,
         siteDir: "",
         error: `DSL file not found: ${dslPath}`
       };
     }
-    if (!fs5.existsSync(outputDir)) {
-      fs5.mkdirSync(outputDir, { recursive: true });
+    if (!fs6.existsSync(outputDir)) {
+      fs6.mkdirSync(outputDir, { recursive: true });
     }
     const dockerAvailable = await this.isDockerAvailable();
     if (!dockerAvailable) {
@@ -6073,7 +6476,7 @@ async function main() {
   switch (command) {
     case "--generate":
     case "generate":
-      await generateCommand();
+      await generateCommand(args.slice(1));
       break;
     case "--export":
     case "export":
@@ -6090,22 +6493,64 @@ async function main() {
       showHelp();
       break;
     default:
-      await generateCommand();
+      await generateCommand(args);
   }
 }
-async function generateCommand() {
+async function generateCommand(args) {
   console.log(color(`
 \uD83D\uDCCA Analyzing architecture...
 `, COLORS.blue));
   try {
+    const { snapshotPath } = parseGenerateArgs(args);
+    const snapshot = snapshotPath ? loadAndReportSnapshot(snapshotPath) : undefined;
     const { tsConfigPath, projectRoot } = findAndDisplayProjectConfig();
     const analysis = await analyzeAndDisplayResults(tsConfigPath, projectRoot);
-    const dslPath = generateAndWriteDSL(analysis);
+    const dslPath = generateAndWriteDSL(analysis, snapshot);
     displayNextSteps(dslPath);
   } catch (_error) {
     process.exit(1);
   }
 }
+function parseGenerateArgs(args) {
+  const result = {};
+  for (let i = 0;i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--snapshot") {
+      const next = args[i + 1];
+      if (!next || next.startsWith("--")) {
+        console.log(color(`
+✗ --snapshot requires a file path
+`, COLORS.red));
+        process.exit(1);
+      }
+      result.snapshotPath = next;
+      i++;
+    } else if (arg?.startsWith("--snapshot=")) {
+      result.snapshotPath = arg.slice("--snapshot=".length);
+    }
+  }
+  return result;
+}
+function loadAndReportSnapshot(snapshotPath) {
+  let snapshot;
+  try {
+    snapshot = loadMeshSnapshot(snapshotPath);
+  } catch (error) {
+    const message = error instanceof MeshSnapshotError ? error.message : String(error);
+    console.log(color(`
+✗ Snapshot error: ${message}
+`, COLORS.red));
+    process.exit(1);
+  }
+  const isEmpty = snapshot.knownPeerIds.length === 0 && snapshot.presentPeerIds.length === 0 && snapshot.peers.length === 0;
+  if (isEmpty) {
+    console.log(color("⚠ Snapshot has no peers — generating the static diagram only.", COLORS.yellow));
+    return;
+  }
+  const peerCount = collectSnapshotPeerIds(snapshot).length;
+  console.log(color(`✓ Loaded runtime snapshot: ${peerCount} peer(s)`, COLORS.green));
+  return snapshot;
+}
 function findAndDisplayProjectConfig() {
   const tsConfigPath = findTsConfig();
   if (!tsConfigPath) {
@@ -6121,7 +6566,7 @@ function findAndDisplayProjectConfig() {
   return { tsConfigPath, projectRoot };
 }
 function displayProjectType(projectRoot) {
-  const hasManifest = fs6.existsSync(path6.join(projectRoot, "manifest.json"));
+  const hasManifest = fs7.existsSync(path6.join(projectRoot, "manifest.json"));
   const projectType = hasManifest ? "Chrome Extension" : "Detecting from project structure...";
   console.log(color(`   Type: ${projectType}`, COLORS.gray));
 }
@@ -6155,7 +6600,7 @@ function displayArchitectureSummary(analysis) {
     }
   }
 }
-function generateAndWriteDSL(analysis) {
+function generateAndWriteDSL(analysis, snapshot) {
   console.log(color(`
 \uD83D\uDCDD Generating Structurizr DSL...
 `, COLORS.blue));
@@ -6163,14 +6608,15 @@ function generateAndWriteDSL(analysis) {
   const dsl = generateStructurizrDSL(analysis, {
     includeDynamicDiagrams: true,
     includeComponentDiagrams: true,
-    componentDiagramContexts: contextTypes.length > 0 ? contextTypes : ["background"]
+    componentDiagramContexts: contextTypes.length > 0 ? contextTypes : ["background"],
+    snapshot
   });
   const outputDir = path6.join(process.cwd(), "docs");
-  if (!fs6.existsSync(outputDir)) {
-    fs6.mkdirSync(outputDir, { recursive: true });
+  if (!fs7.existsSync(outputDir)) {
+    fs7.mkdirSync(outputDir, { recursive: true });
   }
   const dslPath = path6.join(outputDir, "architecture.dsl");
-  fs6.writeFileSync(dslPath, dsl, "utf-8");
+  fs7.writeFileSync(dslPath, dsl, "utf-8");
   return dslPath;
 }
 function displayNextSteps(dslPath) {
@@ -6206,7 +6652,7 @@ async function exportCommand(_args) {
 `, COLORS.blue));
   try {
     const dslPath = path6.join(process.cwd(), "docs", "architecture.dsl");
-    if (!fs6.existsSync(dslPath)) {
+    if (!fs7.existsSync(dslPath)) {
       process.exit(1);
     }
     const outputDir = path6.join(process.cwd(), "docs", "site");
@@ -6244,7 +6690,7 @@ async function serveCommand(args) {
   try {
     const siteDir = path6.join(process.cwd(), "docs", "site");
     const indexPath = path6.join(siteDir, "index.html");
-    if (!fs6.existsSync(indexPath)) {
+    if (!fs7.existsSync(indexPath)) {
       process.exit(1);
     }
     const portArg = args.find((arg) => arg.startsWith("--port="));
@@ -6261,7 +6707,7 @@ async function serveCommand(args) {
       fetch(req) {
         const url = new URL(req.url);
         const filePath = path6.join(siteDir, url.pathname === "/" ? "index.html" : url.pathname);
-        if (fs6.existsSync(filePath) && fs6.statSync(filePath).isFile()) {
+        if (fs7.existsSync(filePath) && fs7.statSync(filePath).isFile()) {
           const file = BunGlobal.file(filePath);
           return new Response(file);
         }
@@ -6305,6 +6751,10 @@ ${color("Commands:", COLORS.blue)}
   ${color("bun visualize --generate", COLORS.green)}
     Analyze codebase and generate Structurizr DSL
 
+  ${color("bun visualize generate --snapshot <path>", COLORS.green)}
+    Overlay a captured MeshClientPeerStateSnapshot — runtime mesh peers
+    and sync-state-coloured replication edges — onto the diagram
+
   ${color("bun visualize --export", COLORS.green)}
     Generate static HTML site with interactive diagrams (requires Docker)
 
@@ -6341,7 +6791,7 @@ function findTsConfig() {
     path6.join(process.cwd(), "..", "tsconfig.json")
   ];
   for (const loc of locations) {
-    if (fs6.existsSync(loc)) {
+    if (fs7.existsSync(loc)) {
       return loc;
     }
   }
@@ -6350,7 +6800,7 @@ function findTsConfig() {
 function findProjectRoot() {
   const locations = [process.cwd(), path6.join(process.cwd(), "..")];
   for (const loc of locations) {
-    if (fs6.existsSync(path6.join(loc, "manifest.json")) || fs6.existsSync(path6.join(loc, "package.json")) || fs6.existsSync(path6.join(loc, "tsconfig.json"))) {
+    if (fs7.existsSync(path6.join(loc, "manifest.json")) || fs7.existsSync(path6.join(loc, "package.json")) || fs7.existsSync(path6.join(loc, "tsconfig.json"))) {
       return loc;
     }
   }
@@ -6360,4 +6810,4 @@ main().catch((_error) => {
   process.exit(1);
 });
 
-//# debugId=D0F61C41F83644F864756E2164756E21
+//# debugId=4CFC761842CDF97B64756E2164756E21