collabmd 0.1.20 → 0.1.21

package/src/client/infrastructure/workspace-sync-client.js

@@ -0,0 +1,324 @@
+import { WebsocketProvider } from 'y-websocket';
+import * as Y from 'yjs';
+
+import { normalizeWorkspaceEvent } from '../../domain/workspace-change.js';
+import { WORKSPACE_ROOM_NAME } from '../../domain/workspace-room.js';
+import { resolveWsBaseUrl } from '../domain/runtime-paths.js';
+import { stopReconnectOnControlledClose } from './yjs-provider-reset-guard.js';
+
+function createNode(entry) {
+  if (!entry?.path || !entry?.type) {
+    return null;
+  }
+
+  if (entry.nodeType === 'directory' || entry.type === 'directory') {
+    return {
+      children: [],
+      name: entry.name,
+      path: entry.path,
+      type: 'directory',
+    };
+  }
+
+  return {
+    name: entry.name,
+    path: entry.path,
+    type: entry.type,
+  };
+}
+
+function sortNodes(nodes = []) {
+  nodes.sort((left, right) => {
+    if (left.type === 'directory' && right.type !== 'directory') return -1;
+    if (left.type !== 'directory' && right.type === 'directory') return 1;
+    return left.name.localeCompare(right.name, undefined, { sensitivity: 'base' });
+  });
+
+  nodes.forEach((node) => {
+    if (Array.isArray(node.children)) {
+      sortNodes(node.children);
+    }
+  });
+
+  return nodes;
+}
+
+function toEntryMap(value) {
+  if (value instanceof Map) {
+    return value;
+  }
+
+  return new Map(Object.entries(value ?? {}));
+}
+
+function sortPathsByDepth(values = [], direction = 'asc') {
+  const factor = direction === 'desc' ? -1 : 1;
+  return [...values].sort((left, right) => {
+    const depthDelta = left.split('/').length - right.split('/').length;
+    if (depthDelta !== 0) {
+      return depthDelta * factor;
+    }
+
+    return left.localeCompare(right, undefined, { sensitivity: 'base' }) * factor;
+  });
+}
+
+class WorkspaceTreeModel {
+  constructor() {
+    this.entriesByPath = new Map();
+    this.nodesByPath = new Map();
+    this.nodeParentPathByPath = new Map();
+    this.roots = [];
+  }
+
+  reset(rawEntries) {
+    this.entriesByPath = toEntryMap(rawEntries);
+    this.nodesByPath = new Map();
+    this.nodeParentPathByPath = new Map();
+    this.roots = [];
+
+    this.entriesByPath.forEach((entry) => {
+      const node = createNode(entry);
+      if (node) {
+        this.nodesByPath.set(entry.path, node);
+      }
+    });
+
+    sortPathsByDepth(Array.from(this.nodesByPath.keys())).forEach((pathValue) => {
+      const node = this.nodesByPath.get(pathValue);
+      if (node) {
+        this.attachNode(pathValue, node, this.entriesByPath.get(pathValue)?.parentPath || '');
+      }
+    });
+
+    sortNodes(this.roots);
+    return this.roots;
+  }
+
+  getTree() {
+    return this.roots;
+  }
+
+  applyMapChanges(changes, entriesMap) {
+    const deletePaths = [];
+    const upsertPaths = [];
+
+    changes.forEach((change, pathValue) => {
+      if (change.action === 'delete') {
+        deletePaths.push(pathValue);
+      } else {
+        upsertPaths.push(pathValue);
+      }
+    });
+
+    sortPathsByDepth(deletePaths, 'desc').forEach((pathValue) => {
+      this.removeEntry(pathValue);
+    });
+
+    sortPathsByDepth(upsertPaths).forEach((pathValue) => {
+      this.upsertEntry(pathValue, entriesMap.get(pathValue));
+    });
+
+    sortNodes(this.roots);
+    return this.roots;
+  }
+
+  removeEntry(pathValue) {
+    const node = this.nodesByPath.get(pathValue);
+    if (!node) {
+      this.entriesByPath.delete(pathValue);
+      this.nodeParentPathByPath.delete(pathValue);
+      return;
+    }
+
+    this.detachNode(pathValue, node);
+    this.nodesByPath.delete(pathValue);
+    this.entriesByPath.delete(pathValue);
+    this.nodeParentPathByPath.delete(pathValue);
+  }
+
+  upsertEntry(pathValue, entry) {
+    if (!entry?.path || !entry?.type) {
+      this.removeEntry(pathValue);
+      return;
+    }
+
+    const nextNode = createNode(entry);
+    if (!nextNode) {
+      this.removeEntry(pathValue);
+      return;
+    }
+
+    const existingNode = this.nodesByPath.get(pathValue);
+    let node = existingNode;
+    if (!node || (node.type === 'directory') !== (nextNode.type === 'directory')) {
+      if (node) {
+        this.detachNode(pathValue, node);
+      }
+      node = nextNode;
+      this.nodesByPath.set(pathValue, node);
+    } else {
+      node.name = nextNode.name;
+      node.path = nextNode.path;
+      node.type = nextNode.type;
+      if (node.type === 'directory' && !Array.isArray(node.children)) {
+        node.children = [];
+      }
+      if (node.type !== 'directory' && Array.isArray(node.children)) {
+        delete node.children;
+      }
+    }
+
+    this.entriesByPath.set(pathValue, entry);
+    this.attachNode(pathValue, node, entry.parentPath || '');
+
+    if (node.type === 'directory') {
+      this.rehomeChildren(pathValue);
+    }
+  }
+
+  detachNode(pathValue, node) {
+    const currentParentPath = this.nodeParentPathByPath.get(pathValue) || '';
+    const siblings = currentParentPath
+      ? this.nodesByPath.get(currentParentPath)?.children
+      : this.roots;
+    const index = siblings?.indexOf?.(node) ?? -1;
+    if (index >= 0) {
+      siblings.splice(index, 1);
+    }
+    this.nodeParentPathByPath.delete(pathValue);
+  }
+
+  attachNode(pathValue, node, requestedParentPath = '') {
+    const parentPath = this.nodesByPath.get(requestedParentPath)?.type === 'directory'
+      ? requestedParentPath
+      : '';
+    const currentParentPath = this.nodeParentPathByPath.get(pathValue);
+
+    if (currentParentPath === parentPath) {
+      return;
+    }
+
+    if (currentParentPath !== undefined) {
+      this.detachNode(pathValue, node);
+    }
+
+    const siblings = parentPath
+      ? this.nodesByPath.get(parentPath)?.children
+      : this.roots;
+    if (!siblings.includes(node)) {
+      siblings.push(node);
+    }
+    this.nodeParentPathByPath.set(pathValue, parentPath);
+  }
+
+  rehomeChildren(parentPath) {
+    this.entriesByPath.forEach((entry, pathValue) => {
+      if (entry?.parentPath !== parentPath) {
+        return;
+      }
+
+      const node = this.nodesByPath.get(pathValue);
+      if (node) {
+        this.attachNode(pathValue, node, parentPath);
+      }
+    });
+  }
+}
+
+export class WorkspaceSyncClient {
+  constructor({
+    onTreeChange = () => {},
+    onWorkspaceEvent = () => {},
+  } = {}) {
+    this.onTreeChange = onTreeChange;
+    this.onWorkspaceEvent = onWorkspaceEvent;
+    this.ydoc = new Y.Doc();
+    this.entries = this.ydoc.getMap('entries');
+    this.events = this.ydoc.getArray('events');
+    this.provider = null;
+    this._didInitialSync = false;
+    this.seenEventIds = new Set();
+    this.treeModel = new WorkspaceTreeModel();
+
+    this.handleEntriesChange = (event) => {
+      if (!this._didInitialSync || !event) {
+        return;
+      }
+
+      this.onTreeChange(this.treeModel.applyMapChanges(event.changes.keys, this.entries), {
+        changedPaths: Array.from(event.changes.keys.keys()),
+        reset: false,
+      });
+    };
+    this.handleEventsChange = () => {
+      if (!this._didInitialSync) {
+        this.primeEventCache();
+        return;
+      }
+
+      this.events.toArray().forEach((event) => {
+        const normalized = normalizeWorkspaceEvent(event);
+        if (!normalized || this.seenEventIds.has(normalized.id)) {
+          return;
+        }
+
+        this.seenEventIds.add(normalized.id);
+        this.onWorkspaceEvent(normalized);
+      });
+    };
+  }
+
+  connect() {
+    if (this.provider) {
+      return;
+    }
+
+    this._didInitialSync = false;
+    this.provider = new WebsocketProvider(resolveWsBaseUrl(), WORKSPACE_ROOM_NAME, this.ydoc, {
+      disableBc: true,
+      maxBackoffTime: 5000,
+    });
+    stopReconnectOnControlledClose(this.provider);
+
+    this.entries.observe(this.handleEntriesChange);
+    this.events.observe(this.handleEventsChange);
+    this.provider.on('sync', (isSynced) => {
+      if (!isSynced || this._didInitialSync) {
+        return;
+      }
+
+      this._didInitialSync = true;
+      this.primeEventCache();
+      this.onTreeChange(this.treeModel.reset(this.entries.toJSON()), {
+        changedPaths: [],
+        reset: true,
+      });
+    });
+  }
+
+  primeEventCache() {
+    this.events.toArray().forEach((event) => {
+      const normalized = normalizeWorkspaceEvent(event);
+      if (normalized) {
+        this.seenEventIds.add(normalized.id);
+      }
+    });
+  }
+
+  disconnect() {
+    this.entries.unobserve(this.handleEntriesChange);
+    this.events.unobserve(this.handleEventsChange);
+    this.provider?.disconnect();
+    this.provider?.destroy();
+    this.provider = null;
+    this._didInitialSync = false;
+    this.seenEventIds.clear();
+    this.treeModel.reset(new Map());
+  }
+
+  destroy() {
+    this.disconnect();
+    this.ydoc.destroy();
+  }
+}

