viteboard 0.1.0 → 0.1.2

package/vite.config.ts

@@ -3,8 +3,10 @@ import { defineConfig, type Plugin, type Connect } from "vite";
 import { promises as fs } from "node:fs";
 import * as path from "node:path";
 import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
 import { promisify } from "node:util";
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { fileURLToPath } from "node:url";
 
 const WORKSPACE_DIR = ".workspace";
 const WORKSPACE_FILE = "workspace.json";
@@ -29,6 +31,18 @@ const MIME: Record<string, string> = {
   ".json": "application/json; charset=utf-8",
 };
 
+const MIME_EXT: Record<string, string> = {
+  "image/png": ".png",
+  "image/jpeg": ".jpg",
+  "image/webp": ".webp",
+  "image/gif": ".gif",
+  "image/svg+xml": ".svg",
+};
+const MANAGED_ASSET_RE = /^assets\/[a-f0-9]{64}\.(png|jpe?g|webp|gif|svg)$/i;
+const ACTOR_TTL_MS = 30000;
+const LOCK_TTL_MS = 30000;
+const ROOT_LINK_HEADER = '</llms.txt>; rel="describedby"; type="text/plain", </.well-known/viteboard.json>; rel="alternate"; type="application/json"';
+
 const execFileAsync = promisify(execFile);
 
 type WorkspaceManifest = {
@@ -59,6 +73,7 @@ type WorkspaceResponse = {
   projects: Array<{
     id: string;
     label: string;
+    rootPath: string;
     docsRoots: Array<{
       id: string;
       projectId: string;
@@ -73,10 +88,51 @@ type TreeNode =
   | { type: "file"; name: string; path: string }
   | { type: "dir"; name: string; path: string; children: TreeNode[] };
 
+type ActorState =
+  | "idle"
+  | "viewing-doc"
+  | "editing-doc"
+  | "viewing-board"
+  | "editing-board"
+  | "viewing-project"
+  | "writing";
+
+type ActorSessionRecord = {
+  actorId: string;
+  actorType: "human" | "agent";
+  label: string;
+  route: string;
+  state: ActorState;
+  rootId?: string;
+  projectId?: string;
+  docPath?: string;
+  boardId?: string;
+  updatedAt: number;
+  expiresAt: number;
+};
+
+type LockRecord = {
+  lockId: string;
+  actorId: string;
+  actorType: "human" | "agent";
+  label: string;
+  targetType: "doc" | "board";
+  rootId: string;
+  path?: string;
+  boardId?: string;
+  acquiredAt: number;
+  expiresAt: number;
+};
+
 function contentApiPlugin(): Plugin {
   const cwd = process.cwd();
+  const packageRoot = path.dirname(fileURLToPath(import.meta.url));
   const workspaceDir = path.resolve(cwd, WORKSPACE_DIR);
   const workspaceFile = path.join(workspaceDir, WORKSPACE_FILE);
+  const machineDir = path.join(packageRoot, "content", "machine");
+  const actorSessions = new Map<string, ActorSessionRecord>();
+  const locks = new Map<string, LockRecord>();
+  const sseClients = new Set<ServerResponse>();
 
   function send(res: ServerResponse, status: number, body: unknown): void {
     res.statusCode = status;
@@ -90,6 +146,87 @@ function contentApiPlugin(): Plugin {
     res.end(body);
   }
 
+  function sendSse(res: ServerResponse, event: string, body: unknown): void {
+    res.write(`event: ${event}\n`);
+    res.write(`data: ${JSON.stringify(body)}\n\n`);
+  }
+
+  function broadcast(event: string, body: unknown): void {
+    for (const client of sseClients) {
+      try {
+        sendSse(client, event, body);
+      } catch {
+        sseClients.delete(client);
+      }
+    }
+  }
+
+  function actorFromHeaders(req: IncomingMessage): { actorId: string; actorType: "human" | "agent"; label: string } | null {
+    const actorId = String(req.headers["x-viteboard-actor-id"] ?? "").trim();
+    if (!actorId) return null;
+    const actorType = String(req.headers["x-viteboard-actor-type"] ?? "human") === "agent" ? "agent" : "human";
+    const label = String(req.headers["x-viteboard-actor-label"] ?? "").trim() || (actorType === "agent" ? "Agent" : "ViteBoard UI");
+    return { actorId, actorType, label };
+  }
+
+  function lockKey(target: { targetType: "doc" | "board"; rootId: string; path?: string; boardId?: string }): string {
+    const suffix = target.targetType === "doc" ? target.path ?? "" : target.boardId ?? "";
+    return `${target.targetType}:${target.rootId}:${suffix}`;
+  }
+
+  function activeActors(): ActorSessionRecord[] {
+    return [...actorSessions.values()].sort((a, b) => a.label.localeCompare(b.label));
+  }
+
+  function activeLocks(): LockRecord[] {
+    return [...locks.values()].sort((a, b) => a.acquiredAt - b.acquiredAt);
+  }
+
+  function broadcastPresence(): void {
+    broadcast("presence", { actors: activeActors(), locks: activeLocks() });
+  }
+
+  function broadcastLocks(): void {
+    broadcast("lock-changed", { locks: activeLocks() });
+  }
+
+  function pruneEphemeral(): void {
+    const now = Date.now();
+    let changedPresence = false;
+    let changedLocks = false;
+    for (const [actorId, actor] of actorSessions) {
+      if (actor.expiresAt <= now) {
+        actorSessions.delete(actorId);
+        changedPresence = true;
+      }
+    }
+    for (const [key, lock] of locks) {
+      if (lock.expiresAt <= now || !actorSessions.has(lock.actorId)) {
+        locks.delete(key);
+        changedLocks = true;
+      }
+    }
+    if (changedPresence) broadcastPresence();
+    else if (changedLocks) broadcastLocks();
+  }
+
+  function extendActorLocks(actorId: string): void {
+    const now = Date.now();
+    for (const lock of locks.values()) {
+      if (lock.actorId === actorId) lock.expiresAt = now + LOCK_TTL_MS;
+    }
+  }
+
+  async function readMachineAsset(fileName: string): Promise<string> {
+    return fs.readFile(path.join(machineDir, fileName), "utf-8");
+  }
+
+  function revisionForText(content: string): string {
+    return createHash("sha1").update(content).digest("hex");
+  }
+
+  setInterval(pruneEphemeral, 10000).unref?.();
+
   function readBody(req: IncomingMessage): Promise<string> {
     return new Promise((resolve, reject) => {
       let data = "";
@@ -114,6 +251,48 @@ function contentApiPlugin(): Plugin {
     return (hash >>> 0).toString(36);
   }
 
+  async function canonicalizeProjectRoot(rootPath: string): Promise<string> {
+    const resolved = path.resolve(rootPath);
+    try {
+      return path.resolve(await fs.realpath(resolved));
+    } catch {
+      return resolved;
+    }
+  }
+
+  function isNestedPath(parent: string, child: string): boolean {
+    const rel = path.relative(parent, child);
+    return rel !== "" && rel !== "." && !rel.startsWith("..") && !path.isAbsolute(rel);
+  }
+
+  function findOverlappingProject(
+    projects: WorkspaceProjectRecord[],
+    candidateRoot: string,
+    ignoreProjectId?: string
+  ): WorkspaceProjectRecord | null {
+    for (const project of projects) {
+      if (ignoreProjectId && project.id === ignoreProjectId) continue;
+      if (
+        project.rootPath === candidateRoot ||
+        isNestedPath(project.rootPath, candidateRoot) ||
+        isNestedPath(candidateRoot, project.rootPath)
+      ) {
+        return project;
+      }
+    }
+    return null;
+  }
+
+  function overlapError(existing: WorkspaceProjectRecord, candidateRoot: string): string {
+    if (existing.rootPath === candidateRoot) {
+      return `\"${existing.label}\" is already added. Pick a different folder, or remove the existing project first.`;
+    }
+    if (isNestedPath(existing.rootPath, candidateRoot)) {
+      return `That folder is inside the existing workspace project \"${existing.label}\". ViteBoard only allows one project root per nested path.`;
+    }
+    return `That folder contains the existing workspace project \"${existing.label}\". Add the more specific project instead, or remove the current one first.`;
+  }
+
   async function ensureWorkspaceDir(): Promise<void> {
     await fs.mkdir(workspaceDir, { recursive: true });
   }
@@ -122,17 +301,26 @@ function contentApiPlugin(): Plugin {
     try {
       const raw = await fs.readFile(workspaceFile, "utf-8");
       const parsed = JSON.parse(raw) as Partial<WorkspaceManifest>;
-      const projects = Array.isArray(parsed.projects)
-        ? parsed.projects
-            .filter((item): item is WorkspaceProjectRecord => {
-              return !!item && typeof item.id === "string" && typeof item.rootPath === "string";
-            })
-            .map((item) => ({
-              id: item.id,
-              label: typeof item.label === "string" && item.label.trim() ? item.label.trim() : path.basename(item.rootPath),
-              rootPath: path.resolve(item.rootPath),
-            }))
+      const rawProjects = Array.isArray(parsed.projects)
+        ? parsed.projects.filter((item): item is WorkspaceProjectRecord => {
+            return !!item && typeof item.id === "string" && typeof item.rootPath === "string";
+          })
         : [];
+      const projects: WorkspaceProjectRecord[] = [];
+      const seenIds = new Set<string>();
+      const seenPaths = new Set<string>();
+      for (const item of rawProjects) {
+        const rootPath = await canonicalizeProjectRoot(item.rootPath);
+        const id = item.id.trim() || `project-${hashPath(rootPath)}`;
+        if (seenIds.has(id) || seenPaths.has(rootPath)) continue;
+        seenIds.add(id);
+        seenPaths.add(rootPath);
+        projects.push({
+          id,
+          label: typeof item.label === "string" && item.label.trim() ? item.label.trim() : path.basename(rootPath),
+          rootPath,
+        });
+      }
       return { version: 1, projects };
     } catch {
       return { version: 1, projects: [] };
@@ -153,10 +341,7 @@ function contentApiPlugin(): Plugin {
   }
 
   async function loadProjects(): Promise<WorkspaceProjectRecord[]> {
-    const manifest = await loadManifest();
-    return manifest.projects.filter((item, index, list) => {
-      return list.findIndex((other) => other.rootPath === item.rootPath) === index;
-    });
+    return (await loadManifest()).projects;
   }
 
   async function openProjectPicker(): Promise<string | null> {
@@ -290,6 +475,7 @@ function contentApiPlugin(): Plugin {
       projects: projects.map((project) => ({
         id: project.id,
         label: project.label,
+        rootPath: project.rootPath,
         docsRoots: project.docsRoots.map((root) => ({
           id: root.id,
           projectId: root.projectId,
@@ -323,6 +509,142 @@ function contentApiPlugin(): Plugin {
     return abs;
   }
 
+  function normalizeRelativePath(input: string): string {
+    const parts: string[] = [];
+    for (const raw of String(input ?? "").replace(/\\/g, "/").split("/")) {
+      const part = raw.trim();
+      if (!part || part === ".") continue;
+      if (part === "..") {
+        if (parts.length > 0) parts.pop();
+        continue;
+      }
+      parts.push(part);
+    }
+    return parts.join("/");
+  }
+
+  function dirnamePosix(filePath: string): string {
+    const normalized = normalizeRelativePath(filePath);
+    const idx = normalized.lastIndexOf("/");
+    return idx === -1 ? "" : normalized.slice(0, idx);
+  }
+
+  function resolveDocRelativePath(fromFile: string, target: string): string | null {
+    const raw = String(target ?? "").trim();
+    if (!raw || /^(https?:|mailto:|tel:|#|data:)/i.test(raw)) return null;
+    if (raw.startsWith("/")) return normalizeRelativePath(raw);
+    const base = dirnamePosix(fromFile);
+    return normalizeRelativePath(base ? `${base}/${raw}` : raw);
+  }
+
+  function isManagedAssetPath(relPath: string): boolean {
+    return MANAGED_ASSET_RE.test(normalizeRelativePath(relPath));
+  }
+
+  async function collectFiles(dir: string, base = ""): Promise<string[]> {
+    let entries: import("node:fs").Dirent[];
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return [];
+    }
+
+    const files: string[] = [];
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) continue;
+      const rel = base ? `${base}/${entry.name}` : entry.name;
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        files.push(...(await collectFiles(abs, rel)));
+      } else {
+        files.push(rel);
+      }
+    }
+    return files;
+  }
+
+  function collectBoardAssetRefs(raw: unknown): Set<string> {
+    const refs = new Set<string>();
+    if (typeof raw !== "object" || raw === null) return refs;
+    const elements = Array.isArray((raw as { elements?: unknown[] }).elements)
+      ? (raw as { elements: unknown[] }).elements
+      : [];
+    for (const element of elements) {
+      if (typeof element !== "object" || element === null) continue;
+      const data = (element as { data?: Record<string, unknown> }).data;
+      const src = typeof data?.src === "string" ? normalizeRelativePath(data.src) : "";
+      if (isManagedAssetPath(src)) refs.add(src);
+    }
+    return refs;
+  }
+
+  function collectMarkdownAssetRefs(markdown: string, docPath: string): Set<string> {
+    const refs = new Set<string>();
+    const imagePatterns = [
+      /!\[[^\]]*\]\(([^)\s]+)\)/g,
+      /<img\b[^>]*\bsrc=["']([^"']+)["'][^>]*>/gi,
+    ];
+
+    for (const pattern of imagePatterns) {
+      pattern.lastIndex = 0;
+      let match: RegExpExecArray | null;
+      while ((match = pattern.exec(markdown))) {
+        const resolved = resolveDocRelativePath(docPath, match[1]);
+        if (resolved && isManagedAssetPath(resolved)) refs.add(resolved);
+      }
+    }
+
+    return refs;
+  }
+
+  async function cleanupManagedAssets(rootAbsPath: string, preservePaths: string[] = []): Promise<number> {
+    const allFiles = await collectFiles(rootAbsPath);
+    const managedAssets = allFiles.filter((file) => isManagedAssetPath(file));
+    if (managedAssets.length === 0) return 0;
+
+    const referenced = new Set<string>();
+    for (const relPath of allFiles) {
+      const abs = safeResolve(rootAbsPath, relPath);
+      if (!abs) continue;
+      if (relPath.endsWith(".board.json")) {
+        try {
+          const raw = JSON.parse(await fs.readFile(abs, "utf-8"));
+          for (const ref of collectBoardAssetRefs(raw)) referenced.add(ref);
+        } catch {
+          // Ignore unreadable or invalid boards; cleanup stays conservative.
+        }
+        continue;
+      }
+      if (relPath.endsWith(".md")) {
+        try {
+          const markdown = await fs.readFile(abs, "utf-8");
+          for (const ref of collectMarkdownAssetRefs(markdown, relPath)) referenced.add(ref);
+        } catch {
+          // Ignore unreadable docs; cleanup stays conservative.
+        }
+      }
+    }
+
+    for (const relPath of preservePaths) {
+      const normalized = normalizeRelativePath(relPath);
+      if (isManagedAssetPath(normalized)) referenced.add(normalized);
+    }
+
+    let removed = 0;
+    for (const relPath of managedAssets) {
+      if (referenced.has(relPath)) continue;
+      const abs = safeResolve(rootAbsPath, relPath);
+      if (!abs) continue;
+      try {
+        await fs.unlink(abs);
+        removed++;
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+      }
+    }
+    return removed;
+  }
+
   async function walkDocsRoot(dir: string, base: string, nestedRoots: Set<string>): Promise<TreeNode[]> {
     let entries: import("node:fs").Dirent[];
     try {
@@ -358,7 +680,7 @@ function contentApiPlugin(): Plugin {
     return nodes;
   }
 
-  /** Walk full project directory tree — returns only directories (no files). */
+  /** Walk the project tree for Raw sidebar mode. */
   async function walkProjectTree(dir: string, base: string): Promise<TreeNode[]> {
     let entries: import("node:fs").Dirent[];
     try {
@@ -368,44 +690,247 @@ function contentApiPlugin(): Plugin {
     }
     const nodes: TreeNode[] = [];
     for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
       if (entry.name.startsWith(".")) continue;
-      if (isIgnoredDir(entry.name)) continue;
       const rel = base ? `${base}/${entry.name}` : entry.name;
-      nodes.push({
-        type: "dir",
-        name: entry.name,
-        path: rel,
-        children: await walkProjectTree(path.join(dir, entry.name), rel),
-      });
+      if (entry.isDirectory()) {
+        if (isIgnoredDir(entry.name)) continue;
+        nodes.push({
+          type: "dir",
+          name: entry.name,
+          path: rel,
+          children: await walkProjectTree(path.join(dir, entry.name), rel),
+        });
+      } else {
+        nodes.push({ type: "file", name: entry.name, path: rel });
+      }
     }
-    nodes.sort((a, b) => a.name.localeCompare(b.name));
+    nodes.sort((a, b) => {
+      if (a.type !== b.type) return a.type === "dir" ? -1 : 1;
+      return a.name.localeCompare(b.name);
+    });
     return nodes;
   }
 
+  async function sendMachineFile(res: ServerResponse, fileName: string, contentType: string): Promise<void> {
+    return sendText(res, 200, await readMachineAsset(fileName), contentType);
+  }
+
   const handler: Connect.NextHandleFunction = (req, res, next) => {
     const url = req.url ?? "";
-    if (!url.startsWith("/__api/")) return next();
+    const parsed = new URL(url, "http://localhost");
+    const route = parsed.pathname;
+
+    if (route === "/" || route === "/index.html") {
+      res.setHeader("Link", ROOT_LINK_HEADER);
+      return next();
+    }
+
+    if (route === "/llms.txt") {
+      void sendMachineFile(res, "llms.txt", "text/plain; charset=utf-8");
+      return;
+    }
+
+    if (route === "/.well-known/viteboard.json") {
+      void sendMachineFile(res, "viteboard.json", "application/json; charset=utf-8");
+      return;
+    }
+
+    if (route === "/viteboard-guide.md") {
+      void sendMachineFile(res, "guide.md", "text/markdown; charset=utf-8");
+      return;
+    }
+
+    if (route === "/board-v1.schema.json") {
+      void sendMachineFile(res, "board-v1.schema.json", "application/schema+json; charset=utf-8");
+      return;
+    }
+
+    if (route === "/viteboard-example.board.json") {
+      void sendMachineFile(res, "example.board.json", "application/json; charset=utf-8");
+      return;
+    }
+
+    if (!route.startsWith("/__api/")) return next();
 
     void (async () => {
       try {
-        const parsed = new URL(url, "http://localhost");
-        const route = parsed.pathname;
         const method = (req.method ?? "GET").toUpperCase();
+        const actor = actorFromHeaders(req);
+        pruneEphemeral();
 
         if (route === "/__api/workspace" && method === "GET") {
           return send(res, 200, await toWorkspaceResponse(await getWorkspace()));
         }
 
+        if (route === "/__api/events" && method === "GET") {
+          res.statusCode = 200;
+          res.setHeader("Content-Type", "text/event-stream; charset=utf-8");
+          res.setHeader("Cache-Control", "no-cache, no-transform");
+          res.setHeader("Connection", "keep-alive");
+          res.write(": connected\n\n");
+          sseClients.add(res);
+          sendSse(res, "hello", { actors: activeActors(), locks: activeLocks() });
+          req.on("close", () => {
+            sseClients.delete(res);
+          });
+          return;
+        }
+
+        if (route === "/__api/actors/session" && method === "GET") {
+          return send(res, 200, { actors: activeActors() });
+        }
+
+        if (route === "/__api/actors/session" && method === "POST") {
+          const body = JSON.parse(await readBody(req));
+          const actorId = String(body.actorId ?? actor?.actorId ?? "").trim();
+          if (!actorId) return send(res, 400, { error: "actorId is required" });
+          const actorType = String(body.actorType ?? actor?.actorType ?? "human") === "agent" ? "agent" : "human";
+          const label = String(body.label ?? actor?.label ?? "").trim() || (actorType === "agent" ? "Agent" : "ViteBoard UI");
+          const now = Date.now();
+          actorSessions.set(actorId, {
+            actorId,
+            actorType,
+            label,
+            route: String(body.route ?? "#/"),
+            state: String(body.state ?? "idle") as ActorState,
+            rootId: typeof body.rootId === "string" ? body.rootId : undefined,
+            projectId: typeof body.projectId === "string" ? body.projectId : undefined,
+            docPath: typeof body.docPath === "string" ? body.docPath : undefined,
+            boardId: typeof body.boardId === "string" ? body.boardId : undefined,
+            selectedElementIds: Array.isArray(body.selectedElementIds)
+              ? body.selectedElementIds.filter((item: unknown): item is string => typeof item === "string")
+              : undefined,
+            updatedAt: now,
+            expiresAt: now + ACTOR_TTL_MS,
+          });
+          extendActorLocks(actorId);
+          broadcastPresence();
+          return send(res, 200, { ok: true });
+        }
+
+        if (route === "/__api/actors/heartbeat" && method === "POST") {
+          const body = JSON.parse(await readBody(req));
+          const actorId = String(body.actorId ?? actor?.actorId ?? "").trim();
+          if (!actorId) return send(res, 400, { error: "actorId is required" });
+          const current = actorSessions.get(actorId);
+          if (!current) return send(res, 404, { error: "Actor session not found" });
+          const now = Date.now();
+          const next: ActorSessionRecord = {
+            ...current,
+            route: typeof body.route === "string" ? body.route : current.route,
+            state: typeof body.state === "string" ? (body.state as ActorState) : current.state,
+            rootId: typeof body.rootId === "string" ? body.rootId : current.rootId,
+            projectId: typeof body.projectId === "string" ? body.projectId : current.projectId,
+            docPath: typeof body.docPath === "string" ? body.docPath : current.docPath,
+            boardId: typeof body.boardId === "string" ? body.boardId : current.boardId,
+            selectedElementIds: Array.isArray(body.selectedElementIds)
+              ? body.selectedElementIds.filter((item: unknown): item is string => typeof item === "string")
+              : current.selectedElementIds,
+            updatedAt: now,
+            expiresAt: now + ACTOR_TTL_MS,
+          };
+          actorSessions.set(actorId, next);
+          extendActorLocks(actorId);
+          broadcastPresence();
+          return send(res, 200, { ok: true });
+        }
+
+        if (route === "/__api/actors/session" && method === "DELETE") {
+          const actorId = parsed.searchParams.get("actorId") ?? actor?.actorId ?? "";
+          if (!actorId) return send(res, 400, { error: "actorId is required" });
+          actorSessions.delete(actorId);
+          let changedLocks = false;
+          for (const [key, lock] of locks) {
+            if (lock.actorId === actorId) {
+              locks.delete(key);
+              changedLocks = true;
+            }
+          }
+          if (changedLocks) broadcastLocks();
+          broadcastPresence();
+          return send(res, 200, { ok: true });
+        }
+
+        if (route === "/__api/locks" && method === "GET") {
+          return send(res, 200, { locks: activeLocks() });
+        }
+
+        if (route === "/__api/locks/acquire" && method === "POST") {
+          const body = JSON.parse(await readBody(req));
+          if (!actor?.actorId) return send(res, 400, { error: "actor identity is required" });
+          const targetType = body.targetType === "board" ? "board" : body.targetType === "doc" ? "doc" : null;
+          const rootId = String(body.rootId ?? "").trim();
+          if (!targetType || !rootId) return send(res, 400, { error: "targetType and rootId are required" });
+          const resolved = await resolveRoot(rootId);
+          if (!resolved) return send(res, 404, { error: "Docs root not found" });
+          const targetPath = targetType === "doc" ? String(body.path ?? "").trim() : undefined;
+          const targetBoardId = targetType === "board" ? String(body.boardId ?? "").trim() : undefined;
+          const targetAbs = targetType === "doc"
+            ? safeResolve(resolved.root.absPath, targetPath ?? "")
+            : safeResolve(resolved.root.absPath, `${targetBoardId}.board.json`);
+          if (!targetAbs) {
+            return send(res, 400, { error: targetType === "doc" ? "Invalid path" : "Invalid boardId" });
+          }
+          const key = lockKey({ targetType, rootId, path: targetPath, boardId: targetBoardId });
+          const now = Date.now();
+          const existing = locks.get(key);
+          if (existing && existing.actorId !== actor.actorId && existing.expiresAt > now) {
+            return send(res, 409, { error: `${existing.label} is editing this ${targetType}.`, lock: existing });
+          }
+          const nextLock: LockRecord = existing && existing.actorId === actor.actorId
+            ? { ...existing, expiresAt: now + LOCK_TTL_MS }
+            : {
+                lockId: `lock-${hashPath(`${key}:${now}`)}`,
+                actorId: actor.actorId,
+                actorType: actor.actorType,
+                label: actor.label,
+                targetType,
+                rootId,
+                path: targetPath,
+                boardId: targetBoardId,
+                acquiredAt: now,
+                expiresAt: now + LOCK_TTL_MS,
+              };
+          locks.set(key, nextLock);
+          broadcastLocks();
+          broadcastPresence();
+          return send(res, 200, { ok: true, lock: nextLock });
+        }
+
+        if (route === "/__api/locks/release" && method === "POST") {
+          const body = JSON.parse(await readBody(req));
+          if (!actor?.actorId) return send(res, 400, { error: "actor identity is required" });
+          const targetType = body.targetType === "board" ? "board" : body.targetType === "doc" ? "doc" : null;
+          const rootId = String(body.rootId ?? "").trim();
+          if (!targetType || !rootId) return send(res, 400, { error: "targetType and rootId are required" });
+          const key = lockKey({
+            targetType,
+            rootId,
+            path: targetType === "doc" ? String(body.path ?? "").trim() : undefined,
+            boardId: targetType === "board" ? String(body.boardId ?? "").trim() : undefined,
+          });
+          const existing = locks.get(key);
+          if (!existing) return send(res, 200, { ok: true });
+          if (existing.actorId !== actor.actorId) return send(res, 403, { error: "Lock owned by another actor" });
+          locks.delete(key);
+          broadcastLocks();
+          broadcastPresence();
+          return send(res, 200, { ok: true });
+        }
+
         if (route === "/__api/workspace/project" && method === "POST") {
           const { rootPath, label } = JSON.parse(await readBody(req));
-          const absRoot = path.resolve(String(rootPath ?? "").trim());
+          const absRoot = await canonicalizeProjectRoot(String(rootPath ?? "").trim());
           if (!absRoot || !(await dirExists(absRoot))) {
             return send(res, 400, { error: "Project root not found" });
           }
           const manifest = await loadManifest();
+          const existingProject = manifest.projects.find((item) => item.rootPath === absRoot);
+          const projectId = existingProject?.id ?? `project-${hashPath(absRoot)}`;
+          const overlap = findOverlappingProject(manifest.projects, absRoot, projectId);
+          if (overlap) return send(res, 409, { error: overlapError(overlap, absRoot) });
           const project: WorkspaceProjectRecord = {
-            id: `project-${hashPath(absRoot)}`,
+            id: projectId,
             label: String(label ?? "").trim() || path.basename(absRoot) || absRoot,
             rootPath: absRoot,
           };
@@ -413,17 +938,22 @@ function contentApiPlugin(): Plugin {
           if (existingIndex === -1) manifest.projects.push(project);
           else manifest.projects.splice(existingIndex, 1, project);
           await saveManifest(manifest);
+          broadcast("workspace-changed", { action: "project-added", projectId: project.id, actorId: actor?.actorId ?? null });
           return send(res, 200, await toWorkspaceResponse(await getWorkspace()));
         }
 
         if (route === "/__api/workspace/pick-project" && method === "POST") {
           const picked = await openProjectPicker();
           if (!picked) return send(res, 200, { cancelled: true, workspace: await toWorkspaceResponse(await getWorkspace()) });
-          const absRoot = path.resolve(picked);
+          const absRoot = await canonicalizeProjectRoot(picked);
           if (!(await dirExists(absRoot))) return send(res, 400, { error: "Project root not found" });
           const manifest = await loadManifest();
+          const existingProject = manifest.projects.find((item) => item.rootPath === absRoot);
+          const projectId = existingProject?.id ?? `project-${hashPath(absRoot)}`;
+          const overlap = findOverlappingProject(manifest.projects, absRoot, projectId);
+          if (overlap) return send(res, 409, { error: overlapError(overlap, absRoot) });
           const project: WorkspaceProjectRecord = {
-            id: `project-${hashPath(absRoot)}`,
+            id: projectId,
             label: path.basename(absRoot) || absRoot,
             rootPath: absRoot,
           };
@@ -431,6 +961,7 @@ function contentApiPlugin(): Plugin {
           if (existingIndex === -1) manifest.projects.push(project);
           else manifest.projects.splice(existingIndex, 1, project);
           await saveManifest(manifest);
+          broadcast("workspace-changed", { action: "project-added", projectId: project.id, actorId: actor?.actorId ?? null });
           return send(res, 200, { cancelled: false, workspace: await toWorkspaceResponse(await getWorkspace()), addedProjectId: project.id });
         }
 
@@ -446,6 +977,7 @@ function contentApiPlugin(): Plugin {
           const root = refreshedProject?.docsRoots.find((item) => item.absPath === docsPath)
             ?? refreshedProject?.docsRoots[0];
           if (!root) return send(res, 500, { error: "Could not create docs root" });
+          broadcast("workspace-changed", { action: "docs-root-created", projectId: project.id, rootId: root.id, actorId: actor?.actorId ?? null });
           return send(res, 200, {
             root: {
               id: root.id,
@@ -470,6 +1002,7 @@ function contentApiPlugin(): Plugin {
           const refreshedProject = workspace.find((item) => item.id === project.id);
           const root = refreshedProject?.docsRoots.find((item) => item.absPath === docsPath);
           if (!root) return send(res, 500, { error: "Could not create docs area" });
+          broadcast("workspace-changed", { action: "docs-area-created", projectId: project.id, rootId: root.id, actorId: actor?.actorId ?? null });
           return send(res, 200, {
             root: {
               id: root.id,
@@ -489,6 +1022,7 @@ function contentApiPlugin(): Plugin {
           if (!project) return send(res, 404, { error: "Project not found" });
           const docsPath = path.join(project.rootPath, String(parentPath ?? ""), "docs");
           await fs.mkdir(docsPath, { recursive: true });
+          broadcast("workspace-changed", { action: "docs-folder-created", projectId: project.id, actorId: actor?.actorId ?? null });
           return send(res, 200, { ok: true, workspace: await toWorkspaceResponse(await getWorkspace()) });
         }
 
@@ -497,6 +1031,7 @@ function contentApiPlugin(): Plugin {
           const manifest = await loadManifest();
           manifest.projects = manifest.projects.filter((item) => item.id !== id);
           await saveManifest(manifest);
+          broadcast("workspace-changed", { action: "project-removed", projectId: id, actorId: actor?.actorId ?? null });
           return send(res, 200, await toWorkspaceResponse(await getWorkspace()));
         }
 
@@ -526,21 +1061,38 @@ function contentApiPlugin(): Plugin {
           if (!abs) return send(res, 400, { error: "Invalid path" });
           try {
             const content = await fs.readFile(abs, "utf-8");
-            return send(res, 200, { path: rel, content });
+            return send(res, 200, { path: rel, content, revision: revisionForText(content) });
           } catch {
             return send(res, 404, { error: "Not found" });
           }
         }
 
         if (route === "/__api/file" && method === "PUT") {
-          const { rootId, path: rel, content } = JSON.parse(await readBody(req));
+          const { rootId, path: rel, content, expectedRevision } = JSON.parse(await readBody(req));
           const resolved = await resolveRoot(String(rootId ?? ""));
           if (!resolved) return send(res, 404, { error: "Docs root not found" });
           const abs = safeResolve(resolved.root.absPath, String(rel));
           if (!abs) return send(res, 400, { error: "Invalid path" });
+          let currentContent: string | null = null;
+          try {
+            currentContent = await fs.readFile(abs, "utf-8");
+          } catch (err) {
+            if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+          }
+          const currentRevision = currentContent === null ? null : revisionForText(currentContent);
+          if (typeof expectedRevision === "string" && expectedRevision !== currentRevision) {
+            return send(res, 409, {
+              error: "File changed on disk",
+              currentRevision,
+              path: rel,
+            });
+          }
           await fs.mkdir(path.dirname(abs), { recursive: true });
-          await fs.writeFile(abs, String(content ?? ""), "utf-8");
-          return send(res, 200, { ok: true, path: rel });
+          const nextContent = String(content ?? "");
+          await fs.writeFile(abs, nextContent, "utf-8");
+          const revision = revisionForText(nextContent);
+          broadcast("file-changed", { rootId: resolved.root.id, path: String(rel), action: "write", actorId: actor?.actorId ?? null });
+          return send(res, 200, { ok: true, path: rel, revision });
         }
 
         if (route === "/__api/directory" && method === "PUT") {
@@ -550,6 +1102,7 @@ function contentApiPlugin(): Plugin {
           const abs = safeResolve(resolved.root.absPath, String(rel));
           if (!abs) return send(res, 400, { error: "Invalid path" });
           await fs.mkdir(abs, { recursive: true });
+          broadcast("workspace-changed", { action: "directory-created", rootId: resolved.root.id, path: String(rel), actorId: actor?.actorId ?? null });
           return send(res, 200, { ok: true, path: rel });
         }
 
@@ -565,6 +1118,7 @@ function contentApiPlugin(): Plugin {
           } catch (err) {
             if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
           }
+          broadcast("file-changed", { rootId: resolved.root.id, path: rel, action: "delete", actorId: actor?.actorId ?? null });
           return send(res, 200, { ok: true });
         }
 
@@ -585,6 +1139,7 @@ function contentApiPlugin(): Plugin {
             }
             throw err;
           }
+          broadcast("file-changed", { rootId: resolved.root.id, path: String(newPath), oldPath: String(oldPath), action: "rename", actorId: actor?.actorId ?? null });
           return send(res, 200, { ok: true, path: newPath });
         }
 
@@ -597,21 +1152,38 @@ function contentApiPlugin(): Plugin {
           if (!abs) return send(res, 400, { error: "Invalid id" });
           try {
             const content = await fs.readFile(abs, "utf-8");
-            return send(res, 200, { id, doc: JSON.parse(content) });
+            return send(res, 200, { id, doc: JSON.parse(content), revision: revisionForText(content) });
           } catch {
             return send(res, 404, { error: "Not found" });
           }
         }
 
         if (route === "/__api/board" && method === "PUT") {
-          const { rootId, id, doc } = JSON.parse(await readBody(req));
+          const { rootId, id, doc, expectedRevision } = JSON.parse(await readBody(req));
           const resolved = await resolveRoot(String(rootId ?? ""));
           if (!resolved) return send(res, 404, { error: "Docs root not found" });
           const abs = safeResolve(resolved.root.absPath, `${String(id)}.board.json`);
           if (!abs) return send(res, 400, { error: "Invalid id" });
+          let currentContent: string | null = null;
+          try {
+            currentContent = await fs.readFile(abs, "utf-8");
+          } catch (err) {
+            if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+          }
+          const currentRevision = currentContent === null ? null : revisionForText(currentContent);
+          if (typeof expectedRevision === "string" && expectedRevision !== currentRevision) {
+            return send(res, 409, {
+              error: "Board changed on disk",
+              currentRevision,
+              id,
+            });
+          }
           await fs.mkdir(path.dirname(abs), { recursive: true });
-          await fs.writeFile(abs, JSON.stringify(doc, null, 2) + "\n", "utf-8");
-          return send(res, 200, { ok: true, id });
+          const nextContent = JSON.stringify(doc, null, 2) + "\n";
+          await fs.writeFile(abs, nextContent, "utf-8");
+          const revision = revisionForText(nextContent);
+          broadcast("board-changed", { rootId: resolved.root.id, boardId: String(id), action: "write", actorId: actor?.actorId ?? null });
+          return send(res, 200, { ok: true, id, revision });
         }
 
         if (route === "/__api/board" && method === "DELETE") {
@@ -626,6 +1198,7 @@ function contentApiPlugin(): Plugin {
           } catch (err) {
             if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
           }
+          broadcast("board-changed", { rootId: resolved.root.id, boardId: id, action: "delete", actorId: actor?.actorId ?? null });
           return send(res, 200, { ok: true, id });
         }
 
@@ -648,23 +1221,37 @@ function contentApiPlugin(): Plugin {
         }
 
         if (route === "/__api/asset" && method === "POST") {
-          const { rootId, name, base64 } = JSON.parse(await readBody(req));
+          const { rootId, name, base64, mimeType } = JSON.parse(await readBody(req));
           const resolved = await resolveRoot(String(rootId ?? ""));
           if (!resolved) return send(res, 404, { error: "Docs root not found" });
-          const ext = (path.extname(String(name ?? "")) || ".png").toLowerCase();
-          const safeBase = String(name ?? "image")
-            .replace(/\.[^.]*$/, "")
-            .replace(/[^a-z0-9-_]/gi, "-")
-            .slice(0, 40);
-          const unique = `${safeBase || "image"}-${Date.now().toString(36)}${ext}`;
-          const rel = `assets/${unique}`;
+          const bytes = Buffer.from(String(base64), "base64");
+          const ext = MIME_EXT[String(mimeType ?? "")] ?? (path.extname(String(name ?? "")) || ".png").toLowerCase();
+          const digest = createHash("sha256").update(bytes).digest("hex");
+          const rel = `assets/${digest}${ext}`;
           const abs = safeResolve(resolved.root.absPath, rel);
           if (!abs) return send(res, 400, { error: "Invalid path" });
           await fs.mkdir(path.dirname(abs), { recursive: true });
-          await fs.writeFile(abs, Buffer.from(String(base64), "base64"));
+          try {
+            await fs.access(abs);
+          } catch {
+            await fs.writeFile(abs, bytes);
+          }
+          broadcast("asset-changed", { rootId: resolved.root.id, path: rel, action: "write", actorId: actor?.actorId ?? null });
           return send(res, 200, { ok: true, path: rel });
         }
 
+        if (route === "/__api/asset/cleanup" && method === "POST") {
+          const { rootId, preservePaths } = JSON.parse(await readBody(req));
+          const resolved = await resolveRoot(String(rootId ?? ""));
+          if (!resolved) return send(res, 404, { error: "Docs root not found" });
+          const removed = await cleanupManagedAssets(
+            resolved.root.absPath,
+            Array.isArray(preservePaths) ? preservePaths.filter((item): item is string => typeof item === "string") : []
+          );
+          if (removed > 0) broadcast("asset-changed", { rootId: resolved.root.id, action: "cleanup", removed, actorId: actor?.actorId ?? null });
+          return send(res, 200, { ok: true, removed });
+        }
+
         if (route === "/__api/workspace-file" && method === "GET") {
           await ensureWorkspaceDir();
           const manifest = await loadManifest();