@documentation-robotics/cli 0.1.0 → 0.1.7

package/dist/server/server.js

@@ -1,60 +1,298 @@
-import { Hono } from "hono";
-import { upgradeWebSocket, websocket } from "hono/bun";
+import { OpenAPIHono, createRoute, z } from "@hono/zod-openapi";
 import { cors } from "hono/cors";
-import { serve } from "bun";
+import { swaggerUI } from "@hono/swagger-ui";
+import { randomBytes } from "crypto";
+import { createRequire } from "module";
+import { fileURLToPath } from "url";
+import path from "path";
+let upgradeWebSocket, websocket;
+const require2 = createRequire(import.meta.url);
 import { Model } from "../core/model.js";
+import { StagedChangesetStorage } from "../core/staged-changeset-storage.js";
 import { telemetryMiddleware } from "./telemetry-middleware.js";
+import { ClaudeCodeClient } from "../coding-agents/claude-code-client.js";
+import { CopilotClient } from "../coding-agents/copilot-client.js";
+import { detectAvailableClients, selectChatClient } from "../coding-agents/chat-utils.js";
+import { getErrorMessage } from "../utils/errors.js";
+import { AnnotationCreateSchema, AnnotationUpdateSchema, AnnotationReplyCreateSchema, LayerNameSchema, IdSchema, AnnotationFilterSchema, ErrorResponseSchema, HealthResponseSchema, AnnotationSchema, AnnotationReplySchema, AnnotationsListSchema, ChangesetsListSchema, ChangesetDetailSchema, ModelResponseSchema, LayerResponseSchema, SpecResponseSchema, AnnotationRepliesSchema, WSMessageSchema } from "./schemas.js";
+const JSONRPC_ERRORS = {
+  // Standard JSON-RPC errors
+  INVALID_PARAMS: -32602,
+  // Invalid method parameters
+  METHOD_NOT_FOUND: -32601,
+  // Method does not exist
+  INTERNAL_ERROR: -32603,
+  // Internal server error
+  // Custom application errors
+  NO_CLIENT_AVAILABLE: -32001
+  // No chat client available
+};
 class VisualizationServer {
   app;
   model;
   _server;
+  // Bun.serve return type, loaded dynamically
   clients = /* @__PURE__ */ new Set();
   watcher;
   annotations = /* @__PURE__ */ new Map();
   // annotationId -> annotation
   annotationsByElement = /* @__PURE__ */ new Map();
   // elementId -> Set<annotationId>
+  replies = /* @__PURE__ */ new Map();
+  // annotationId -> replies[]
   changesets = /* @__PURE__ */ new Map();
   // changesetId -> changeset
+  changesetStorage;
   authToken;
   authEnabled = !0;
-  // Enabled by default for security
+  withDanger = !1;
+  // Danger mode disabled by default
+  viewerPath;
+  // Optional custom viewer path
   activeChatProcesses = /* @__PURE__ */ new Map();
   // conversationId -> Bun.spawn process
   chatConversationCounter = 0;
+  selectedChatClient;
+  // Selected chat client for server
+  chatInitializationError;
+  // Store initialization error for status endpoint
+  /**
+   * Valid spec node IDs per layer
+   * Dynamically loaded from compiled spec (spec/dist/{layer}.json at module load time)
+   * Used to validate and resolve viewer spec node IDs
+   * Prevents silent drift when node types are added to spec/schemas/nodes/
+   */
+  static VALID_SPEC_NODE_IDS = VisualizationServer.loadValidSpecNodeIds();
+  /**
+   * Load valid spec node IDs dynamically from bundled spec files
+   * Extracts node_types arrays from each layer's compiled schema file
+   * This ensures the list is always in sync with the spec build output
+   * If any file cannot be loaded, falls back to a minimal safe set
+   */
+  static loadValidSpecNodeIds() {
+    const result = {}, requiredLayers = [
+      "motivation",
+      "business",
+      "security",
+      "application",
+      "technology",
+      "api",
+      "data-model",
+      "data-store",
+      "ux",
+      "navigation",
+      "apm",
+      "testing"
+    ], __dirname = path.dirname(fileURLToPath(import.meta.url)), bundledDir = path.join(__dirname, "..", "schemas", "bundled");
+    for (const layer of requiredLayers)
+      try {
+        const specFilePath = path.join(bundledDir, `${layer}.json`), nodeTypes = require2(specFilePath).layer?.node_types;
+        Array.isArray(nodeTypes) && nodeTypes.length > 0 ? result[layer] = nodeTypes : (console.warn(`[SPEC-LOAD-001] Layer ${layer} has no node_types in spec file`), result[layer] = []);
+      } catch (error) {
+        console.warn(`[SPEC-LOAD-002] Failed to load spec node IDs for layer ${layer}: ${getErrorMessage(error)}`), result[layer] = [];
+      }
+    return result;
+  }
+  /**
+   * Fallback spec node IDs used when type extraction from elementId fails
+   * These are used when no valid spec node ID can be extracted from the elementId
+   * or found through other resolution strategies
+   */
+  static LAYER_FALLBACK = {
+    security: "business.businessprocess",
+    technology: "application.applicationservice",
+    api: "business.businessprocess",
+    "data-model": "data-store.database",
+    "data-store": "data-store.database",
+    ux: "application.applicationcomponent",
+    navigation: "application.applicationcomponent",
+    apm: "application.applicationservice",
+    testing: "business.businessprocess"
+  };
+  /**
+   * All valid spec node IDs across all layers (cached Set for O(1) lookup)
+   */
+  static ALL_VALID_IDS = (() => {
+    const ids = /* @__PURE__ */ new Set();
+    return Object.values(VisualizationServer.VALID_SPEC_NODE_IDS).forEach((layerIds) => {
+      layerIds.forEach((id) => ids.add(id));
+    }), ids;
+  })();
   constructor(model, options) {
-    this.app = new Hono(), this.model = model, this.authEnabled = options?.authEnabled ?? process.env.DR_AUTH_ENABLED !== "false", this.authToken = options?.authToken || process.env.DR_AUTH_TOKEN || this.generateAuthToken(), this.app.use("/*", cors()), this.app.use("/*", telemetryMiddleware), this.app.use("/api/*", async (c, next) => {
+    this.app = new OpenAPIHono(), this.model = model, this.loadBunAdapters(), this.authEnabled = options?.authEnabled ?? process.env.DR_AUTH_ENABLED !== "false", this.authToken = options?.authToken || process.env.DR_AUTH_TOKEN || this.generateAuthToken(), this.withDanger = options?.withDanger || !1, this.viewerPath = options?.viewerPath || new URL("../viewer", import.meta.url).pathname, !this.authEnabled && options?.authToken && console.warn("[VisualizationServer] Warning: authToken provided but authEnabled is false. The token will be generated but not used for authentication. Set authEnabled: true to enable authentication."), this.app.use("/*", cors()), this.app.use("/*", telemetryMiddleware), this.app.use("/api/*", async (c, next) => {
       if (!this.authEnabled)
         return next();
       const authHeader = c.req.header("Authorization"), queryToken = c.req.query("token");
       let providedToken = null;
       return authHeader && authHeader.startsWith("Bearer ") ? providedToken = authHeader.substring(7) : queryToken && (providedToken = queryToken), providedToken ? providedToken !== this.authToken ? c.json({ error: "Invalid authentication token" }, 403) : next() : c.json({ error: "Authentication required. Please provide a valid token." }, 401);
-    }), this.setupRoutes(), this.authEnabled && process.env.VERBOSE && console.log(`[Auth] Authentication enabled. Token: ${this.authToken}`);
+    }), this.setupRoutes(), this.authEnabled && process.env.VERBOSE && console.log(`[Auth] Authentication enabled. Token: ${this.authToken}`), this.initializeChatClients().catch((error) => {
+      this.chatInitializationError = error instanceof Error ? error : new Error(String(error)), console.error("[Chat] Failed to initialize chat clients:", error);
+    });
+  }
+  /**
+   * Load Bun-specific WebSocket adapters if available
+   * This is called in the constructor to support WebSocket functionality in Bun runtime
+   * In Node.js/tsx environments (e.g., generating OpenAPI spec), these imports are skipped
+   */
+  loadBunAdapters() {
+    if (typeof global.Bun < "u")
+      try {
+        const honoModule = require2("hono/bun");
+        upgradeWebSocket = honoModule.upgradeWebSocket, websocket = honoModule.websocket;
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`[Server] WARNING: Could not load WebSocket adapters from hono/bun: ${message}. WebSocket endpoints (/ws) will not be available. Please ensure 'hono' is installed and the Bun runtime is properly configured.`), process.env.VERBOSE && error instanceof Error && error.stack && console.debug("[Server] Stack trace:", error.stack);
+      }
+  }
+  /**
+   * Detect and initialize available chat clients
+   */
+  async initializeChatClients() {
+    const clients = await detectAvailableClients();
+    this.selectedChatClient = selectChatClient(clients, null), this.selectedChatClient && process.env.VERBOSE ? console.log(`[Chat] Using chat client: ${this.selectedChatClient.getClientName()}`) : clients.length === 0 && process.env.VERBOSE && console.log("[Chat] No chat clients available");
   }
   /**
    * Generate a random auth token
    */
   generateAuthToken() {
-    return `dr-${Date.now()}-${Math.random().toString(36).substring(2, 15)}`;
+    return `dr-${randomBytes(24).toString("base64url")}`;
+  }
+  /**
+   * Shared annotation update logic for PUT/PATCH handlers
+   * Performs partial updates with atomic operations
+   */
+  async updateAnnotation(annotationId, body) {
+    const annotation = this.annotations.get(annotationId);
+    if (!annotation)
+      return null;
+    const updatedAnnotation = {
+      ...annotation,
+      content: body.content ?? annotation.content,
+      tags: body.tags ?? annotation.tags,
+      resolved: body.resolved ?? annotation.resolved,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    return this.annotations.set(annotationId, updatedAnnotation), await this.broadcastMessage({
+      type: "annotation.updated",
+      annotationId: updatedAnnotation.id,
+      timestamp: updatedAnnotation.updatedAt
+    }), updatedAnnotation;
   }
   /**
    * Setup HTTP routes and WebSocket handler
    */
   setupRoutes() {
-    this.app.get("/", (c) => c.html(this.getViewerHTML())), this.app.get("/health", (c) => c.json({
-      status: "ok",
-      version: "0.1.0"
-    })), this.app.get("/api/model", async (c) => {
+    this.app.openAPIRegistry.registerComponent("securitySchemes", "bearerAuth", {
+      type: "http",
+      scheme: "bearer",
+      description: "API token (shown at server startup, pass as Authorization: Bearer <token>)"
+    }), this.app.get("/", (c) => this.viewerPath ? this.serveCustomViewer("index.html") : c.html(this.getViewerHTML())), this.viewerPath && this.app.get("/*", async (c, next) => {
+      const requestPath = c.req.path;
+      return process.env.VERBOSE && console.log(`[ROUTE] Catch-all matched: ${requestPath}`), requestPath.startsWith("/api/") || requestPath === "/ws" || requestPath === "/health" || requestPath === "/api-spec.yaml" || requestPath === "/api-docs" ? (process.env.VERBOSE && console.log(`[ROUTE] Catch-all delegating to next handler for: ${requestPath}`), next()) : (process.env.VERBOSE && console.log(`[ROUTE] Catch-all serving custom viewer file: ${requestPath}`), this.serveCustomViewer(requestPath.substring(1)));
+    });
+    const healthRoute = createRoute({
+      method: "get",
+      path: "/health",
+      tags: ["Health"],
+      summary: "Health check",
+      description: "Check if the server is running and healthy",
+      responses: {
+        200: {
+          description: "Server is healthy",
+          content: {
+            "application/json": {
+              schema: HealthResponseSchema
+            }
+          }
+        }
+      }
+    });
+    this.app.openapi(healthRoute, (c) => {
+      const response = {
+        status: this.chatInitializationError ? "degraded" : "ok",
+        version: "0.1.0"
+      };
+      return this.chatInitializationError && (response.warnings = [
+        `Chat service unavailable: ${getErrorMessage(this.chatInitializationError)}`
+      ]), c.json(response);
+    });
+    const getModelRoute = createRoute({
+      method: "get",
+      path: "/api/model",
+      tags: ["Model"],
+      summary: "Get full model",
+      description: "Retrieve the complete architecture model across all layers",
+      security: [{ bearerAuth: [] }],
+      responses: {
+        200: {
+          description: "Model data retrieved successfully",
+          content: {
+            "application/json": {
+              schema: ModelResponseSchema
+            }
+          }
+        },
+        500: {
+          description: "Server error",
+          content: {
+            "application/json": {
+              schema: ErrorResponseSchema
+            }
+          }
+        }
+      }
+    });
+    this.app.openapi(getModelRoute, async (c) => {
+      process.env.VERBOSE && console.log("[ROUTE] /api/model handler called");
       try {
+        process.env.VERBOSE && console.log("[ROUTE] /api/model serializing model...");
         const modelData = await this.serializeModel();
-        return c.json(modelData);
+        return process.env.VERBOSE && console.log(`[ROUTE] /api/model returning ${Object.keys(modelData.layers || {}).length} layers`), c.json(modelData);
       } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return c.json({ error: message }, 500);
+        const message = getErrorMessage(error);
+        return console.error(`[ROUTE] /api/model error: ${message}`), c.json({ error: message }, 500);
       }
-    }), this.app.get("/api/layers/:name", async (c) => {
+    });
+    const getLayerRoute = createRoute({
+      method: "get",
+      path: "/api/layers/:layerName",
+      tags: ["Model"],
+      summary: "Get layer",
+      description: "Retrieve a specific layer with all its elements",
+      security: [{ bearerAuth: [] }],
+      request: {
+        params: z.object({ layerName: LayerNameSchema })
+      },
+      responses: {
+        200: {
+          description: "Layer retrieved successfully",
+          content: {
+            "application/json": {
+              schema: LayerResponseSchema
+            }
+          }
+        },
+        404: {
+          description: "Layer not found",
+          content: {
+            "application/json": {
+              schema: ErrorResponseSchema
+            }
+          }
+        },
+        500: {
+          description: "Server error",
+          content: {
+            "application/json": {
+              schema: ErrorResponseSchema
+            }
+          }
+        }
+      }
+    });
+    this.app.openapi(getLayerRoute, async (c) => {
       try {
-        const layerName = c.req.param("name"), layer = await this.model.getLayer(layerName);
+        const { layerName } = c.req.valid("param"), layer = await this.model.getLayer(layerName);
         if (!layer)
           return c.json({ error: "Layer not found" }, 404);
         const elements = layer.listElements().map((e) => e.toJSON());
@@ -64,21 +302,37 @@ class VisualizationServer {
           elementCount: elements.length
         });
       } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
+        const message = getErrorMessage(error);
         return c.json({ error: message }, 500);
       }
-    }), this.app.get("/api/elements/:id", async (c) => {
-      try {
-        const elementId = c.req.param("id"), element = await this.findElement(elementId);
-        return element ? c.json({
-          ...element.toJSON(),
-          annotations: this.annotations.get(elementId) || []
-        }) : c.json({ error: "Element not found" }, 404);
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return c.json({ error: message }, 500);
+    });
+    const getSpecRoute = createRoute({
+      method: "get",
+      path: "/api/spec",
+      tags: ["Schema"],
+      summary: "Get JSON schemas",
+      description: "Retrieve all JSON Schema definitions used by the system",
+      security: [{ bearerAuth: [] }],
+      responses: {
+        200: {
+          description: "Schemas retrieved successfully",
+          content: {
+            "application/json": {
+              schema: SpecResponseSchema
+            }
+          }
+        },
+        500: {
+          description: "Server error",
+          content: {
+            "application/json": {
+              schema: ErrorResponseSchema
+            }
+          }
+        }
       }
-    }), this.app.get("/api/spec", async (c) => {
+    });
+    this.app.openapi(getSpecRoute, async (c) => {
       try {
         const schemas = await this.loadSchemas();
         return c.json({
@@ -90,19 +344,33 @@ class VisualizationServer {
           schemaCount: Object.keys(schemas).length
         });
       } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
+        const message = getErrorMessage(error);
         return c.json({ error: message }, 500);
       }
-    }), this.app.get("/api/link-registry", async (c) => {
-      try {
-        const linkRegistry = await this.loadLinkRegistry();
-        return c.json(linkRegistry);
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return c.json({ error: message }, 404);
+    });
+    const getAnnotationsRoute = createRoute({
+      method: "get",
+      path: "/api/annotations",
+      tags: ["Annotations"],
+      summary: "Get annotations",
+      description: "Retrieve all annotations, optionally filtered by element",
+      security: [{ bearerAuth: [] }],
+      request: {
+        query: AnnotationFilterSchema
+      },
+      responses: {
+        200: {
+          description: "Annotations retrieved successfully",
+          content: {
+            "application/json": {
+              schema: AnnotationsListSchema
+            }
+          }
+        }
       }
-    }), this.app.get("/api/annotations", (c) => {
-      const elementId = c.req.query("elementId");
+    });
+    this.app.openapi(getAnnotationsRoute, (c) => {
+      const elementId = c.req.valid("query").elementId;
       if (elementId) {
         const annotationIds = this.annotationsByElement.get(elementId) || /* @__PURE__ */ new Set(), annotations = Array.from(annotationIds).map((id) => this.annotations.get(id)).filter((a) => a !== void 0);
         return c.json({ annotations });
@@ -110,22 +378,72 @@ class VisualizationServer {
         const annotations = Array.from(this.annotations.values());
         return c.json({ annotations });
       }
-    }), this.app.post("/api/annotations", async (c) => {
+    });
+    const createAnnotationRoute = createRoute({
+      method: "post",
+      path: "/api/annotations",
+      tags: ["Annotations"],
+      summary: "Create annotation",
+      description: "Create a new annotation on a model element",
+      security: [{ bearerAuth: [] }],
+      request: {
+        body: {
+          content: {
+            "application/json": {
+              schema: AnnotationCreateSchema
+            }
+          }
+        }
+      },
+      responses: {
+        201: {
+          description: "Annotation created successfully",
+          content: {
+            "application/json": {
+              schema: AnnotationSchema
+            }
+          }
+        },
+        400: {
+          description: "Invalid request body",
+          content: {
+            "application/json": {
+              schema: ErrorResponseSchema
+            }
+          }
+        },
+        404: {
+          description: "Element not found",
+          content: {
+            "application/json": {
+              schema: ErrorResponseSchema
+            }
+          }
+        },
+        500: {
+          description: "Server error",
+          content: {
+            "application/json": {
+              schema: ErrorResponseSchema
+            }
+          }
+        }
+      }
+    });
+    this.app.openapi(createAnnotationRoute, async (c) => {
       try {
-        const body = await c.req.json();
-        if (!body.elementId || !body.content || !body.author)
-          return c.json({
-            error: "Missing required fields: elementId, content, author"
-          }, 400);
+        const body = c.req.valid("json");
         if (!await this.findElement(body.elementId))
           return c.json({ error: "Element not found" }, 404);
         const annotation = {
           id: this.generateAnnotationId(),
-          elementId: String(body.elementId),
-          author: String(body.author),
-          content: String(body.content),
+          elementId: body.elementId,
+          author: body.author,
+          content: body.content,
           createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-          tags: body.tags || []
+          tags: body.tags,
+          resolved: !1
+          // Default to unresolved
         };
         return this.annotations.set(annotation.id, annotation), this.annotationsByElement.has(annotation.elementId) || this.annotationsByElement.set(annotation.elementId, /* @__PURE__ */ new Set()), this.annotationsByElement.get(annotation.elementId).add(annotation.id), await this.broadcastMessage({
           type: "annotation.added",
@@ -134,30 +452,200 @@ class VisualizationServer {
           timestamp: annotation.createdAt
         }), c.json(annotation, 201);
       } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
+        const message = getErrorMessage(error);
         return c.json({ error: message }, 500);
       }
-    }), this.app.put("/api/annotations/:annotationId", async (c) => {
+    });
+    const getAnnotationRoute = createRoute({
+      method: "get",
+      path: "/api/annotations/:annotationId",
+      tags: ["Annotations"],
+      summary: "Get annotation by ID",
+      description: "Retrieve a specific annotation by its ID",
+      security: [{ bearerAuth: [] }],
+      request: {
+        params: z.object({ annotationId: IdSchema })
+      },
+      responses: {
+        200: {
+          description: "Annotation retrieved successfully",
+          content: {
+            "application/json": {
+              schema: AnnotationSchema
+            }
+          }
+        },
+        404: {
+          description: "Annotation not found",
+          content: {
+            "application/json": {
+              schema: ErrorResponseSchema
+            }
+          }
+        },
+        500: {
+          description: "Server error",
+          content: {
+            "application/json": {
+              schema: ErrorResponseSchema
+            }
+          }
+        }
+      }
+    });
+    this.app.openapi(getAnnotationRoute, async (c) => {
       try {
-        const annotationId = c.req.param("annotationId"), annotation = this.annotations.get(annotationId);
-        if (!annotation)
-          return c.json({ error: "Annotation not found" }, 404);
-        const body = await c.req.json();
-        return body.content !== void 0 && (annotation.content = String(body.content)), body.tags !== void 0 && (annotation.tags = body.tags), annotation.updatedAt = (/* @__PURE__ */ new Date()).toISOString(), await this.broadcastMessage({
-          type: "annotation.updated",
-          annotationId: annotation.id,
-          timestamp: annotation.updatedAt
-        }), c.json(annotation);
+        const { annotationId } = c.req.valid("param"), annotation = this.annotations.get(annotationId);
+        return annotation ? c.json(annotation) : c.json({ error: "Annotation not found" }, 404);
       } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
+        const message = getErrorMessage(error);
+        return c.json({ error: message }, 500);
+      }
+    });
+    const putAnnotationRoute = createRoute({
+      method: "put",
+      path: "/api/annotations/:annotationId",
+      tags: ["Annotations"],
+      summary: "Update annotation (partial)",
+      description: "Update an existing annotation with partial fields (NOTE: partial updates, use PATCH for recommended behavior)",
+      security: [{ bearerAuth: [] }],
+      request: {
+        params: z.object({ annotationId: IdSchema }),
+        body: {
+          content: {
+            "application/json": {
+              schema: AnnotationUpdateSchema
+            }
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: "Annotation updated successfully",
+          content: {
+            "application/json": {
+              schema: AnnotationSchema
+            }
+          }
+        },
+        404: {
+          description: "Annotation not found",
+          content: {
+            "application/json": {
+              schema: ErrorResponseSchema
+            }
+          }
+        },
+        500: {
+          description: "Server error",
+          content: {
+            "application/json": {
+              schema: ErrorResponseSchema
+            }
+          }
+        }
+      }
+    });
+    this.app.openapi(putAnnotationRoute, async (c) => {
+      try {
+        const { annotationId } = c.req.valid("param"), body = c.req.valid("json"), updatedAnnotation = await this.updateAnnotation(annotationId, body);
+        return updatedAnnotation ? c.json(updatedAnnotation) : c.json({ error: "Annotation not found" }, 404);
+      } catch (error) {
+        const message = getErrorMessage(error);
+        return c.json({ error: message }, 500);
+      }
+    });
+    const patchAnnotationRoute = createRoute({
+      method: "patch",
+      path: "/api/annotations/:annotationId",
+      tags: ["Annotations"],
+      summary: "Partially update annotation",
+      description: "Partially update an existing annotation (recommended over PUT)",
+      security: [{ bearerAuth: [] }],
+      request: {
+        params: z.object({ annotationId: IdSchema }),
+        body: {
+          content: {
+            "application/json": {
+              schema: AnnotationUpdateSchema
+            }
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: "Annotation updated successfully",
+          content: {
+            "application/json": {
+              schema: AnnotationSchema
+            }
+          }
+        },
+        404: {
+          description: "Annotation not found",
+          content: {
+            "application/json": {
+              schema: ErrorResponseSchema
+            }
+          }
+        },
+        500: {
+          description: "Server error",
+          content: {
+            "application/json": {
+              schema: ErrorResponseSchema
+            }
+          }
+        }
+      }
+    });
+    this.app.openapi(patchAnnotationRoute, async (c) => {
+      try {
+        const { annotationId } = c.req.valid("param"), body = c.req.valid("json"), updatedAnnotation = await this.updateAnnotation(annotationId, body);
+        return updatedAnnotation ? c.json(updatedAnnotation) : c.json({ error: "Annotation not found" }, 404);
+      } catch (error) {
+        const message = getErrorMessage(error);
         return c.json({ error: message }, 500);
       }
-    }), this.app.delete("/api/annotations/:annotationId", async (c) => {
+    });
+    const deleteAnnotationRoute = createRoute({
+      method: "delete",
+      path: "/api/annotations/:annotationId",
+      tags: ["Annotations"],
+      summary: "Delete annotation",
+      description: "Delete an existing annotation",
+      security: [{ bearerAuth: [] }],
+      request: {
+        params: z.object({ annotationId: IdSchema })
+      },
+      responses: {
+        204: {
+          description: "Annotation deleted successfully"
+        },
+        404: {
+          description: "Annotation not found",
+          content: {
+            "application/json": {
+              schema: ErrorResponseSchema
+            }
+          }
+        },
+        500: {
+          description: "Server error",
+          content: {
+            "application/json": {
+              schema: ErrorResponseSchema
+            }
+          }
+        }
+      }
+    });
+    this.app.openapi(deleteAnnotationRoute, async (c) => {
       try {
-        const annotationId = c.req.param("annotationId"), annotation = this.annotations.get(annotationId);
+        const { annotationId } = c.req.valid("param"), annotation = this.annotations.get(annotationId);
         if (!annotation)
           return c.json({ error: "Annotation not found" }, 404);
-        this.annotations.delete(annotationId);
+        this.annotations.delete(annotationId), this.replies.delete(annotationId);
         const elementAnnotations = this.annotationsByElement.get(annotation.elementId);
         return elementAnnotations && elementAnnotations.delete(annotationId), await this.broadcastMessage({
           type: "annotation.deleted",
@@ -165,142 +653,478 @@ class VisualizationServer {
           timestamp: (/* @__PURE__ */ new Date()).toISOString()
         }), c.body(null, 204);
       } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
+        const message = getErrorMessage(error);
+        return c.json({ error: message }, 500);
+      }
+    });
+    const getAnnotationRepliesRoute = createRoute({
+      method: "get",
+      path: "/api/annotations/:annotationId/replies",
+      tags: ["Annotations"],
+      summary: "Get annotation replies",
+      description: "Retrieve all replies to an annotation",
+      security: [{ bearerAuth: [] }],
+      request: {
+        params: z.object({ annotationId: IdSchema })
+      },
+      responses: {
+        200: {
+          description: "Replies retrieved successfully",
+          content: {
+            "application/json": {
+              schema: AnnotationRepliesSchema
+            }
+          }
+        },
+        404: {
+          description: "Annotation not found",
+          content: {
+            "application/json": {
+              schema: ErrorResponseSchema
+            }
+          }
+        }
+      }
+    });
+    this.app.openapi(getAnnotationRepliesRoute, (c) => {
+      const { annotationId } = c.req.valid("param");
+      if (!this.annotations.get(annotationId))
+        return c.json({ error: "Annotation not found" }, 404);
+      const replies = this.replies.get(annotationId) || [];
+      return c.json({ replies });
+    });
+    const createAnnotationReplyRoute = createRoute({
+      method: "post",
+      path: "/api/annotations/:annotationId/replies",
+      tags: ["Annotations"],
+      summary: "Create annotation reply",
+      description: "Add a reply to an annotation",
+      security: [{ bearerAuth: [] }],
+      request: {
+        params: z.object({ annotationId: IdSchema }),
+        body: {
+          content: {
+            "application/json": {
+              schema: AnnotationReplyCreateSchema
+            }
+          }
+        }
+      },
+      responses: {
+        201: {
+          description: "Reply created successfully",
+          content: {
+            "application/json": {
+              schema: AnnotationReplySchema
+            }
+          }
+        },
+        404: {
+          description: "Annotation not found",
+          content: {
+            "application/json": {
+              schema: ErrorResponseSchema
+            }
+          }
+        },
+        500: {
+          description: "Server error",
+          content: {
+            "application/json": {
+              schema: ErrorResponseSchema
+            }
+          }
+        }
+      }
+    });
+    this.app.openapi(createAnnotationReplyRoute, async (c) => {
+      try {
+        const { annotationId } = c.req.valid("param");
+        if (!this.annotations.get(annotationId))
+          return c.json({ error: "Annotation not found" }, 404);
+        const body = c.req.valid("json"), reply = {
+          id: this.generateReplyId(),
+          author: body.author,
+          content: body.content,
+          createdAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        return this.replies.has(annotationId) || this.replies.set(annotationId, []), this.replies.get(annotationId).push(reply), await this.broadcastMessage({
+          type: "annotation.reply.added",
+          annotationId,
+          replyId: reply.id,
+          timestamp: reply.createdAt
+        }), c.json(reply, 201);
+      } catch (error) {
+        const message = getErrorMessage(error);
         return c.json({ error: message }, 500);
       }
-    }), this.app.get("/api/changesets", (c) => {
+    });
+    const getChangesetsRoute = createRoute({
+      method: "get",
+      path: "/api/changesets",
+      tags: ["Changesets"],
+      summary: "Get changesets",
+      description: "Retrieve a list of all changesets",
+      security: [{ bearerAuth: [] }],
+      responses: {
+        200: {
+          description: "Changesets retrieved successfully",
+          content: {
+            "application/json": {
+              schema: ChangesetsListSchema
+            }
+          }
+        }
+      }
+    });
+    this.app.openapi(getChangesetsRoute, (c) => {
       const changesets = {};
       for (const [id, changeset] of this.changesets)
         changesets[id] = {
-          name: changeset.metadata.name,
-          status: changeset.metadata.status,
-          type: changeset.metadata.type,
-          created_at: changeset.metadata.created_at,
-          elements_count: changeset.changes.changes.length
+          name: changeset.name,
+          status: changeset.status,
+          created: changeset.created,
+          changes_count: changeset.changes.length
         };
       return c.json({
         version: "1.0.0",
         changesets
       });
-    }), this.app.get("/api/changesets/:changesetId", (c) => {
-      const changesetId = c.req.param("changesetId"), changeset = this.changesets.get(changesetId);
-      return changeset ? c.json(changeset) : c.json({ error: "Changeset not found" }, 404);
-    }), this.app.get("/api/elements/:id/annotations", (c) => {
-      const elementId = c.req.param("id"), annotationIds = this.annotationsByElement.get(elementId) || /* @__PURE__ */ new Set(), annotations = Array.from(annotationIds).map((id) => this.annotations.get(id)).filter((a) => a !== void 0);
-      return c.json({ elementId, annotations });
-    }), this.app.post("/api/elements/:id/annotations", async (c) => {
-      try {
-        const elementId = c.req.param("id");
-        if (!await this.findElement(elementId))
-          return c.json({ error: "Element not found" }, 404);
-        const body = await c.req.json(), content = (body.content || body.text) && String(body.content || body.text).trim();
-        if (!content)
-          return c.json({ error: "Annotation content cannot be empty" }, 400);
-        const author = body.author ? String(body.author).trim() : "Anonymous", annotation = {
-          id: this.generateAnnotationId(),
-          elementId,
-          author,
-          content,
-          createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-          tags: body.tags || []
-        };
-        return this.annotations.set(annotation.id, annotation), this.annotationsByElement.has(elementId) || this.annotationsByElement.set(elementId, /* @__PURE__ */ new Set()), this.annotationsByElement.get(elementId).add(annotation.id), await this.broadcastMessage({
-          type: "annotation.added",
-          annotationId: annotation.id,
-          elementId: annotation.elementId,
-          timestamp: annotation.createdAt
-        }), c.json({ success: !0, annotation });
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return c.json({ error: message }, 500);
+    });
+    const getChangesetRoute = createRoute({
+      method: "get",
+      path: "/api/changesets/:changesetId",
+      tags: ["Changesets"],
+      summary: "Get changeset",
+      description: "Retrieve a specific changeset with all its changes",
+      security: [{ bearerAuth: [] }],
+      request: {
+        params: z.object({ changesetId: IdSchema })
+      },
+      responses: {
+        200: {
+          description: "Changeset retrieved successfully",
+          content: {
+            "application/json": {
+              schema: ChangesetDetailSchema
+            }
+          }
+        },
+        404: {
+          description: "Changeset not found",
+          content: {
+            "application/json": {
+              schema: ErrorResponseSchema
+            }
+          }
+        }
       }
-    }), this.app.get("/ws", async (c, next) => {
+    });
+    this.app.openapi(getChangesetRoute, (c) => {
+      const { changesetId } = c.req.valid("param"), changeset = this.changesets.get(changesetId);
+      return changeset ? c.json({
+        id: changeset.id,
+        name: changeset.name,
+        description: changeset.description,
+        status: changeset.status,
+        created: changeset.created,
+        modified: changeset.modified,
+        baseSnapshot: changeset.baseSnapshot,
+        stats: changeset.stats,
+        changes: changeset.changes
+      }) : c.json({ error: "Changeset not found" }, 404);
+    }), this.app.doc("/api-spec.yaml", {
+      openapi: "3.1.0",
+      info: {
+        title: "Documentation Robotics Visualization Server API",
+        version: "0.1.0",
+        description: "API specification for the DR CLI visualization server",
+        contact: {
+          name: "Documentation Robotics",
+          url: "https://github.com/tinkermonkey/documentation_robotics"
+        },
+        license: {
+          name: "ISC"
+        }
+      },
+      servers: [
+        { url: "http://localhost:8080", description: "Local development server" }
+      ],
+      tags: [
+        { name: "Health", description: "Server health and status" },
+        { name: "Schema", description: "JSON Schema specifications" },
+        { name: "Model", description: "Architecture model data" },
+        { name: "Changesets", description: "Model changesets and history" },
+        { name: "Annotations", description: "User annotations on model elements" },
+        { name: "WebSocket", description: "Real-time updates via WebSocket" }
+      ]
+    }), this.app.get("/api-docs", swaggerUI({ url: "/api-spec.yaml" })), upgradeWebSocket && this.app.get("/ws", async (c, next) => {
       if (this.authEnabled) {
-        const queryToken = c.req.query("token");
-        if (!queryToken)
-          return c.json({ error: "Authentication required. Provide token as query parameter: ?token=YOUR_TOKEN" }, 401);
-        if (queryToken !== this.authToken)
+        const queryToken = c.req.query("token"), wsProtocol = c.req.header("Sec-WebSocket-Protocol");
+        let protocolToken = null;
+        if (wsProtocol) {
+          const protocols = wsProtocol.split(",").map((p) => p.trim()), tokenIndex = protocols.indexOf("token");
+          tokenIndex !== -1 && protocols.length > tokenIndex + 1 && (protocolToken = protocols[tokenIndex + 1]);
+        }
+        const authHeader = c.req.header("Authorization"), bearerToken = authHeader?.startsWith("Bearer ") ? authHeader.substring(7) : null, token = queryToken || protocolToken || bearerToken;
+        if (!token)
+          return c.json({
+            error: 'Authentication required. Provide token via: 1) Query param (?token=YOUR_TOKEN), 2) Sec-WebSocket-Protocol header (browser: new WebSocket(url, ["token", "YOUR_TOKEN"])), or 3) Authorization header (Bearer YOUR_TOKEN)'
+          }, 401);
+        if (token !== this.authToken)
           return c.json({ error: "Invalid authentication token" }, 403);
+        protocolToken && c.header("Sec-WebSocket-Protocol", "token");
       }
       return next();
     }, upgradeWebSocket(() => ({
-      onOpen: (_evt, ws) => {
-        this.clients.add(ws), ws.send(JSON.stringify({
+      onOpen: async (_evt, ws) => {
+        await this.recordWebSocketEvent("ws.connection.open", {
+          "ws.client_count": this.clients.size + 1
+        }), this.clients.add(ws), ws.send(JSON.stringify({
           type: "connected",
           version: "0.1.0",
           timestamp: (/* @__PURE__ */ new Date()).toISOString()
         })), process.env.VERBOSE && console.log(`[WebSocket] Client connected (total: ${this.clients.size})`);
       },
-      onClose: (_evt, ws) => {
-        this.clients.delete(ws), process.env.VERBOSE && console.log(`[WebSocket] Client disconnected (total: ${this.clients.size})`);
+      onClose: async (_evt, ws) => {
+        await this.recordWebSocketEvent("ws.connection.close", {
+          "ws.client_count": this.clients.size - 1
+        }), this.clients.delete(ws), process.env.VERBOSE && console.log(`[WebSocket] Client disconnected (total: ${this.clients.size})`);
       },
       onMessage: async (message, ws) => {
+        const messageStartTime = Date.now();
+        let messageType = "unknown";
         try {
           const rawData = message.data ?? message;
           let msgStr;
           typeof rawData == "string" ? msgStr = rawData : rawData instanceof Buffer || rawData instanceof Uint8Array ? msgStr = new TextDecoder().decode(rawData) : msgStr = String(rawData);
-          const data = JSON.parse(msgStr);
-          data.jsonrpc === "2.0" ? await this.handleJSONRPCMessage(ws, data) : await this.handleWSMessage(ws, data);
+          const rawMessage = JSON.parse(msgStr), validationResult = WSMessageSchema.safeParse(rawMessage);
+          if (!validationResult.success) {
+            const errorMsg = validationResult.error.issues.map((e) => `${e.path.join(".")}: ${e.message}`).join("; ");
+            console.error("Invalid WebSocket message format:", errorMsg), ws.send(JSON.stringify({ error: "Invalid message format", details: errorMsg }));
+            return;
+          }
+          const data = validationResult.data;
+          "jsonrpc" in data && data.jsonrpc === "2.0" ? "method" in data && typeof data.method == "string" ? messageType = data.method : messageType = data.id?.toString() || "jsonrpc-response" : "type" in data ? messageType = data.type : messageType = "unknown", await this.recordWebSocketEvent("ws.message.received", {
+            "ws.message.type": messageType,
+            "ws.message.size_bytes": msgStr.length
+          }), "jsonrpc" in data && data.jsonrpc === "2.0" ? await this.handleJSONRPCMessage(ws, data) : await this.handleWSMessage(ws, data);
+          const durationMs = Date.now() - messageStartTime;
+          await this.recordWebSocketEvent("ws.message.processed", {
+            "ws.message.type": messageType,
+            "ws.message.duration_ms": durationMs,
+            "ws.message.status": "success"
+          });
         } catch (error) {
-          const errorMsg = error instanceof Error ? error.message : String(error);
-          process.env.DEBUG && console.error(`[WebSocket] Error handling message: ${errorMsg}`), ws.send(JSON.stringify({
+          const errorMsg = getErrorMessage(error), durationMs = Date.now() - messageStartTime;
+          await this.recordWebSocketEvent("ws.message.error", {
+            "ws.message.type": messageType,
+            "ws.message.duration_ms": durationMs,
+            "ws.message.status": "error",
+            "error.message": errorMsg
+          }), console.warn(`[WebSocket] Error handling ${messageType} message (${durationMs}ms): ${errorMsg}`), ws.send(JSON.stringify({
             type: "error",
             message: errorMsg
           }));
         }
       },
-      onError: (error) => {
-        const message = error instanceof Error ? error.message : String(error);
-        console.error(`[WebSocket] Error: ${message}`);
+      onError: async (error) => {
+        const message = getErrorMessage(error);
+        await this.recordWebSocketEvent("ws.error", {
+          "error.type": error instanceof Error ? error.constructor.name : "unknown",
+          "error.message": message
+        }), console.error("[WebSocket] Error:", error);
       }
     })));
   }
   /**
-   * Serialize model to JSON for client consumption
+   * Get OpenAPI specification document
+   * Provides a stable public API for OpenAPI spec generation.
+   *
+   * BEHAVIOR: Returns an OpenAPI spec with the version specified in `config.openapi`.
+   * The returned document will have whatever OpenAPI version was passed in the config.
+   *
+   * NOTE: Hono's getOpenAPI31Document() passes the config directly through and
+   * uses the specified version in the output. There is no forced version conversion.
+   */
+  getOpenAPIDocument(config) {
+    return this.app.getOpenAPI31Document(config);
+  }
+  /**
+   * Serialize model to graph format for client consumption.
+   *
+   * Returns { nodes, links } where:
+   * - nodes: flat array of all elements across all layers
+   * - links: intra-layer relationships (carry layer_id) and cross-layer
+   *   references (carry source_layer_id + target_layer_id)
+   *
+   * Links are deduplicated: if the same relationship appears on multiple
+   * elements (e.g. stored on both source and target), only one entry is kept.
    */
   async serializeModel() {
-    const layers = {};
-    for (const [name, layer] of this.model.layers) {
-      const elements = layer.listElements().map((e) => {
-        const annotationIds = this.annotationsByElement.get(e.id) || /* @__PURE__ */ new Set(), annotations = Array.from(annotationIds).map((id) => this.annotations.get(id)).filter((a) => a !== void 0);
-        return {
-          ...e.toJSON(),
-          annotations
+    const nodes = [], linksMap = /* @__PURE__ */ new Map(), elementLayerMap = /* @__PURE__ */ new Map();
+    for (const [layerName, layer] of this.model.layers)
+      for (const e of layer.listElements()) {
+        const layerId = e.layer_id || layerName;
+        e.id && elementLayerMap.set(e.id, layerId), e.path && e.path !== e.id && elementLayerMap.set(e.path, layerId);
+      }
+    for (const [layerName, layer] of this.model.layers)
+      for (const e of layer.listElements()) {
+        const layerId = e.layer_id || layerName, viewerSpecNodeId = this.resolveViewerSpecNodeId(e.id, layerId, e.type, e.spec_node_id), node = {
+          id: e.id,
+          spec_node_id: viewerSpecNodeId,
+          type: e.type,
+          layer_id: layerId,
+          name: e.name
         };
-      });
-      layers[name] = {
-        name,
-        elements,
-        elementCount: elements.length
-      };
+        e.description && (node.description = e.description), e.attributes && Object.keys(e.attributes).length > 0 && (node.attributes = e.attributes), e.source_reference && (node.source_reference = e.source_reference), e.metadata && (node.metadata = e.metadata), nodes.push(node);
+        for (const rel of e.relationships) {
+          const linkId = `rel:${rel.source}:${rel.target}:${rel.predicate}`;
+          linksMap.has(linkId) || linksMap.set(linkId, {
+            id: linkId,
+            source: rel.source,
+            target: rel.target,
+            type: rel.predicate,
+            layer_id: layerId
+          });
+        }
+        for (const ref of e.references) {
+          const linkId = `ref:${ref.source}:${ref.target}:${ref.type}`;
+          linksMap.has(linkId) || linksMap.set(linkId, {
+            id: linkId,
+            source: ref.source,
+            target: ref.target,
+            type: ref.type,
+            source_layer_id: elementLayerMap.get(ref.source) || layerId,
+            target_layer_id: elementLayerMap.get(ref.target) || "unknown"
+          });
+        }
+      }
+    for (const rel of this.model.relationships.getAll()) {
+      const linkId = `rel:${rel.source}:${rel.target}:${rel.predicate}`;
+      if (!linksMap.has(linkId)) {
+        const layerId = rel.layer || elementLayerMap.get(rel.source);
+        if (!layerId)
+          continue;
+        const link = {
+          id: linkId,
+          source: rel.source,
+          target: rel.target,
+          type: rel.predicate
+        };
+        rel.targetLayer ? (link.source_layer_id = layerId, link.target_layer_id = rel.targetLayer) : link.layer_id = layerId, linksMap.set(linkId, link);
+      }
     }
     return {
-      manifest: this.model.manifest.toJSON(),
-      layers,
-      totalElements: Array.from(this.model.layers.values()).reduce((sum, layer) => sum + layer.listElements().length, 0)
+      nodes,
+      links: Array.from(linksMap.values())
     };
   }
+  /**
+   * Resolve viewer spec node ID with fallback logic
+   * Handles multiple resolution strategies:
+   * 1. Valid pass-through: Return specNodeId if it's already a valid spec node ID
+   * 2. Dot-format extraction: Extract type from elementId in "layer.type.name" format and construct candidate
+   * 3. Hyphen-format extraction: Extract type from elementId in "layer-type-name" format and construct candidate
+   * 4. Type-parameter fallback: If extracted type differs from type parameter, retry with type parameter
+   * 5. Layer-specific fallback: Use LAYER_FALLBACK map for layers with limited viewer support
+   *
+   * @param elementId - The element ID (can be in dot-format or hyphen-format)
+   * @param layer - The layer name (canonical form)
+   * @param type - The element type field
+   * @param specNodeId - The spec node ID if already known
+   * @returns The resolved spec node ID string
+   */
+  resolveViewerSpecNodeId(elementId, layer, type, specNodeId) {
+    if (specNodeId && VisualizationServer.ALL_VALID_IDS.has(specNodeId))
+      return specNodeId;
+    let extractedType = null;
+    if (elementId) {
+      if (elementId.includes(".")) {
+        const parts = elementId.split(".");
+        parts.length >= 2 && (extractedType = parts[1]);
+      }
+      if (!extractedType && elementId.includes("-"))
+        if (layer === "data-model" || layer === "data-store") {
+          const expectedPrefix = layer + "-";
+          if (elementId.startsWith(expectedPrefix)) {
+            const parts = elementId.substring(expectedPrefix.length).split("-");
+            parts.length >= 1 && (extractedType = parts[0]);
+          }
+        } else {
+          const parts = elementId.split("-");
+          parts.length >= 2 && (extractedType = parts[1]);
+        }
+    }
+    if (extractedType) {
+      const candidate = `${layer}.${extractedType}`;
+      if ((VisualizationServer.VALID_SPEC_NODE_IDS[layer] || []).includes(candidate))
+        return candidate;
+    }
+    if (type && (!extractedType || extractedType !== type)) {
+      const candidate = `${layer}.${type}`;
+      if ((VisualizationServer.VALID_SPEC_NODE_IDS[layer] || []).includes(candidate))
+        return candidate;
+    }
+    return layer in VisualizationServer.LAYER_FALLBACK ? VisualizationServer.LAYER_FALLBACK[layer] : "data-store.database";
+  }
   /**
    * Generate unique annotation ID
+   * Uses cryptographically secure random bytes for collision-resistant IDs
    */
   generateAnnotationId() {
-    return `ann-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    return `ann-${Date.now()}-${randomBytes(4).toString("hex")}`;
+  }
+  /**
+   * Generate unique reply ID
+   * Uses cryptographically secure random bytes for collision-resistant IDs
+   */
+  generateReplyId() {
+    return `reply-${Date.now()}-${randomBytes(4).toString("hex")}`;
   }
   /**
    * Broadcast message to all connected WebSocket clients
    */
   async broadcastMessage(message) {
-    const messageStr = JSON.stringify(message);
+    const messageStr = JSON.stringify(message), messageType = message.type || "unknown";
+    await this.recordWebSocketEvent("ws.broadcast.start", {
+      "ws.broadcast.type": messageType,
+      "ws.broadcast.client_count": this.clients.size,
+      "ws.broadcast.message_size_bytes": messageStr.length
+    });
     let failureCount = 0;
+    const failedClients = [];
     for (const client of this.clients)
       try {
         client.send(messageStr);
       } catch (error) {
-        failureCount++;
-        const msg = error instanceof Error ? error.message : String(error);
-        process.env.VERBOSE && console.warn(`[WebSocket] Failed to send message to client: ${msg}`);
+        failureCount++, failedClients.push(client);
+        const msg = getErrorMessage(error);
+        console.warn(`[WebSocket] Failed to send message to client: ${msg}`);
       }
-    failureCount > 0 && process.env.VERBOSE && console.warn(`[WebSocket] Failed to send message to ${failureCount}/${this.clients.size} clients`);
+    for (const client of failedClients)
+      this.clients.delete(client);
+    if (await this.recordWebSocketEvent("ws.broadcast.complete", {
+      "ws.broadcast.type": messageType,
+      "ws.broadcast.success_count": this.clients.size - failureCount,
+      "ws.broadcast.failure_count": failureCount
+    }), failureCount > 0) {
+      const failureRate = this.clients.size > 0 ? failureCount / this.clients.size * 100 : 0;
+      (failureRate >= 10 || failureCount > 5) && console.warn(`[WebSocket] Broadcast completed with ${failureCount}/${this.clients.size} client failures (${failureRate.toFixed(1)}% failure rate)`);
+    }
+  }
+  /**
+   * Record WebSocket telemetry event
+   * Creates spans for WebSocket operations when telemetry is enabled
+   */
+  async recordWebSocketEvent(eventName, attributes) {
+    return;
+    try {
+      const { startSpan, endSpan } = await import("../telemetry/index.js"), span = startSpan(eventName, attributes);
+      endSpan(span);
+    } catch (error) {
+      console.warn(`[Telemetry] Failed to record WebSocket event: ${getErrorMessage(error)}`);
+    }
   }
   /**
    * Find an element across all layers
@@ -317,9 +1141,10 @@ class VisualizationServer {
    * Handle WebSocket messages
    */
   async handleWSMessage(ws, data) {
-    switch (data.type) {
+    const simpleMsg = data;
+    switch (simpleMsg.type) {
       case "subscribe":
-        const topics = data.topics || ["model", "annotations"];
+        const topics = simpleMsg.topics || ["model", "annotations"];
         ws.send(JSON.stringify({
           type: "subscribed",
           topics,
@@ -339,15 +1164,15 @@ class VisualizationServer {
         }));
         break;
       case "annotate":
-        data.annotation && await this.broadcastMessage({
+        simpleMsg.annotation && await this.broadcastMessage({
           type: "annotation",
-          data: data.annotation
+          data: simpleMsg.annotation
         });
         break;
       default:
         ws.send(JSON.stringify({
           type: "error",
-          message: `Unknown message type: ${data.type}`
+          message: `Unknown message type: ${simpleMsg.type}`
         }));
     }
   }
@@ -355,7 +1180,12 @@ class VisualizationServer {
    * Handle JSON-RPC 2.0 messages for chat functionality
    */
   async handleJSONRPCMessage(ws, data) {
-    const { method, params, id } = data, sendResponse = (result) => {
+    if (!("method" in data)) {
+      const responseType = "result" in data ? "success" : "error" in data ? "error" : "unknown", msgId = "id" in data ? data.id : "unknown";
+      console.warn(`[WebSocket] Received JSON-RPC ${responseType} response from client (ID: ${msgId}), ignoring`);
+      return;
+    }
+    const rpcMsg = data, { method, params, id } = rpcMsg, sendResponse = (result) => {
       ws.send(JSON.stringify({
         jsonrpc: "2.0",
         result,
@@ -371,24 +1201,25 @@ class VisualizationServer {
     try {
       switch (method) {
         case "chat.status":
-          const claudeAvailable = await this.checkClaudeCodeCLI();
-          sendResponse({
-            sdk_available: claudeAvailable,
-            sdk_version: claudeAvailable ? "claude-code-cli" : null,
-            error_message: claudeAvailable ? null : "Claude Code CLI not found in PATH"
+          const hasClient = this.selectedChatClient !== void 0;
+          let statusError = null;
+          this.chatInitializationError ? statusError = `Chat initialization failed: ${this.chatInitializationError.message}` : hasClient || (statusError = "No chat client available. Install Claude Code or GitHub Copilot."), sendResponse({
+            sdk_available: hasClient,
+            sdk_version: hasClient ? this.selectedChatClient.getClientName() : null,
+            error_message: statusError
           });
           break;
         case "chat.send":
-          if (!params || !params.message) {
-            sendError(-32602, "Message cannot be empty");
+          if (!params || typeof params != "object" || !("message" in params) || typeof params.message != "string" || params.message.trim() === "") {
+            sendError(JSONRPC_ERRORS.INVALID_PARAMS, "Message cannot be empty");
             return;
           }
-          if (!await this.checkClaudeCodeCLI()) {
-            sendError(-32001, "Claude Code CLI not available. Install Claude Code to enable chat.");
+          if (!this.selectedChatClient) {
+            sendError(JSONRPC_ERRORS.NO_CLIENT_AVAILABLE, "No chat client available. Install Claude Code or GitHub Copilot to enable chat.");
             return;
           }
           const conversationId = `conv-${++this.chatConversationCounter}-${Date.now()}`;
-          await this.launchClaudeCodeChat(ws, conversationId, params.message, id);
+          await this.launchChat(ws, conversationId, params.message, id);
           break;
         case "chat.cancel":
           let cancelled = !1, cancelledConvId = null;
@@ -396,7 +1227,8 @@ class VisualizationServer {
             try {
               process2.kill(), this.activeChatProcesses.delete(convId), cancelled = !0, cancelledConvId = convId;
               break;
-            } catch {
+            } catch (error) {
+              console.warn(`[Chat] Failed to cancel process for conversation ${convId}: ${getErrorMessage(error)}`);
             }
           sendResponse({
             cancelled,
@@ -404,43 +1236,46 @@ class VisualizationServer {
           });
           break;
         default:
-          sendError(-32601, `Method not found: ${method}`);
+          sendError(JSONRPC_ERRORS.METHOD_NOT_FOUND, `Method not found: ${method}`);
       }
     } catch (error) {
-      const errorMsg = error instanceof Error ? error.message : String(error);
-      sendError(-32603, "Internal error", errorMsg);
+      const errorMsg = getErrorMessage(error);
+      sendError(JSONRPC_ERRORS.INTERNAL_ERROR, "Internal error", errorMsg);
     }
   }
   /**
-   * Check if Claude Code CLI is available
+   * Launch chat with selected client and stream responses via WebSocket
    */
-  async checkClaudeCodeCLI() {
-    try {
-      return Bun.spawnSync({
-        cmd: ["which", "claude"],
-        stdout: "pipe",
-        stderr: "pipe"
-      }).exitCode === 0;
-    } catch {
-      return !1;
+  async launchChat(ws, conversationId, message, requestId) {
+    if (!this.selectedChatClient) {
+      ws.send(JSON.stringify({
+        jsonrpc: "2.0",
+        error: {
+          code: JSONRPC_ERRORS.NO_CLIENT_AVAILABLE,
+          message: "No chat client available"
+        },
+        id: requestId
+      }));
+      return;
     }
+    this.selectedChatClient instanceof ClaudeCodeClient ? await this.launchClaudeCodeChat(ws, conversationId, message, requestId) : this.selectedChatClient instanceof CopilotClient ? await this.launchCopilotChat(ws, conversationId, message, requestId) : ws.send(JSON.stringify({
+      jsonrpc: "2.0",
+      error: {
+        code: JSONRPC_ERRORS.NO_CLIENT_AVAILABLE,
+        message: "Unknown chat client type"
+      },
+      id: requestId
+    }));
   }
   /**
    * Launch Claude Code CLI with dr-architect agent and stream responses
    */
   async launchClaudeCodeChat(ws, conversationId, message, requestId) {
     try {
+      const cmd = ["claude", "--agent", "dr-architect", "--print"];
+      this.withDanger && cmd.push("--dangerously-skip-permissions"), cmd.push("--verbose", "--output-format", "stream-json");
       const proc = Bun.spawn({
-        cmd: [
-          "claude",
-          "--agent",
-          "dr-architect",
-          "--print",
-          "--dangerously-skip-permissions",
-          "--verbose",
-          "--output-format",
-          "stream-json"
-        ],
+        cmd,
         cwd: this.model.rootPath,
         stdin: "pipe",
         stdout: "pipe",
@@ -495,8 +1330,8 @@ class VisualizationServer {
                       timestamp: (/* @__PURE__ */ new Date()).toISOString()
                     }
                   }));
-                } catch {
-                  ws.send(JSON.stringify({
+                } catch (parseError) {
+                  process.env.DEBUG && console.debug(`[Chat] Failed to parse JSON chunk: ${getErrorMessage(parseError)}`), ws.send(JSON.stringify({
                     jsonrpc: "2.0",
                     method: "chat.response.chunk",
                     params: {
@@ -532,96 +1367,197 @@ class VisualizationServer {
             id: requestId
           }));
         } catch (error) {
-          const errorMsg = error instanceof Error ? error.message : String(error);
+          const errorMsg = getErrorMessage(error);
           ws.send(JSON.stringify({
             jsonrpc: "2.0",
             error: {
-              code: -32603,
+              code: JSONRPC_ERRORS.INTERNAL_ERROR,
               message: `Chat failed: ${errorMsg}`
             },
             id: requestId
           })), this.activeChatProcesses.delete(conversationId);
           try {
-            proc.kill();
-          } catch {
+            await this.killProcessWithRetry(proc, conversationId, "Claude Code");
+          } catch (error2) {
+            console.error(`[Claude Code] Failed to kill process for conversation ${conversationId}: ${getErrorMessage(error2)}`);
           }
         }
-      })();
+      })().catch((err) => {
+        const errorMsg = getErrorMessage(err);
+        console.error(`[Claude Code] Stream error: ${errorMsg}`);
+        try {
+          ws.send(JSON.stringify({
+            jsonrpc: "2.0",
+            error: {
+              code: JSONRPC_ERRORS.INTERNAL_ERROR,
+              message: `Stream error: ${errorMsg}`
+            },
+            id: requestId
+          }));
+        } catch (sendError) {
+          console.error(`[Claude Code] Failed to send stream error notification: ${getErrorMessage(sendError)}`);
+        }
+      });
     } catch (error) {
-      const errorMsg = error instanceof Error ? error.message : String(error);
+      const errorMsg = getErrorMessage(error);
       ws.send(JSON.stringify({
         jsonrpc: "2.0",
         error: {
-          code: -32603,
+          code: JSONRPC_ERRORS.INTERNAL_ERROR,
           message: `Failed to launch Claude Code: ${errorMsg}`
         },
         id: requestId
       }));
     }
   }
+  /**
+   * Launch GitHub Copilot CLI and stream responses via WebSocket
+   */
+  async launchCopilotChat(ws, conversationId, message, requestId) {
+    try {
+      let cmd;
+      Bun.spawnSync({
+        cmd: ["gh", "copilot", "--version"],
+        stdout: "pipe",
+        stderr: "pipe"
+      }).exitCode === 0 ? (cmd = ["gh", "copilot", "explain"], this.withDanger && cmd.push("--allow-all-tools"), cmd.push(message)) : (cmd = ["copilot", "explain"], this.withDanger && cmd.push("--allow-all-tools"), cmd.push(message));
+      const proc = Bun.spawn({
+        cmd,
+        cwd: this.model.rootPath,
+        stdin: "pipe",
+        stdout: "pipe",
+        stderr: "pipe"
+      });
+      this.activeChatProcesses.set(conversationId, proc);
+      const stdoutReader = proc.stdout.getReader(), decoder = new TextDecoder();
+      (async () => {
+        let accumulatedText = "";
+        try {
+          for (; ; ) {
+            const { done, value } = await stdoutReader.read();
+            if (done)
+              break;
+            const chunk = decoder.decode(value, { stream: !0 });
+            accumulatedText += chunk, ws.send(JSON.stringify({
+              jsonrpc: "2.0",
+              method: "chat.response.chunk",
+              params: {
+                conversation_id: conversationId,
+                content: chunk,
+                is_final: !1,
+                timestamp: (/* @__PURE__ */ new Date()).toISOString()
+              }
+            }));
+          }
+          const exitCode = await proc.exited;
+          this.activeChatProcesses.delete(conversationId), ws.send(JSON.stringify({
+            jsonrpc: "2.0",
+            result: {
+              conversation_id: conversationId,
+              status: exitCode === 0 ? "complete" : "error",
+              exit_code: exitCode,
+              full_response: accumulatedText,
+              timestamp: (/* @__PURE__ */ new Date()).toISOString()
+            },
+            id: requestId
+          }));
+        } catch (error) {
+          const errorMsg = getErrorMessage(error);
+          ws.send(JSON.stringify({
+            jsonrpc: "2.0",
+            error: {
+              code: JSONRPC_ERRORS.INTERNAL_ERROR,
+              message: `Chat failed: ${errorMsg}`
+            },
+            id: requestId
+          })), this.activeChatProcesses.delete(conversationId);
+          try {
+            await this.killProcessWithRetry(proc, conversationId, "Copilot");
+          } catch (error2) {
+            console.error(`[Copilot] Failed to kill process for conversation ${conversationId}: ${getErrorMessage(error2)}`);
+          }
+        }
+      })().catch((err) => {
+        console.error(`[Copilot] Stream error: ${getErrorMessage(err)}`);
+      });
+    } catch (error) {
+      const errorMsg = getErrorMessage(error);
+      ws.send(JSON.stringify({
+        jsonrpc: "2.0",
+        error: {
+          code: JSONRPC_ERRORS.INTERNAL_ERROR,
+          message: `Failed to launch GitHub Copilot: ${errorMsg}`
+        },
+        id: requestId
+      }));
+    }
+  }
   /**
    * Setup file watcher for model changes
    */
   setupFileWatcher() {
-    const drPath = `${this.model.rootPath}/.dr`, bunWatch = globalThis.Bun?.watch;
+    const modelPath = `${this.model.rootPath}/documentation-robotics/model`, bunWatch = globalThis.Bun?.watch;
     if (!bunWatch) {
       console.warn("[Watcher] Bun.watch not available, file watching disabled");
       return;
     }
-    this.watcher = bunWatch(drPath, {
-      recursive: !0,
-      onChange: async (_event, path) => {
-        process.env.VERBOSE && console.log(`[Watcher] File changed: ${path}`);
-        try {
-          this.model = await Model.load(this.model.rootPath, { lazyLoad: !1 });
-          const modelData = await this.serializeModel(), message = JSON.stringify({
-            type: "model.updated",
-            data: modelData,
-            timestamp: (/* @__PURE__ */ new Date()).toISOString()
-          });
-          for (const client of this.clients)
-            try {
-              client.send(message);
-            } catch (error) {
-              if (process.env.DEBUG) {
-                const msg = error instanceof Error ? error.message : String(error);
-                console.debug(`[Watcher] Failed to send update: ${msg}`);
+    try {
+      this.watcher = bunWatch(modelPath, {
+        recursive: !0,
+        onChange: async (_event, path2) => {
+          process.env.VERBOSE && console.log(`[Watcher] File changed: ${path2}`);
+          try {
+            this.model = await Model.load(this.model.rootPath, { lazyLoad: !1 }), await this.loadChangesetsFromDisk();
+            const modelData = await this.serializeModel(), message = JSON.stringify({
+              type: "model.updated",
+              data: modelData,
+              timestamp: (/* @__PURE__ */ new Date()).toISOString()
+            });
+            for (const client of this.clients)
+              try {
+                client.send(message);
+              } catch (error) {
+                const msg = getErrorMessage(error);
+                console.warn(`[Watcher] Failed to send update: ${msg}`);
               }
-            }
-        } catch (error) {
-          const message = error instanceof Error ? error.message : String(error);
-          console.error(`[Watcher] Failed to reload model: ${message}`);
+          } catch (error) {
+            const message = getErrorMessage(error);
+            console.error(`[Watcher] Failed to reload model: ${message}`);
+          }
         }
-      }
-    });
+      });
+    } catch (err) {
+      console.warn(`[Watcher] Could not watch ${modelPath}: ${err}`);
+    }
   }
   /**
-   * Load all JSON schemas from bundled directory
+   * Load all JSON schemas from bundled directory (recursive)
+   * Loads schemas from all subdirectories: base/, nodes/, relationships/, etc.
    */
   async loadSchemas() {
     const schemasPath = new URL("../schemas/bundled/", import.meta.url).pathname, schemas = {};
     try {
-      const fs = await import("fs/promises"), path = await import("path"), fileList = await fs.readdir(schemasPath);
-      for (const file of fileList)
-        if (file.endsWith(".schema.json") || file.endsWith(".json")) {
-          const filePath = path.join(schemasPath, file), content = await fs.readFile(filePath, "utf-8");
-          schemas[file] = JSON.parse(content);
+      const fs = await import("fs/promises"), path2 = await import("path"), walkDirectory = async (dir, prefix = "") => {
+        const entries = await fs.readdir(dir, { withFileTypes: !0 });
+        for (const entry of entries) {
+          const fullPath = path2.join(dir, entry.name), schemaKey = prefix ? `${prefix}/${entry.name}` : entry.name;
+          if (entry.isDirectory())
+            await walkDirectory(fullPath, schemaKey);
+          else if (entry.isFile() && (entry.name.endsWith(".schema.json") || entry.name.endsWith(".json"))) {
+            const content = await fs.readFile(fullPath, "utf-8");
+            try {
+              schemas[schemaKey] = JSON.parse(content);
+            } catch (parseError) {
+              const parseErrorMsg = parseError instanceof Error ? parseError.message : String(parseError);
+              throw new Error(`Invalid JSON in schema file ${fullPath}: ${parseErrorMsg}`);
+            }
+          }
         }
-      return schemas;
-    } catch (error) {
-      throw console.error("Failed to load schemas:", error), new Error("Failed to load schema files");
-    }
-  }
-  /**
-   * Load link registry from bundled directory
-   */
-  async loadLinkRegistry() {
-    const linkRegistryPath = new URL("../schemas/bundled/link-registry.json", import.meta.url).pathname;
-    try {
-      const content = await (await import("fs/promises")).readFile(linkRegistryPath, "utf-8");
-      return JSON.parse(content);
+      };
+      return await walkDirectory(schemasPath), schemas;
     } catch (error) {
-      throw console.error("Failed to load link registry:", error), new Error("Link registry not found");
+      const errorMsg = getErrorMessage(error);
+      throw console.error("Failed to load schemas:", error), new Error(`Failed to load schema files: ${errorMsg}`);
     }
   }
   /**
@@ -967,7 +1903,27 @@ class VisualizationServer {
       return div.innerHTML;
     }
 
-    const ws = new WebSocket(\`ws://\${window.location.host}/ws\`);
+    // Extract token from URL query parameters if present
+    const urlParams = new URLSearchParams(window.location.search);
+    const token = urlParams.get('token');
+
+    // Log token status for debugging
+    if (!token) {
+      console.warn('[WebSocket] No authentication token found in URL. If authentication is enabled, connection will fail.');
+      console.warn('[WebSocket] Expected URL format: http://localhost:PORT?token=YOUR_TOKEN');
+    } else {
+      console.log('[WebSocket] Found authentication token in URL');
+    }
+
+    // Build WebSocket URL with token if available
+    let wsUrl = \`ws://\${window.location.host}/ws\`;
+    if (token) {
+      wsUrl += \`?token=\${encodeURIComponent(token)}\`;
+    }
+
+    console.log('[WebSocket] Connecting to:', wsUrl.replace(/token=[^&]+/, 'token=***'));
+
+    const ws = new WebSocket(wsUrl);
 
     ws.addEventListener('open', () => {
       console.log('WebSocket connected');
@@ -993,16 +1949,45 @@ class VisualizationServer {
       }
     });
 
-    ws.addEventListener('close', () => {
-      console.log('WebSocket disconnected');
+    ws.addEventListener('close', (event) => {
+      console.log('WebSocket disconnected', event.code, event.reason);
       updateStatus(false);
+
+      // If closed immediately with auth error codes, show helpful message
+      if (!token && (event.code === 1002 || event.code === 1008 || event.code === 1006)) {
+        showAuthError();
+      }
     });
 
     ws.addEventListener('error', (error) => {
       console.error('WebSocket error:', error);
       updateStatus(false);
+
+      // If we don't have a token, likely an auth issue
+      if (!token) {
+        showAuthError();
+      }
     });
 
+    function showAuthError() {
+      const errorDiv = document.createElement('div');
+      errorDiv.style.cssText = 'position: fixed; top: 80px; left: 50%; transform: translateX(-50%); background: #f44336; color: white; padding: 16px 24px; border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.3); z-index: 10000; max-width: 500px; text-align: center;';
+      errorDiv.innerHTML = \`
+        <strong>\u26A0\uFE0F Authentication Required</strong><br>
+        <span style="font-size: 14px; margin-top: 8px; display: inline-block;">
+          Please use the full URL with authentication token from the terminal.
+        </span>
+      \`;
+      document.body.appendChild(errorDiv);
+
+      // Auto-dismiss after 10 seconds
+      setTimeout(() => {
+        errorDiv.style.transition = 'opacity 0.5s';
+        errorDiv.style.opacity = '0';
+        setTimeout(() => errorDiv.remove(), 500);
+      }, 10000);
+    }
+
     function updateStatus(connected) {
       if (connected) {
         statusEl.className = 'status-badge connected';
@@ -1044,12 +2029,13 @@ class VisualizationServer {
         for (const element of layerData.elements) {
           const elemDiv = document.createElement('div');
           elemDiv.className = 'element-item';
-          if (element.id === selectedElementId) {
+          const elementSlug = element.path || element.id;
+          if (elementSlug === selectedElementId) {
             elemDiv.classList.add('selected');
           }
-          elemDiv.innerHTML = \`\${escapeHtml(element.id)}<br><span style="font-size: 11px; color: #999;">\${escapeHtml(element.name)}</span>\`;
+          elemDiv.innerHTML = \`\${escapeHtml(elementSlug)}<br><span style="font-size: 11px; color: #999;">\${escapeHtml(element.name)}</span>\`;
           elemDiv.addEventListener('click', () => {
-            selectedElementId = element.id;
+            selectedElementId = elementSlug;
             document.querySelectorAll('.element-item').forEach(el => el.classList.remove('selected'));
             elemDiv.classList.add('selected');
             renderSelectedElement();
@@ -1073,7 +2059,7 @@ class VisualizationServer {
       // Find element in model
       let element = null;
       for (const layer of Object.values(currentModel.layers)) {
-        element = layer.elements.find(e => e.id === selectedElementId);
+        element = layer.elements.find(e => (e.path || e.id) === selectedElementId);
         if (element) break;
       }
 
@@ -1086,7 +2072,7 @@ class VisualizationServer {
         <div class="detail-header">
           <div class="element-type">\${escapeHtml(element.type)}</div>
           <h2>\${escapeHtml(element.name)}</h2>
-          <div style="font-size: 12px; color: #666; margin-top: 4px;"><code>\${escapeHtml(element.id)}</code></div>
+          <div style="font-size: 12px; color: #666; margin-top: 4px;"><code>\${escapeHtml(element.path || element.id)}</code></div>
         </div>
       \`;
 
@@ -1128,11 +2114,12 @@ class VisualizationServer {
       html += \`
         <div class="detail-section">
           <h3>Add Annotation</h3>
-          <form class="annotation-form" onsubmit="addAnnotation(event, '\${escapeHtml(element.id)}')">
+          <form class="annotation-form" onsubmit="addAnnotation(event, '\${escapeHtml(element.path || element.id)}')">
             <input type="text" placeholder="Author name" id="ann-author" required>
             <textarea placeholder="Annotation text" id="ann-text" required></textarea>
             <button type="submit">Add Annotation</button>
           </form>
+          <div id="ann-error" style="margin-top: 8px; min-height: 1.2em;"></div>
         </div>
       \`;
 
@@ -1147,30 +2134,101 @@ class VisualizationServer {
 
       if (!author || !text) return;
 
-      // Send to server
-      fetch(\`/api/elements/\${elementId}/annotations\`, {
+      // Send to server using new annotation API
+      fetch('/api/annotations', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ author, text })
+        body: JSON.stringify({ elementId, author, content: text })
       })
-        .then(r => r.json())
-        .then(data => {
-          if (data.success) {
+        .then(r => r.json().then(data => ({ ok: r.ok, data })))
+        .then(({ ok, data }) => {
+          if (ok && data && data.id) {
             document.getElementById('ann-author').value = '';
             document.getElementById('ann-text').value = '';
+            const errorDiv = document.getElementById('ann-error');
+            if (errorDiv) errorDiv.textContent = '';
+          } else if (!ok) {
+            const errorMsg = (data && data.error) ? data.error : 'Failed to create annotation';
+            const errorDiv = document.getElementById('ann-error');
+            if (errorDiv) {
+              errorDiv.textContent = 'Error: ' + errorMsg;
+              errorDiv.style.color = '#d32f2f';
+              errorDiv.style.marginTop = '8px';
+            }
           }
         })
-        .catch(err => console.error('Failed to add annotation:', err));
+        .catch(err => {
+          const errorDiv = document.getElementById('ann-error');
+          if (errorDiv) {
+            errorDiv.textContent = 'Error: Failed to add annotation: ' + err.message;
+            errorDiv.style.color = '#d32f2f';
+            errorDiv.style.marginTop = '8px';
+          }
+        });
     }
   </script>
 </body>
 </html>`;
   }
+  /**
+   * Serve a file from the custom viewer path
+   */
+  async serveCustomViewer(filePath) {
+    if (process.env.VERBOSE && console.log(`[VIEWER] serveCustomViewer called for: ${filePath}`), !this.viewerPath)
+      return console.error("[VIEWER] Custom viewer path not configured"), new Response("Custom viewer path not configured", { status: 500 });
+    try {
+      const path2 = await import("path"), fs = await import("fs/promises"), fullPath = path2.resolve(this.viewerPath, filePath);
+      if (process.env.VERBOSE && console.log(`[VIEWER] Resolved path: ${fullPath}`), !fullPath.startsWith(path2.resolve(this.viewerPath)))
+        return console.error("[VIEWER] Security check failed - path outside viewer directory"), new Response("Forbidden", { status: 403 });
+      process.env.VERBOSE && console.log(`[VIEWER] Reading file: ${fullPath}`);
+      const content = await fs.readFile(fullPath), ext = path2.extname(fullPath).toLowerCase(), contentType = {
+        ".html": "text/html",
+        ".css": "text/css",
+        ".js": "application/javascript",
+        ".json": "application/json",
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".gif": "image/gif",
+        ".svg": "image/svg+xml",
+        ".ico": "image/x-icon",
+        ".woff": "font/woff",
+        ".woff2": "font/woff2",
+        ".ttf": "font/ttf",
+        ".eot": "application/vnd.ms-fontobject"
+      }[ext] || "application/octet-stream";
+      return process.env.VERBOSE && console.log(`[VIEWER] Successfully read file, returning with Content-Type: ${contentType}`), new Response(content, {
+        status: 200,
+        headers: {
+          "Content-Type": contentType
+        }
+      });
+    } catch (error) {
+      return error.code === "ENOENT" ? (console.error(`[VIEWER] File not found: ${filePath}`), new Response("File not found", { status: 404 })) : (console.error(`[VIEWER] Error serving custom viewer file ${filePath}:`, error), new Response("Internal server error", { status: 500 }));
+    }
+  }
+  /**
+   * Load all changesets from disk into the in-memory map
+   */
+  async loadChangesetsFromDisk() {
+    if (this.changesetStorage)
+      try {
+        const changesets = await this.changesetStorage.list();
+        this.changesets.clear();
+        for (const cs of changesets)
+          this.changesets.set(cs.id, cs);
+        process.env.VERBOSE && console.log(`[Changesets] Loaded ${changesets.length} changeset(s) from disk`);
+      } catch (err) {
+        console.warn(`[Changesets] Warning: Failed to load changesets from disk: ${err}`);
+      }
+  }
   /**
    * Start the server
    */
   async start(port = 8080) {
-    this.setupFileWatcher(), this._server = serve({
+    this.changesetStorage = new StagedChangesetStorage(this.model.rootPath), await this.loadChangesetsFromDisk(), this.setupFileWatcher();
+    const { serve } = await import("bun");
+    this._server = serve({
       port,
       fetch: this.app.fetch,
       websocket
@@ -1189,6 +2247,30 @@ class VisualizationServer {
   isAuthEnabled() {
     return this.authEnabled;
   }
+  /**
+   * Kill a process with retry logic and exponential backoff
+   * Attempts graceful SIGTERM first, then force SIGKILL if needed
+   */
+  async killProcessWithRetry(proc, conversationId, label) {
+    let attempt = 0;
+    const baseDelay = 100;
+    for (; attempt < 3; ) {
+      try {
+        if (proc.killed || (proc.kill("SIGTERM"), await new Promise((resolve) => setTimeout(resolve, 500)), proc.killed))
+          return;
+      } catch {
+      }
+      if (attempt++, attempt < 3) {
+        const delay = baseDelay * Math.pow(2, attempt - 1);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+    try {
+      proc.killed || (proc.kill("SIGKILL"), console.warn(`[${label}] Process for conversation ${conversationId} did not respond to SIGTERM, force killed with SIGKILL`));
+    } catch (error) {
+      throw new Error(`Failed to kill process: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
   /**
    * Stop the server
    */
@@ -1196,7 +2278,9 @@ class VisualizationServer {
     for (const client of this.clients)
       try {
         client.close();
-      } catch {
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        errorMessage.includes("already closed") || console.warn(`[SERVER] Unexpected error closing WebSocket client: ${errorMessage}`);
       }
     this.clients.clear(), this.watcher && this.watcher.close?.(), this._server && this._server.stop();
   }