package/src/client/presentation/comment-ui-controller.js

@@ -9,6 +9,9 @@ const COMMENT_CARD_WIDTH = 520;
 const COMMENT_SELECTION_REVEAL_DELAY_MS = 150;
 const COMMENT_SELECTION_CHIP_GAP = 12;
 const COMMENT_CONTROL_SLOT_HEIGHT = 36;
+const COMMENT_PREVIEW_RAIL_SLOT_HEIGHT = 30;
+const COMMENT_PREVIEW_RAIL_MIN_WIDTH = 400;
+const COMMENT_PREVIEW_RAIL_BREAKPOINT = 769;
 const COMMENT_REACTION_PRESET_EMOJIS = Object.freeze(['👍', '❤️', '🎉', '👀', '🚀']);
 const COMMENT_REACTION_MORE_EMOJIS = Object.freeze(['😂', '🔥', '✅', '🙏', '💡', '🤔', '👏', '😄', '🎯', '🙌']);
 
@@ -248,6 +251,25 @@ function createRectFromRects(rects = []) {
   };
 }
 
+function pointIntersectsRect(x, y, rect) {
+  if (!rect) {
+    return false;
+  }
+
+  return x >= rect.left
+    && x <= rect.right
+    && y >= rect.top
+    && y <= rect.bottom;
+}
+
+function normalizeGroupKeys(keys = []) {
+  return [...new Set(keys.filter(Boolean))].sort();
+}
+
+function serializeGroupKeys(keys = []) {
+  return normalizeGroupKeys(keys).join(' ');
+}
+
 function createCommentMarkerContent(count) {
   const fragment = document.createDocumentFragment();
 
@@ -315,6 +337,12 @@ export class CommentUiController {
     this.pointerSelecting = false;
     this.session = null;
     this.activeCard = null;
+    this.hoveredEditorGroupKeys = [];
+    this.hoveredEditorGroupKeysSignature = '';
+    this.hoveredPreviewGroupKeys = [];
+    this.hoveredPreviewGroupKeysSignature = '';
+    this.previewHoverRegions = [];
+    this.lastPreviewPointerPosition = null;
     this.editorLayer = null;
     this.previewLayer = null;
     this.previewHighlightLayer = null;
@@ -331,6 +359,20 @@ export class CommentUiController {
     this.handleEditorScroll = () => this.scheduleLayoutRefresh();
     this.handlePreviewScroll = () => this.scheduleLayoutRefresh();
     this.handleWindowResize = () => this.scheduleLayoutRefresh();
+    this.handlePreviewPointerMove = (event) => {
+      this.lastPreviewPointerPosition = { x: event.clientX, y: event.clientY };
+      this.updateHoveredPreviewGroups(this.getPreviewGroupKeysAtPoint(event.clientX, event.clientY));
+    };
+    this.handlePreviewPointerLeave = () => {
+      this.lastPreviewPointerPosition = null;
+      this.updateHoveredPreviewGroups([]);
+    };
+    this.handlePreviewFocusIn = (event) => {
+      this.updateHoveredPreviewGroups(this.getPreviewGroupKeysForTarget(event.target));
+    };
+    this.handlePreviewFocusOut = (event) => {
+      this.updateHoveredPreviewGroups(this.getPreviewGroupKeysForTarget(event.relatedTarget));
+    };
     this.handleCommentSelectionButtonPointerDown = (event) => {
       event.preventDefault();
     };
@@ -436,6 +478,10 @@ export class CommentUiController {
       this.setDrawerOpen(!this.drawerOpen);
     });
     this.previewContainer?.addEventListener('scroll', this.handlePreviewScroll, { passive: true });
+    this.previewElement?.addEventListener('pointermove', this.handlePreviewPointerMove, { passive: true });
+    this.previewElement?.addEventListener('pointerleave', this.handlePreviewPointerLeave);
+    this.previewElement?.addEventListener('focusin', this.handlePreviewFocusIn);
+    this.previewElement?.addEventListener('focusout', this.handlePreviewFocusOut);
     this.editorContainer?.addEventListener('pointerdown', this.handleEditorPointerDown);
     this.editorContainer?.addEventListener('focusout', this.handleEditorFocusOut);
     window.addEventListener('resize', this.handleWindowResize);
@@ -452,6 +498,10 @@ export class CommentUiController {
     }
     this.attachSession(null);
     this.previewContainer?.removeEventListener('scroll', this.handlePreviewScroll);
+    this.previewElement?.removeEventListener('pointermove', this.handlePreviewPointerMove);
+    this.previewElement?.removeEventListener('pointerleave', this.handlePreviewPointerLeave);
+    this.previewElement?.removeEventListener('focusin', this.handlePreviewFocusIn);
+    this.previewElement?.removeEventListener('focusout', this.handlePreviewFocusOut);
     this.commentSelectionButton?.removeEventListener('pointerdown', this.handleCommentSelectionButtonPointerDown);
     this.editorContainer?.removeEventListener('pointerdown', this.handleEditorPointerDown);
     this.editorContainer?.removeEventListener('focusout', this.handleEditorFocusOut);
@@ -460,6 +510,7 @@ export class CommentUiController {
     document.removeEventListener('pointercancel', this.handleDocumentPointerUp);
     document.removeEventListener('pointerdown', this.handleDocumentPointerDown);
     document.removeEventListener('keydown', this.handleDocumentKeyDown);
+    this.previewHoverRegions = [];
     this.cardRoot?.remove();
     this.editorLayer?.remove();
     this.previewLayer?.remove();
@@ -493,6 +544,10 @@ export class CommentUiController {
       this.clearSelectionRevealTimer();
       this.pointerSelecting = false;
       this.activeCard = null;
+      this.updateHoveredEditorGroups([]);
+      this.updateHoveredPreviewGroups([]);
+      this.previewHoverRegions = [];
+      this.lastPreviewPointerPosition = null;
       this.reactionPicker = null;
     }
     if (!this.supported) {
@@ -504,6 +559,10 @@ export class CommentUiController {
       this.committedSelectionAnchor = null;
       this.clearSelectionRevealTimer();
       this.pointerSelecting = false;
+      this.updateHoveredEditorGroups([]);
+      this.updateHoveredPreviewGroups([]);
+      this.previewHoverRegions = [];
+      this.lastPreviewPointerPosition = null;
       this.reactionPicker = null;
     }
     this.render();
@@ -757,11 +816,19 @@ export class CommentUiController {
       }
 
       const relativeRect = toRelativeRect(rect, containerRect);
+      if (relativeRect.bottom < 0 || relativeRect.top > containerRect.height) {
+        return;
+      }
+
       const button = document.createElement('button');
       button.type = 'button';
       button.className = 'comment-editor-badge';
       button.dataset.count = String(group.threads.length);
-      button.classList.toggle('is-active', this.activeCard?.groupKey === group.key);
+      const isActive = this.activeCard?.groupKey === group.key;
+      const isHovered = this.hoveredEditorGroupKeys.includes(group.key);
+      button.classList.toggle('is-active', isActive);
+      button.classList.toggle('is-hovered', isHovered);
+      button.classList.toggle('is-passive', !isActive && !isHovered);
       button.setAttribute('aria-label', `${group.threads.length} comment thread${group.threads.length === 1 ? '' : 's'}`);
       button.appendChild(createCommentMarkerContent(group.threads.length));
       const top = Math.max(relativeRect.top, 8);
@@ -771,6 +838,18 @@ export class CommentUiController {
       button.addEventListener('pointerdown', (event) => {
         event.preventDefault();
       });
+      button.addEventListener('pointerenter', () => {
+        this.updateHoveredEditorGroups([group.key]);
+      });
+      button.addEventListener('pointerleave', () => {
+        this.updateHoveredEditorGroups([]);
+      });
+      button.addEventListener('focusin', () => {
+        this.updateHoveredEditorGroups([group.key]);
+      });
+      button.addEventListener('focusout', () => {
+        this.updateHoveredEditorGroups([]);
+      });
       button.addEventListener('click', () => {
         this.openThreadGroup(group, {
           anchor: group.anchor,
@@ -840,20 +919,36 @@ export class CommentUiController {
     this.previewHighlightLayer?.replaceChildren();
 
     if (!this.supported || !this.previewElement) {
+      this.previewHoverRegions = [];
       return;
     }
 
     const previewRect = this.previewElement.getBoundingClientRect();
     const groups = this.getThreadGroups();
+    const occupiedTops = [];
+    const hoverRegions = [];
+    const showPassiveMarkers = this.shouldRenderPassivePreviewMarkers();
     groups.forEach((group) => {
       const target = this.resolvePreviewTarget(group.anchor);
       if (!target?.bubbleRect) {
         return;
       }
 
+      hoverRegions.push({
+        key: group.key,
+        rects: target.hoverRects?.length > 0 ? target.hoverRects : [target.bubbleRect],
+      });
+
+      const isActive = this.activeCard?.groupKey === group.key;
+      const isHovered = this.hoveredPreviewGroupKeys.includes(group.key);
+      const isEmphasized = isActive || isHovered;
+
       target.highlightRects?.forEach((rect) => {
         const highlight = document.createElement('div');
         highlight.className = 'comment-preview-highlight';
+        highlight.classList.toggle('is-active', isActive);
+        highlight.classList.toggle('is-hovered', isHovered);
+        highlight.classList.toggle('is-passive', !isEmphasized);
         highlight.style.left = `${rect.left - previewRect.left}px`;
         highlight.style.top = `${rect.top - previewRect.top}px`;
         highlight.style.width = `${rect.width}px`;
@@ -861,14 +956,32 @@ export class CommentUiController {
         this.previewHighlightLayer?.appendChild(highlight);
       });
 
+      if (!showPassiveMarkers && !isEmphasized) {
+        return;
+      }
+
       const bubble = document.createElement('button');
       bubble.type = 'button';
       bubble.className = 'comment-preview-badge';
-      bubble.classList.toggle('is-active', this.activeCard?.groupKey === group.key);
+      bubble.dataset.commentPreviewGroupKeys = group.key;
+      bubble.classList.toggle('is-active', isActive);
+      bubble.classList.toggle('is-hovered', isHovered);
+      bubble.classList.toggle('is-passive', !isEmphasized);
       bubble.setAttribute('aria-label', `${group.threads.length} comment thread${group.threads.length === 1 ? '' : 's'}`);
       bubble.appendChild(createCommentMarkerContent(group.threads.length));
-      bubble.style.left = `${clamp(target.bubbleRect.right - previewRect.left + 6, 6, this.previewElement.clientWidth - 34)}px`;
-      bubble.style.top = `${Math.max(target.bubbleRect.top - previewRect.top, 6)}px`;
+      let bubbleTop = clamp(
+        target.bubbleRect.top - previewRect.top,
+        6,
+        Math.max(this.previewElement.clientHeight - COMMENT_PREVIEW_RAIL_SLOT_HEIGHT, 6),
+      );
+      while (occupiedTops.some((top) => Math.abs(top - bubbleTop) < (COMMENT_PREVIEW_RAIL_SLOT_HEIGHT - 4))) {
+        bubbleTop = clamp(
+          bubbleTop + COMMENT_PREVIEW_RAIL_SLOT_HEIGHT,
+          6,
+          Math.max(this.previewElement.clientHeight - COMMENT_PREVIEW_RAIL_SLOT_HEIGHT, 6),
+        );
+      }
+      bubble.style.top = `${bubbleTop}px`;
       bubble.title = `${group.threads.length} comment${group.threads.length === 1 ? '' : 's'}`;
       bubble.addEventListener('pointerdown', (event) => {
         event.preventDefault();
@@ -877,11 +990,19 @@ export class CommentUiController {
         this.openThreadGroup(group, {
           anchor: group.anchor,
           origin: 'preview',
-          sourceRect: target.bubbleRect,
+          sourceRect: bubble.getBoundingClientRect(),
         });
       });
       this.previewLayer?.appendChild(bubble);
+      occupiedTops.push(bubbleTop);
     });
+
+    this.previewHoverRegions = hoverRegions;
+    if (this.lastPreviewPointerPosition) {
+      this.updateHoveredPreviewGroups(
+        this.getPreviewGroupKeysAtPoint(this.lastPreviewPointerPosition.x, this.lastPreviewPointerPosition.y),
+      );
+    }
   }
 
   resolvePreviewTarget(anchor) {
@@ -895,6 +1016,7 @@ export class CommentUiController {
       return {
         bubbleRect: diagramShell.getBoundingClientRect(),
         highlightRects: [],
+        hoverRects: [diagramShell.getBoundingClientRect()],
       };
     }
 
@@ -911,6 +1033,7 @@ export class CommentUiController {
         return {
           bubbleRect,
           highlightRects: rects,
+          hoverRects: rects,
         };
       }
     }
@@ -923,6 +1046,7 @@ export class CommentUiController {
     return {
       bubbleRect: fallback.getBoundingClientRect(),
       highlightRects: [],
+      hoverRects: [fallback.getBoundingClientRect()],
     };
   }
 
@@ -1115,6 +1239,69 @@ export class CommentUiController {
     this.scheduleLayoutRefresh();
   }
 
+  getPreviewGroupKeysForTarget(target) {
+    if (!(target instanceof Node)) {
+      return [];
+    }
+
+    const keyCarrier = target.closest?.('[data-comment-preview-group-keys]');
+    return serializeGroupKeys(
+      String(keyCarrier?.dataset?.commentPreviewGroupKeys ?? '')
+        .split(/\s+/)
+        .filter(Boolean),
+    ).split(' ').filter(Boolean);
+  }
+
+  getPreviewGroupKeysAtPoint(x, y) {
+    if (!Number.isFinite(x) || !Number.isFinite(y)) {
+      return [];
+    }
+
+    const targetAtPoint = document.elementFromPoint(x, y);
+    const targetKeys = this.getPreviewGroupKeysForTarget(targetAtPoint);
+    if (targetKeys.length > 0) {
+      return targetKeys;
+    }
+
+    const matchingKeys = this.previewHoverRegions
+      .filter((region) => region.rects.some((rect) => pointIntersectsRect(x, y, rect)))
+      .map((region) => region.key);
+    return normalizeGroupKeys(matchingKeys);
+  }
+
+  updateHoveredPreviewGroups(nextKeys = []) {
+    const normalizedKeys = normalizeGroupKeys(nextKeys);
+    const signature = normalizedKeys.join(' ');
+    if (signature === this.hoveredPreviewGroupKeysSignature) {
+      return;
+    }
+
+    this.hoveredPreviewGroupKeys = normalizedKeys;
+    this.hoveredPreviewGroupKeysSignature = signature;
+    this.scheduleLayoutRefresh();
+  }
+
+  updateHoveredEditorGroups(nextKeys = []) {
+    const normalizedKeys = normalizeGroupKeys(nextKeys);
+    const signature = normalizedKeys.join(' ');
+    if (signature === this.hoveredEditorGroupKeysSignature) {
+      return;
+    }
+
+    this.hoveredEditorGroupKeys = normalizedKeys;
+    this.hoveredEditorGroupKeysSignature = signature;
+    this.scheduleLayoutRefresh();
+  }
+
+  syncHoveredPreviewGroupsFromTarget(target) {
+    this.updateHoveredPreviewGroups(this.getPreviewGroupKeysForTarget(target));
+  }
+
+  shouldRenderPassivePreviewMarkers() {
+    const previewWidth = this.previewContainer?.clientWidth ?? this.previewElement?.clientWidth ?? 0;
+    return window.innerWidth >= COMMENT_PREVIEW_RAIL_BREAKPOINT && previewWidth >= COMMENT_PREVIEW_RAIL_MIN_WIDTH;
+  }
+
   updateReactionPickerPosition(card) {
     const bounds = getReactionPickerBounds(card);
     if (!bounds) {

package/src/client/presentation/file-explorer-controller.js

@@ -54,13 +54,20 @@ export class FileExplorerController {
   async refresh() {
     try {
       const data = await this.vaultClient.readTree();
-      this.state.setTree(data.tree || []);
-      this.renderTree();
+      this.setTree(data.tree || []);
     } catch (error) {
       console.error('[explorer] Failed to load file tree:', error.message);
     }
   }
 
+  setTree(tree, {
+    changedPaths = null,
+    reset = false,
+  } = {}) {
+    this.state.setTree(tree);
+    this.renderTree({ changedPaths, reset });
+  }
+
   setActiveFile(filePath) {
     this.state.setActiveFile(filePath);
     this.renderTree();
@@ -74,10 +81,15 @@ export class FileExplorerController {
     return this.state.flatFiles.filter((path) => !isImageAttachmentFilePath(path));
   }
 
-  renderTree() {
+  renderTree({
+    changedPaths = null,
+    reset = false,
+  } = {}) {
     this.view.render({
       activeFilePath: this.state.activeFilePath,
+      changedPaths,
       expandedDirs: this.state.expandedDirs,
+      reset,
       searchMatches: this.state.getSearchMatches(),
       searchQuery: this.state.searchQuery,
       tree: this.state.tree,