@documentation-robotics/cli 0.1.0

package/dist/server/server.js

@@ -0,0 +1,1207 @@
+import { Hono } from "hono";
+import { upgradeWebSocket, websocket } from "hono/bun";
+import { cors } from "hono/cors";
+import { serve } from "bun";
+import { Model } from "../core/model.js";
+import { telemetryMiddleware } from "./telemetry-middleware.js";
+class VisualizationServer {
+  app;
+  model;
+  _server;
+  clients = /* @__PURE__ */ new Set();
+  watcher;
+  annotations = /* @__PURE__ */ new Map();
+  // annotationId -> annotation
+  annotationsByElement = /* @__PURE__ */ new Map();
+  // elementId -> Set<annotationId>
+  changesets = /* @__PURE__ */ new Map();
+  // changesetId -> changeset
+  authToken;
+  authEnabled = !0;
+  // Enabled by default for security
+  activeChatProcesses = /* @__PURE__ */ new Map();
+  // conversationId -> Bun.spawn process
+  chatConversationCounter = 0;
+  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) => {
+      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}`);
+  }
+  /**
+   * Generate a random auth token
+   */
+  generateAuthToken() {
+    return `dr-${Date.now()}-${Math.random().toString(36).substring(2, 15)}`;
+  }
+  /**
+   * 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) => {
+      try {
+        const modelData = await this.serializeModel();
+        return c.json(modelData);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return c.json({ error: message }, 500);
+      }
+    }), this.app.get("/api/layers/:name", async (c) => {
+      try {
+        const layerName = c.req.param("name"), layer = await this.model.getLayer(layerName);
+        if (!layer)
+          return c.json({ error: "Layer not found" }, 404);
+        const elements = layer.listElements().map((e) => e.toJSON());
+        return c.json({
+          name: layerName,
+          elements,
+          elementCount: elements.length
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(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);
+      }
+    }), this.app.get("/api/spec", async (c) => {
+      try {
+        const schemas = await this.loadSchemas();
+        return c.json({
+          version: "0.1.0",
+          type: "schema-collection",
+          description: "JSON Schema definitions from dr CLI",
+          source: "dr-cli",
+          schemas,
+          schemaCount: Object.keys(schemas).length
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(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);
+      }
+    }), this.app.get("/api/annotations", (c) => {
+      const elementId = c.req.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 });
+      } else {
+        const annotations = Array.from(this.annotations.values());
+        return c.json({ annotations });
+      }
+    }), this.app.post("/api/annotations", 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);
+        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),
+          createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+          tags: body.tags || []
+        };
+        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",
+          annotationId: annotation.id,
+          elementId: annotation.elementId,
+          timestamp: annotation.createdAt
+        }), c.json(annotation, 201);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return c.json({ error: message }, 500);
+      }
+    }), this.app.put("/api/annotations/:annotationId", 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);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return c.json({ error: message }, 500);
+      }
+    }), this.app.delete("/api/annotations/:annotationId", async (c) => {
+      try {
+        const annotationId = c.req.param("annotationId"), annotation = this.annotations.get(annotationId);
+        if (!annotation)
+          return c.json({ error: "Annotation not found" }, 404);
+        this.annotations.delete(annotationId);
+        const elementAnnotations = this.annotationsByElement.get(annotation.elementId);
+        return elementAnnotations && elementAnnotations.delete(annotationId), await this.broadcastMessage({
+          type: "annotation.deleted",
+          annotationId,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        }), c.body(null, 204);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return c.json({ error: message }, 500);
+      }
+    }), this.app.get("/api/changesets", (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
+        };
+      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);
+      }
+    }), 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)
+          return c.json({ error: "Invalid authentication token" }, 403);
+      }
+      return next();
+    }, upgradeWebSocket(() => ({
+      onOpen: (_evt, ws) => {
+        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})`);
+      },
+      onMessage: async (message, ws) => {
+        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);
+        } 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({
+            type: "error",
+            message: errorMsg
+          }));
+        }
+      },
+      onError: (error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`[WebSocket] Error: ${message}`);
+      }
+    })));
+  }
+  /**
+   * Serialize model to JSON for client consumption
+   */
+  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
+        };
+      });
+      layers[name] = {
+        name,
+        elements,
+        elementCount: elements.length
+      };
+    }
+    return {
+      manifest: this.model.manifest.toJSON(),
+      layers,
+      totalElements: Array.from(this.model.layers.values()).reduce((sum, layer) => sum + layer.listElements().length, 0)
+    };
+  }
+  /**
+   * Generate unique annotation ID
+   */
+  generateAnnotationId() {
+    return `ann-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  }
+  /**
+   * Broadcast message to all connected WebSocket clients
+   */
+  async broadcastMessage(message) {
+    const messageStr = JSON.stringify(message);
+    let failureCount = 0;
+    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 > 0 && process.env.VERBOSE && console.warn(`[WebSocket] Failed to send message to ${failureCount}/${this.clients.size} clients`);
+  }
+  /**
+   * Find an element across all layers
+   */
+  async findElement(id) {
+    for (const layer of this.model.layers.values()) {
+      const element = layer.getElement(id);
+      if (element)
+        return element;
+    }
+    return null;
+  }
+  /**
+   * Handle WebSocket messages
+   */
+  async handleWSMessage(ws, data) {
+    switch (data.type) {
+      case "subscribe":
+        const topics = data.topics || ["model", "annotations"];
+        ws.send(JSON.stringify({
+          type: "subscribed",
+          topics,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        }));
+        const modelData = await this.serializeModel();
+        ws.send(JSON.stringify({
+          type: "model",
+          data: modelData,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        }));
+        break;
+      case "ping":
+        ws.send(JSON.stringify({
+          type: "pong",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        }));
+        break;
+      case "annotate":
+        data.annotation && await this.broadcastMessage({
+          type: "annotation",
+          data: data.annotation
+        });
+        break;
+      default:
+        ws.send(JSON.stringify({
+          type: "error",
+          message: `Unknown message type: ${data.type}`
+        }));
+    }
+  }
+  /**
+   * Handle JSON-RPC 2.0 messages for chat functionality
+   */
+  async handleJSONRPCMessage(ws, data) {
+    const { method, params, id } = data, sendResponse = (result) => {
+      ws.send(JSON.stringify({
+        jsonrpc: "2.0",
+        result,
+        id
+      }));
+    }, sendError = (code, message, data2) => {
+      ws.send(JSON.stringify({
+        jsonrpc: "2.0",
+        error: { code, message, data: data2 },
+        id
+      }));
+    };
+    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"
+          });
+          break;
+        case "chat.send":
+          if (!params || !params.message) {
+            sendError(-32602, "Message cannot be empty");
+            return;
+          }
+          if (!await this.checkClaudeCodeCLI()) {
+            sendError(-32001, "Claude Code CLI not available. Install Claude Code to enable chat.");
+            return;
+          }
+          const conversationId = `conv-${++this.chatConversationCounter}-${Date.now()}`;
+          await this.launchClaudeCodeChat(ws, conversationId, params.message, id);
+          break;
+        case "chat.cancel":
+          let cancelled = !1, cancelledConvId = null;
+          for (const [convId, process2] of this.activeChatProcesses)
+            try {
+              process2.kill(), this.activeChatProcesses.delete(convId), cancelled = !0, cancelledConvId = convId;
+              break;
+            } catch {
+            }
+          sendResponse({
+            cancelled,
+            conversation_id: cancelledConvId
+          });
+          break;
+        default:
+          sendError(-32601, `Method not found: ${method}`);
+      }
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      sendError(-32603, "Internal error", errorMsg);
+    }
+  }
+  /**
+   * Check if Claude Code CLI is available
+   */
+  async checkClaudeCodeCLI() {
+    try {
+      return Bun.spawnSync({
+        cmd: ["which", "claude"],
+        stdout: "pipe",
+        stderr: "pipe"
+      }).exitCode === 0;
+    } catch {
+      return !1;
+    }
+  }
+  /**
+   * Launch Claude Code CLI with dr-architect agent and stream responses
+   */
+  async launchClaudeCodeChat(ws, conversationId, message, requestId) {
+    try {
+      const proc = Bun.spawn({
+        cmd: [
+          "claude",
+          "--agent",
+          "dr-architect",
+          "--print",
+          "--dangerously-skip-permissions",
+          "--verbose",
+          "--output-format",
+          "stream-json"
+        ],
+        cwd: this.model.rootPath,
+        stdin: "pipe",
+        stdout: "pipe",
+        stderr: "pipe"
+      });
+      this.activeChatProcesses.set(conversationId, proc), proc.stdin?.write(new TextEncoder().encode(message)), proc.stdin?.end();
+      const stdoutReader = proc.stdout.getReader(), decoder = new TextDecoder();
+      (async () => {
+        let accumulatedText = "", buffer = "";
+        try {
+          for (; ; ) {
+            const { done, value } = await stdoutReader.read();
+            if (done)
+              break;
+            const chunk = decoder.decode(value, { stream: !0 });
+            buffer += chunk;
+            const lines = buffer.split(`
+`);
+            buffer = lines.pop() || "";
+            for (const line of lines)
+              if (line.trim())
+                try {
+                  const event = JSON.parse(line);
+                  if (event.type === "assistant") {
+                    const content = event.message?.content || [];
+                    for (const block of content)
+                      block.type === "text" ? (accumulatedText += block.text, ws.send(JSON.stringify({
+                        jsonrpc: "2.0",
+                        method: "chat.response.chunk",
+                        params: {
+                          conversation_id: conversationId,
+                          content: block.text,
+                          is_final: !1,
+                          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+                        }
+                      }))) : block.type === "tool_use" && ws.send(JSON.stringify({
+                        jsonrpc: "2.0",
+                        method: "chat.tool.invoke",
+                        params: {
+                          conversation_id: conversationId,
+                          tool_name: block.name,
+                          tool_input: block.input,
+                          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+                        }
+                      }));
+                  } else event.type === "result" && ws.send(JSON.stringify({
+                    jsonrpc: "2.0",
+                    method: "chat.tool.result",
+                    params: {
+                      conversation_id: conversationId,
+                      result: event.result,
+                      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+                    }
+                  }));
+                } catch {
+                  ws.send(JSON.stringify({
+                    jsonrpc: "2.0",
+                    method: "chat.response.chunk",
+                    params: {
+                      conversation_id: conversationId,
+                      content: line + `
+`,
+                      is_final: !1,
+                      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+                    }
+                  }));
+                }
+          }
+          buffer.trim() && ws.send(JSON.stringify({
+            jsonrpc: "2.0",
+            method: "chat.response.chunk",
+            params: {
+              conversation_id: conversationId,
+              content: buffer,
+              is_final: !0,
+              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 = error instanceof Error ? error.message : String(error);
+          ws.send(JSON.stringify({
+            jsonrpc: "2.0",
+            error: {
+              code: -32603,
+              message: `Chat failed: ${errorMsg}`
+            },
+            id: requestId
+          })), this.activeChatProcesses.delete(conversationId);
+          try {
+            proc.kill();
+          } catch {
+          }
+        }
+      })();
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      ws.send(JSON.stringify({
+        jsonrpc: "2.0",
+        error: {
+          code: -32603,
+          message: `Failed to launch Claude Code: ${errorMsg}`
+        },
+        id: requestId
+      }));
+    }
+  }
+  /**
+   * Setup file watcher for model changes
+   */
+  setupFileWatcher() {
+    const drPath = `${this.model.rootPath}/.dr`, 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}`);
+              }
+            }
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          console.error(`[Watcher] Failed to reload model: ${message}`);
+        }
+      }
+    });
+  }
+  /**
+   * Load all JSON schemas from bundled directory
+   */
+  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);
+        }
+      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);
+    } catch (error) {
+      throw console.error("Failed to load link registry:", error), new Error("Link registry not found");
+    }
+  }
+  /**
+   * Get viewer HTML
+   */
+  getViewerHTML() {
+    return `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Documentation Robotics Viewer</title>
+  <style>
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+      background: #f5f5f5;
+      color: #333;
+    }
+
+    header {
+      background: white;
+      border-bottom: 1px solid #e0e0e0;
+      padding: 20px;
+      box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+    }
+
+    .header-content {
+      max-width: 1400px;
+      margin: 0 auto;
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+    }
+
+    h1 {
+      font-size: 24px;
+      font-weight: 600;
+    }
+
+    .status-badge {
+      display: inline-block;
+      padding: 6px 12px;
+      border-radius: 4px;
+      font-size: 12px;
+      font-weight: 500;
+      text-transform: uppercase;
+      letter-spacing: 0.5px;
+    }
+
+    .status-badge.connected {
+      background: #4caf50;
+      color: white;
+    }
+
+    .status-badge.disconnected {
+      background: #f44336;
+      color: white;
+    }
+
+    .container {
+      max-width: 1400px;
+      margin: 0 auto;
+      padding: 20px;
+    }
+
+    .content {
+      display: grid;
+      grid-template-columns: 300px 1fr;
+      gap: 20px;
+      height: calc(100vh - 100px);
+    }
+
+    .sidebar {
+      background: white;
+      border-radius: 4px;
+      overflow-y: auto;
+      box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+      padding: 16px;
+    }
+
+    .main-panel {
+      background: white;
+      border-radius: 4px;
+      overflow-y: auto;
+      box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+      padding: 20px;
+    }
+
+    .layer-group {
+      margin-bottom: 16px;
+    }
+
+    .layer-header {
+      font-weight: 600;
+      padding: 8px 0;
+      border-bottom: 2px solid #e0e0e0;
+      margin-bottom: 8px;
+      cursor: pointer;
+      user-select: none;
+      display: flex;
+      align-items: center;
+    }
+
+    .layer-header:hover {
+      color: #2196F3;
+    }
+
+    .layer-header::before {
+      content: '\u25B6';
+      margin-right: 8px;
+      display: inline-block;
+      transition: transform 0.2s;
+    }
+
+    .layer-header.expanded::before {
+      transform: rotate(90deg);
+    }
+
+    .layer-elements {
+      margin-left: 16px;
+      display: none;
+    }
+
+    .layer-elements.expanded {
+      display: block;
+    }
+
+    .element-item {
+      padding: 8px;
+      margin-bottom: 4px;
+      background: #f9f9f9;
+      border-left: 3px solid #e0e0e0;
+      cursor: pointer;
+      border-radius: 2px;
+      transition: all 0.2s;
+      font-size: 13px;
+    }
+
+    .element-item:hover {
+      background: #f0f0f0;
+      border-left-color: #2196F3;
+    }
+
+    .element-item.selected {
+      background: #e3f2fd;
+      border-left-color: #2196F3;
+      font-weight: 500;
+    }
+
+    .element-details {
+      min-height: 300px;
+    }
+
+    .detail-header {
+      border-bottom: 2px solid #e0e0e0;
+      padding-bottom: 12px;
+      margin-bottom: 16px;
+    }
+
+    .detail-header h2 {
+      font-size: 18px;
+      margin-bottom: 4px;
+    }
+
+    .detail-header .element-type {
+      font-size: 12px;
+      color: #999;
+      text-transform: uppercase;
+      letter-spacing: 0.5px;
+    }
+
+    .detail-section {
+      margin-bottom: 16px;
+    }
+
+    .detail-section h3 {
+      font-size: 13px;
+      font-weight: 600;
+      text-transform: uppercase;
+      color: #999;
+      margin-bottom: 8px;
+      letter-spacing: 0.5px;
+    }
+
+    .detail-value {
+      font-size: 14px;
+      line-height: 1.6;
+      color: #333;
+      word-break: break-word;
+    }
+
+    .annotations-list {
+      max-height: 200px;
+      overflow-y: auto;
+      border: 1px solid #e0e0e0;
+      border-radius: 4px;
+      padding: 8px;
+    }
+
+    .annotation-item {
+      padding: 8px;
+      margin-bottom: 8px;
+      background: #fffde7;
+      border-left: 3px solid #fbc02d;
+      border-radius: 2px;
+      font-size: 12px;
+    }
+
+    .annotation-item .author {
+      font-weight: 600;
+      color: #666;
+    }
+
+    .annotation-item .text {
+      margin: 4px 0 0 0;
+      color: #333;
+    }
+
+    .annotation-item .timestamp {
+      font-size: 11px;
+      color: #999;
+      margin-top: 4px;
+    }
+
+    .annotation-form {
+      display: grid;
+      gap: 8px;
+      margin-top: 12px;
+    }
+
+    .annotation-form input,
+    .annotation-form textarea {
+      padding: 8px;
+      border: 1px solid #e0e0e0;
+      border-radius: 4px;
+      font-family: inherit;
+      font-size: 12px;
+    }
+
+    .annotation-form textarea {
+      resize: vertical;
+      min-height: 60px;
+    }
+
+    .annotation-form button {
+      padding: 8px 12px;
+      background: #2196F3;
+      color: white;
+      border: none;
+      border-radius: 4px;
+      font-weight: 500;
+      cursor: pointer;
+      transition: background 0.2s;
+    }
+
+    .annotation-form button:hover {
+      background: #1976D2;
+    }
+
+    .loading {
+      text-align: center;
+      padding: 40px;
+      color: #999;
+    }
+
+    .loading::after {
+      content: '';
+      display: inline-block;
+      width: 16px;
+      height: 16px;
+      border: 2px solid #f3f3f3;
+      border-top: 2px solid #2196F3;
+      border-radius: 50%;
+      animation: spin 1s linear infinite;
+      margin-left: 8px;
+    }
+
+    @keyframes spin {
+      0% { transform: rotate(0deg); }
+      100% { transform: rotate(360deg); }
+    }
+
+    .stats {
+      font-size: 12px;
+      color: #999;
+      margin-bottom: 16px;
+      padding-bottom: 12px;
+      border-bottom: 1px solid #e0e0e0;
+    }
+  </style>
+</head>
+<body>
+  <header>
+    <div class="header-content">
+      <div>
+        <h1>\u{1F4DA} Documentation Robotics Viewer</h1>
+      </div>
+      <div class="status-badge connected" id="status">\u25CF Connected</div>
+    </div>
+  </header>
+
+  <div class="container">
+    <div class="content">
+      <div class="sidebar">
+        <div class="stats" id="stats">Loading...</div>
+        <div id="model-tree">
+          <div class="loading">Loading model...</div>
+        </div>
+      </div>
+
+      <div class="main-panel">
+        <div id="element-details">
+          <div class="loading">Select an element to view details</div>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <script>
+    let currentModel = null;
+    let selectedElementId = null;
+
+    const statusEl = document.getElementById('status');
+    const modelTreeEl = document.getElementById('model-tree');
+    const detailsEl = document.getElementById('element-details');
+    const statsEl = document.getElementById('stats');
+
+    /**
+     * Escape HTML special characters to prevent XSS
+     * @param {string} text - Text to escape
+     * @returns {string} HTML-escaped text
+     */
+    function escapeHtml(text) {
+      if (!text) return '';
+      const div = document.createElement('div');
+      div.textContent = text;
+      return div.innerHTML;
+    }
+
+    const ws = new WebSocket(\`ws://\${window.location.host}/ws\`);
+
+    ws.addEventListener('open', () => {
+      console.log('WebSocket connected');
+      updateStatus(true);
+      ws.send(JSON.stringify({ type: 'subscribe' }));
+    });
+
+    ws.addEventListener('message', (event) => {
+      try {
+        const message = JSON.parse(event.data);
+
+        if (message.type === 'model' || message.type === 'model-update') {
+          currentModel = message.data;
+          renderModel();
+        } else if (message.type === 'annotation') {
+          // Update annotations for the element
+          renderSelectedElement();
+        } else if (message.type === 'error') {
+          console.error('WebSocket error:', message.message);
+        }
+      } catch (error) {
+        console.error('Failed to parse message:', error);
+      }
+    });
+
+    ws.addEventListener('close', () => {
+      console.log('WebSocket disconnected');
+      updateStatus(false);
+    });
+
+    ws.addEventListener('error', (error) => {
+      console.error('WebSocket error:', error);
+      updateStatus(false);
+    });
+
+    function updateStatus(connected) {
+      if (connected) {
+        statusEl.className = 'status-badge connected';
+        statusEl.textContent = '\u25CF Connected';
+      } else {
+        statusEl.className = 'status-badge disconnected';
+        statusEl.textContent = '\u25CF Disconnected';
+      }
+    }
+
+    function renderModel() {
+      if (!currentModel) return;
+
+      // Update stats
+      const layerCount = Object.keys(currentModel.layers).length;
+      const elementCount = currentModel.totalElements || 0;
+      statsEl.textContent = \`\${layerCount} layers \xB7 \${elementCount} elements\`;
+
+      // Render layers and elements
+      modelTreeEl.innerHTML = '';
+      const layers = Object.entries(currentModel.layers)
+        .sort((a, b) => a[0].localeCompare(b[0]));
+
+      for (const [layerName, layerData] of layers) {
+        const layerDiv = document.createElement('div');
+        layerDiv.className = 'layer-group';
+
+        const headerDiv = document.createElement('div');
+        headerDiv.className = 'layer-header';
+        headerDiv.textContent = layerName;
+        headerDiv.addEventListener('click', () => {
+          headerDiv.classList.toggle('expanded');
+          elementsDiv.classList.toggle('expanded');
+        });
+
+        const elementsDiv = document.createElement('div');
+        elementsDiv.className = 'layer-elements';
+
+        for (const element of layerData.elements) {
+          const elemDiv = document.createElement('div');
+          elemDiv.className = 'element-item';
+          if (element.id === selectedElementId) {
+            elemDiv.classList.add('selected');
+          }
+          elemDiv.innerHTML = \`\${escapeHtml(element.id)}<br><span style="font-size: 11px; color: #999;">\${escapeHtml(element.name)}</span>\`;
+          elemDiv.addEventListener('click', () => {
+            selectedElementId = element.id;
+            document.querySelectorAll('.element-item').forEach(el => el.classList.remove('selected'));
+            elemDiv.classList.add('selected');
+            renderSelectedElement();
+          });
+
+          elementsDiv.appendChild(elemDiv);
+        }
+
+        layerDiv.appendChild(headerDiv);
+        layerDiv.appendChild(elementsDiv);
+        modelTreeEl.appendChild(layerDiv);
+      }
+    }
+
+    function renderSelectedElement() {
+      if (!selectedElementId || !currentModel) {
+        detailsEl.innerHTML = '<div class="loading">Select an element to view details</div>';
+        return;
+      }
+
+      // Find element in model
+      let element = null;
+      for (const layer of Object.values(currentModel.layers)) {
+        element = layer.elements.find(e => e.id === selectedElementId);
+        if (element) break;
+      }
+
+      if (!element) {
+        detailsEl.innerHTML = '<div class="loading">Element not found</div>';
+        return;
+      }
+
+      let html = \`
+        <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>
+      \`;
+
+      if (element.description) {
+        html += \`
+          <div class="detail-section">
+            <h3>Description</h3>
+            <div class="detail-value">\${escapeHtml(element.description)}</div>
+          </div>
+        \`;
+      }
+
+      if (element.properties && Object.keys(element.properties).length > 0) {
+        html += \`
+          <div class="detail-section">
+            <h3>Properties</h3>
+            <div class="detail-value"><pre>\${escapeHtml(JSON.stringify(element.properties, null, 2))}</pre></div>
+          </div>
+        \`;
+      }
+
+      if (element.annotations && element.annotations.length > 0) {
+        html += \`
+          <div class="detail-section">
+            <h3>Annotations</h3>
+            <div class="annotations-list">
+              \${element.annotations.map(ann => \`
+                <div class="annotation-item">
+                  <div class="author">\${escapeHtml(ann.author)}</div>
+                  <div class="text">\${escapeHtml(ann.text)}</div>
+                  <div class="timestamp">\${new Date(ann.timestamp).toLocaleString()}</div>
+                </div>
+              \`).join('')}
+            </div>
+          </div>
+        \`;
+      }
+
+      html += \`
+        <div class="detail-section">
+          <h3>Add Annotation</h3>
+          <form class="annotation-form" onsubmit="addAnnotation(event, '\${escapeHtml(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>
+      \`;
+
+      detailsEl.innerHTML = html;
+    }
+
+    function addAnnotation(event, elementId) {
+      event.preventDefault();
+
+      const author = document.getElementById('ann-author').value;
+      const text = document.getElementById('ann-text').value;
+
+      if (!author || !text) return;
+
+      // Send to server
+      fetch(\`/api/elements/\${elementId}/annotations\`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ author, text })
+      })
+        .then(r => r.json())
+        .then(data => {
+          if (data.success) {
+            document.getElementById('ann-author').value = '';
+            document.getElementById('ann-text').value = '';
+          }
+        })
+        .catch(err => console.error('Failed to add annotation:', err));
+    }
+  </script>
+</body>
+</html>`;
+  }
+  /**
+   * Start the server
+   */
+  async start(port = 8080) {
+    this.setupFileWatcher(), this._server = serve({
+      port,
+      fetch: this.app.fetch,
+      websocket
+      // Add WebSocket handler from hono/bun
+    }), console.log(`\u2713 Visualization server running at http://localhost:${port}`);
+  }
+  /**
+   * Get the current auth token
+   */
+  getAuthToken() {
+    return this.authToken;
+  }
+  /**
+   * Check if authentication is enabled
+   */
+  isAuthEnabled() {
+    return this.authEnabled;
+  }
+  /**
+   * Stop the server
+   */
+  stop() {
+    for (const client of this.clients)
+      try {
+        client.close();
+      } catch {
+      }
+    this.clients.clear(), this.watcher && this.watcher.close?.(), this._server && this._server.stop();
+  }
+}
+export {
+  VisualizationServer
+};
+//# sourceMappingURL=server.js.map