viteboard 0.1.0

package/src/shell/Sidebar.ts

@@ -0,0 +1,1352 @@
+import {
+  type DocsRootSummary,
+  type TreeNode,
+  type WorkspaceProject,
+  type WorkspaceState,
+} from "../content/ContentApi";
+import { boardIdFromFilePath } from "../board/BoardService";
+
+// Directories that are never shown as doc tree nodes.
+const SPECIAL_DIRS = new Set(["capabilities", "assets"]);
+
+export type SidebarCallbacks = {
+  onAddRepo: () => void;
+  onRemoveProject: (projectId: string, label: string) => void;
+  // --- create ---
+  onCreateDirectory: (rootId: string, dirPath: string) => void;
+  onCreateDoc: (rootId: string, dirPath: string) => void;
+  onCreateBoard: (rootId: string, dirPath: string) => void;
+  onCreateCapability: (rootId: string, dirPath: string) => void;
+  onCreateDocsFolder: (projectId: string, parentPath: string) => void;
+  onCreateProjectDirectory: (projectId: string) => void;
+  onCreateProjectDoc: (projectId: string) => void;
+  onCreateProjectBoard: (projectId: string) => void;
+  // --- directory ---
+  onRenameDirectory: (rootId: string, dirPath: string) => void;
+  onDeleteDirectory: (rootId: string, dirPath: string) => void;
+  // --- doc file ---
+  onOpenDoc: (rootId: string, filePath: string) => void;
+  onEditDoc: (rootId: string, filePath: string) => void;
+  onRenameDoc: (rootId: string, filePath: string) => void;
+  onDeleteDoc: (rootId: string, filePath: string) => void;
+  // --- board file ---
+  onOpenBoard: (rootId: string, boardId: string) => void;
+  onRenameBoard: (rootId: string, boardId: string) => void;
+  onDeleteBoard: (rootId: string, boardId: string) => void;
+  // --- drag/drop move ---
+  onMoveDoc: (rootId: string, filePath: string, targetDir: string) => void;
+  onMoveBoard: (rootId: string, boardId: string, targetDir: string) => void;
+  onMoveDirectory: (rootId: string, dirPath: string, targetDir: string) => void;
+};
+
+type SidebarDragItem =
+  | { kind: "doc"; rootId: string; path: string }
+  | { kind: "board"; rootId: string; boardId: string }
+  | { kind: "dir"; rootId: string; path: string };
+
+// ---------------------------------------------------------------------------
+// Path-segment tree used to group docs roots into a nested hierarchy.
+// ---------------------------------------------------------------------------
+type PathNode =
+  | { kind: "root"; root: DocsRootSummary }
+  | { kind: "dir"; segment: string; children: PathNode[] };
+
+function buildPathTree(roots: DocsRootSummary[]): PathNode[] {
+  const children: PathNode[] = [];
+
+  function insert(nodes: PathNode[], segments: string[], root: DocsRootSummary): void {
+    if (segments.length === 0) return;
+    if (segments.length === 1) {
+      nodes.push({ kind: "root", root });
+      return;
+    }
+    const [head, ...rest] = segments;
+    let dir = nodes.find(
+      (n): n is PathNode & { kind: "dir" } => n.kind === "dir" && n.segment === head
+    );
+    if (!dir) {
+      dir = { kind: "dir", segment: head, children: [] };
+      nodes.push(dir);
+    }
+    insert(dir.children, rest, root);
+  }
+
+  for (const root of roots) {
+    const segments = root.displayPath.split("/").filter(Boolean);
+    insert(children, segments, root);
+  }
+
+  // Collapse single-child dir chains (e.g. frontend → src → merges to frontend/src).
+  function collapse(nodes: PathNode[]): PathNode[] {
+    return nodes.map((node) => {
+      if (node.kind === "root") return node;
+      const kids = collapse(node.children);
+      if (kids.length === 1 && kids[0].kind === "dir") {
+        const only = kids[0] as PathNode & { kind: "dir" };
+        return { kind: "dir" as const, segment: `${node.segment}/${only.segment}`, children: only.children };
+      }
+      return { ...node, children: kids };
+    });
+  }
+
+  return collapse(children);
+}
+
+// ---------------------------------------------------------------------------
+// A record of every collapsible section built during render, so we can
+// expand the ancestors of the active item without re-rendering.
+// ---------------------------------------------------------------------------
+export type CollapsibleRecord = {
+  body: HTMLElement;
+  group: HTMLElement;
+  btn: HTMLButtonElement;
+};
+
+// ---------------------------------------------------------------------------
+
+export class Sidebar {
+  readonly element: HTMLElement;
+  private header: HTMLElement;
+  private nav: HTMLElement;
+  private footer: HTMLElement;
+
+  /** href / key → anchor — accessible for inline editing lookups */
+  readonly links = new Map<string, HTMLAnchorElement>();
+  /** key → collapsible DOM record — built fresh each refresh() */
+  readonly collapsibles = new Map<string, CollapsibleRecord>();
+  /** key → collapsed state, preserved across refreshes and route changes */
+  private collapsedState = new Map<string, boolean>();
+
+  private callbacks: SidebarCallbacks;
+  private contextMenu?: HTMLElement;
+  private draggedItem?: SidebarDragItem;
+
+  /** Last full workspace state — kept so we can re-render on mode toggle. */
+  private lastWorkspace: WorkspaceState = { projects: [] };
+  private lastTreesByRoot = new Map<string, TreeNode[]>();
+  private lastTreesByProject = new Map<string, TreeNode[]>();
+  /** Track which projects have "browse mode" enabled (shows full filesystem) */
+  private browseModeProjects = new Set<string>();
+
+  constructor(parent: HTMLElement, callbacks: SidebarCallbacks) {
+    this.callbacks = callbacks;
+    this.element = document.createElement("aside");
+    this.element.className = "sidebar";
+
+    this.header = document.createElement("div");
+    this.header.className = "sidebar-header";
+    const brand = document.createElement("a");
+    brand.className = "sidebar-brand";
+    brand.href = "#/";
+    brand.textContent = "ViteBoard";
+    this.header.appendChild(brand);
+
+    this.nav = document.createElement("nav");
+    this.nav.className = "sidebar-nav";
+
+    this.footer = document.createElement("div");
+    this.footer.className = "sidebar-footer";
+    const addRepo = document.createElement("button");
+    addRepo.className = "sidebar-add-repo";
+    addRepo.type = "button";
+    addRepo.textContent = "Add Repo";
+    addRepo.title = "Add a local project root";
+    addRepo.addEventListener("click", () => this.callbacks.onAddRepo());
+    this.footer.appendChild(addRepo);
+
+    this.element.append(this.header, this.nav, this.footer);
+    parent.appendChild(this.element);
+
+    document.addEventListener(
+      "pointerdown",
+      (e) => {
+        if (!this.contextMenu) return;
+        if (this.contextMenu.contains(e.target as Node)) return;
+        this.closeContextMenu();
+      },
+      true
+    );
+  }
+
+  // ---------- Public API ----------
+
+  refresh(workspace: WorkspaceState, treesByRoot: Map<string, TreeNode[]>, treesByProject?: Map<string, TreeNode[]>): void {
+    this.lastWorkspace = workspace;
+    this.lastTreesByRoot = treesByRoot;
+    if (treesByProject) {
+      this.lastTreesByProject = treesByProject;
+    }
+    this.render();
+  }
+
+  private render(): void {
+    const workspace = this.lastWorkspace;
+    const treesByRoot = this.lastTreesByRoot;
+    const treesByProject = this.lastTreesByProject;
+
+    this.nav.replaceChildren();
+    this.links.clear();
+    this.collapsibles.clear();
+
+    if (workspace.projects.length === 0) {
+      const empty = document.createElement("div");
+      empty.className = "nav-group";
+      empty.appendChild(this.groupLabel("Workspace"));
+      const note = document.createElement("div");
+      note.className = "nav-label nav-empty-copy";
+      note.textContent = "Add a project root to discover docs folders.";
+      empty.appendChild(note);
+      this.nav.appendChild(empty);
+    } else {
+      for (const project of workspace.projects) {
+        this.nav.appendChild(this.projectSection(project, treesByRoot));
+      }
+    }
+
+    const system = document.createElement("div");
+    system.className = "nav-group";
+    system.appendChild(this.groupLabel("System"));
+    system.appendChild(this.link("#/tokens", "Tokens", "tokens-root"));
+    this.nav.appendChild(system);
+
+    this.setActive(location.hash);
+  }
+
+
+
+  /** Exit browse mode for all projects (called after content refresh). */
+  clearBrowseMode(): void {
+    if (this.browseModeProjects.size === 0) return;
+    this.browseModeProjects.clear();
+    this.render();
+  }
+
+  private toggleBrowseMode(projectId: string): void {
+    if (this.browseModeProjects.has(projectId)) {
+      this.browseModeProjects.delete(projectId);
+    } else {
+      this.browseModeProjects.add(projectId);
+    }
+    this.render();
+  }
+
+  setActive(hash: string): void {
+    // 1. Clear previous active state.
+    for (const a of new Set(this.links.values())) a.classList.remove("active");
+
+    const exact = this.links.get(hash);
+    if (exact) {
+      exact.classList.add("active");
+    } else if (hash.startsWith("#/root/")) {
+      const match = hash.match(/^#\/root\/([^/]+)\/(boards|capabilities|docs)(?:\/(.+))?$/);
+      if (match) {
+        const [, encodedRootId, section] = match;
+        const rootId = decodeURIComponent(encodedRootId);
+        if (section === "boards") {
+          this.links.get(rootBoardsHref(rootId))?.classList.add("active");
+        } else if (section === "capabilities") {
+          this.links.get(rootCapabilitiesHref(rootId))?.classList.add("active");
+        }
+      }
+    }
+
+    // 2. Sync tree open/close state to the active route.
+    this.syncCollapsed(hash);
+  }
+
+  /**
+   * Open every collapsible that is an ancestor of the active page, while
+   * preserving the user's existing open/close state elsewhere.
+   */
+  private syncCollapsed(hash: string): void {
+    const open = this.ancestorKeys(hash);
+    for (const key of open) this.applyCollapsed(key, false);
+  }
+
+  /**
+   * Compute the set of collapsible keys that must be open for the given hash
+   * to be visible in the tree.
+   *
+   * Key formats:
+   *   projectId                              — project header
+   *   pathseg:{projectId}:{fullSegment}      — path segment group
+   *   doc:{rootId}:{dirPath}                 — doc directory group
+   */
+  private ancestorKeys(hash: string): Set<string> {
+    const open = new Set<string>();
+
+    const projectMatch = hash.match(/^#\/project\/([^/]+)(?:\/boards)?$/);
+    if (projectMatch) {
+      open.add(decodeURIComponent(projectMatch[1]));
+      return open;
+    }
+
+    const match = hash.match(/^#\/root\/([^/]+)\/(docs|boards|capabilities)(?:\/(.+))?$/);
+    if (!match) return open;
+
+    const rootId = decodeURIComponent(match[1]);
+    const section = match[2];
+    const rest = match[3] ? decodeURIComponent(match[3]) : "";
+
+    // Find which project this root belongs to.
+    let projectId: string | undefined;
+    let displayPath: string | undefined;
+    for (const project of this.lastWorkspace.projects) {
+      const root = project.docsRoots.find(r => r.id === rootId);
+      if (root) {
+        projectId = project.id;
+        displayPath = root.displayPath;
+        break;
+      }
+    }
+    if (!projectId || !displayPath) return open;
+
+    // Project header.
+    open.add(projectId);
+
+    // Path-segment keys: auto-open the filesystem scaffolding leading to /docs/
+    const displayParts = displayPath.split("/").filter(Boolean).slice(0, -1);
+    let acc = "";
+    for (const part of displayParts) {
+      acc = acc ? `${acc}/${part}` : part;
+      const candidate = `pathseg:${projectId}:${acc}`;
+      if (this.collapsibles.has(candidate)) open.add(candidate);
+    }
+
+    // Doc directory keys: every parent dir of the current file path.
+    if (section === "docs" && rest) {
+      const parts = rest.split("/");
+      for (let i = 1; i < parts.length; i++) {
+        const dirPath = parts.slice(0, i).join("/");
+        const key = `doc:${rootId}:${dirPath}`;
+        if (this.collapsibles.has(key)) open.add(key);
+      }
+    }
+
+    return open;
+  }
+
+  // ---------- Project section ----------
+
+  private projectSection(
+    project: WorkspaceProject,
+    treesByRoot: Map<string, TreeNode[]>
+  ): HTMLElement {
+    const { id: projectId, label, docsRoots: roots } = project;
+    const isRaw = this.browseModeProjects.has(projectId);
+
+    const body = document.createElement("div");
+    body.className = "nav-repo-body";
+
+    const group = document.createElement("div");
+    group.className = "nav-group nav-repo-group";
+
+    const header = document.createElement("button");
+    header.className = "nav-repo-header";
+    header.type = "button";
+
+    const chevron = document.createElement("span");
+    chevron.className = "nav-repo-chevron";
+    chevron.textContent = "›";
+    const text = document.createElement("span");
+    text.className = "nav-repo-label-text";
+    text.textContent = label;
+
+    // Three-dot menu button (replaces wiki link + toggle)
+    const moreBtn = document.createElement("button");
+    moreBtn.className = "nav-repo-more";
+    moreBtn.type = "button";
+    moreBtn.title = "Project options";
+    moreBtn.innerHTML = `<svg viewBox="0 0 16 16" width="14" height="14" fill="currentColor"><circle cx="8" cy="3" r="1.3"/><circle cx="8" cy="8" r="1.3"/><circle cx="8" cy="13" r="1.3"/></svg>`;
+    moreBtn.addEventListener("click", (e) => {
+      e.stopPropagation();
+      const rect = moreBtn.getBoundingClientRect();
+      this.showContextMenu(rect.right + 4, rect.top, label, [
+        {
+          icon: isRaw ? DOC_ICON_HTML : DIRECTORY_ICON_HTML,
+          iconClass: isRaw ? "nav-ctx-doc" : "nav-ctx-dir",
+          label: isRaw ? "View: Docs" : "View: Raw",
+          action: () => this.toggleBrowseMode(projectId),
+        },
+        {
+          icon: EDIT_ICON_HTML, iconClass: "nav-ctx-edit", label: "Wiki",
+          action: () => { location.hash = `#/project/${encodeURIComponent(projectId)}`; },
+        },
+        { kind: "divider" as const },
+        {
+          icon: DOC_ICON_HTML, iconClass: "nav-ctx-doc", label: "New Doc",
+          action: () => this.callbacks.onCreateProjectDoc(projectId),
+        },
+        {
+          icon: BOARD_ICON_HTML, iconClass: "nav-ctx-board", label: "New Board",
+          action: () => this.callbacks.onCreateProjectBoard(projectId),
+        },
+        {
+          icon: DIRECTORY_ICON_HTML, iconClass: "nav-ctx-dir", label: "New Directory",
+          action: () => this.callbacks.onCreateProjectDirectory(projectId),
+        },
+        { kind: "divider" as const },
+        {
+          icon: TRASH_ICON_HTML, iconClass: "nav-ctx-delete", label: "Remove from workspace",
+          action: () => this.callbacks.onRemoveProject(projectId, label),
+          danger: true,
+        },
+      ]);
+    });
+
+    header.append(chevron, text, moreBtn);
+
+    this.registerCollapsible(projectId, body, group, header as HTMLButtonElement, true);
+    header.addEventListener("click", () => this.toggleCollapsible(projectId));
+
+    // Right-click on header itself opens same menu
+    header.addEventListener("contextmenu", (e) => {
+      e.preventDefault();
+      e.stopPropagation();
+      moreBtn.click();
+    });
+
+    const projectDropRoot = roots[0];
+    if (projectDropRoot) this.enableDirectoryDropTarget(header, projectDropRoot.id, "");
+
+    // ── Render tree: one unified view, same structure in both modes ──
+    if (isRaw) {
+      // Raw mode: full project filesystem. /docs/ folders render full content.
+      // Non-docs dirs are subtly muted. Right-click non-docs → create /docs/.
+      const projectTree = this.lastTreesByProject.get(projectId) ?? [];
+      for (const node of projectTree) {
+        if (node.type === "dir") {
+          body.appendChild(this.renderBrowseNode(project, node, treesByRoot));
+        }
+      }
+    } else {
+      // Docs mode: only /docs/ roots and their content.
+      if (roots.length === 0) {
+        const note = document.createElement("div");
+        note.className = "nav-label nav-empty-copy";
+        note.textContent = "No docs folders found.";
+        body.appendChild(note);
+      } else {
+        const pathTree = buildPathTree(roots);
+        body.appendChild(this.renderPathNodes(pathTree, treesByRoot, projectId));
+      }
+    }
+
+    // ── Footer links (always visible when docs exist) ──
+    if (roots.length > 0) {
+      const boardsRow = document.createElement("div");
+      boardsRow.className = "nav-project-boards-row";
+      const allBoardsLink = this.link(
+        projectBoardsHref(projectId),
+        "All Boards",
+        `boards:${projectId}`
+      );
+      allBoardsLink.classList.add("nav-link-board");
+      allBoardsLink.insertAdjacentHTML("afterbegin", BOARD_ICON_HTML);
+      boardsRow.appendChild(allBoardsLink);
+      body.appendChild(boardsRow);
+
+      const firstRootWithCaps = roots.find((r) => {
+        const tree = treesByRoot.get(r.id) ?? [];
+        const capsDir = tree.find((n) => n.type === "dir" && n.name === "capabilities");
+        return capsDir?.type === "dir" &&
+          capsDir.children.some((n) => n.type === "file" && n.name.endsWith(".md"));
+      }) ?? roots[0];
+      const capsRow = document.createElement("div");
+      capsRow.className = "nav-project-boards-row";
+      const allCapsLink = this.link(
+        rootCapabilitiesHref(firstRootWithCaps.id),
+        "All Capabilities",
+        `caps:${projectId}`
+      );
+      allCapsLink.classList.add("nav-link-capability");
+      allCapsLink.insertAdjacentHTML("afterbegin", CAPABILITY_ICON_HTML);
+      capsRow.appendChild(allCapsLink);
+      body.appendChild(capsRow);
+    }
+
+    group.append(header, body);
+    return group;
+  }
+
+  // ---------- Browse mode (filesystem view) ----------
+
+  /**
+   * Render a directory node in the filesystem browse tree.
+   * /docs/ directories render their full docs content (identical to normal mode).
+   * Non-docs directories are greyed out with right-click to create /docs/.
+   */
+  private renderBrowseNode(
+    project: WorkspaceProject,
+    node: TreeNode,
+    treesByRoot: Map<string, TreeNode[]>
+  ): HTMLElement {
+    if (node.type === "file") {
+      const div = document.createElement("div");
+      div.className = "nav-browse-file";
+      div.textContent = node.name;
+      return div;
+    }
+
+    const isDocsFolder = node.name === "docs";
+
+    // /docs/ folder → render full docs content, same as normal mode.
+    if (isDocsFolder) {
+      const matchingRoot = project.docsRoots.find((r) =>
+        r.displayPath === node.path || r.displayPath.endsWith("/" + node.path)
+      );
+      if (matchingRoot) {
+        const tree = treesByRoot.get(matchingRoot.id) ?? [];
+        const section = this.docsRootSection(matchingRoot, tree);
+        return section;
+      }
+    }
+
+    // Non-docs directory. Directories that contain /docs/ somewhere below
+    // them look solid (they're part of the docs path). Others are muted.
+    const hasDocsDescendant = hasDocs(node);
+    const key = `browse:${project.id}:${node.path}`;
+
+    const group = document.createElement("div");
+    group.className = hasDocsDescendant ? "nav-subgroup nav-collapsible-dir" : "nav-subgroup nav-browse-dir";
+
+    const childrenContainer = document.createElement("div");
+    childrenContainer.className = "nav-dir-body";
+
+    const toggle = document.createElement("button");
+    toggle.className = hasDocsDescendant ? "nav-dir-toggle nav-dir-project" : "nav-browse-dir-toggle";
+    toggle.type = "button";
+
+    const chevronSpan = document.createElement("span");
+    chevronSpan.className = "nav-repo-chevron";
+    chevronSpan.textContent = "›";
+    const nameSpan = document.createElement("span");
+    nameSpan.textContent = node.name;
+    toggle.append(chevronSpan, nameSpan);
+    toggle.addEventListener("click", () => this.toggleCollapsible(key));
+
+    // Right-click behaviour depends on whether this dir leads to /docs/
+    if (hasDocsDescendant) {
+      // This dir is part of the docs path — offer docs root actions
+      const nearestRoot = project.docsRoots.find((r) =>
+        r.displayPath.startsWith(node.path + "/") || r.displayPath === node.path
+      );
+      if (nearestRoot) {
+        toggle.addEventListener("contextmenu", (e) => {
+          e.preventDefault();
+          e.stopPropagation();
+          this.openDirContextMenu(e.clientX, e.clientY, nearestRoot, "");
+        });
+      }
+    } else {
+      // Non-docs directory — only offer to create /docs/
+      toggle.addEventListener("contextmenu", (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        this.showContextMenu(e.clientX, e.clientY, node.name, [
+          {
+            icon: DIRECTORY_ICON_HTML,
+            iconClass: "nav-ctx-dir",
+            label: "Create /docs/",
+            action: () => this.callbacks.onCreateDocsFolder(project.id, node.path),
+          },
+        ]);
+      });
+    }
+
+    for (const child of node.children) {
+      if (child.type === "dir") {
+        childrenContainer.appendChild(this.renderBrowseNode(project, child, treesByRoot));
+      }
+    }
+
+    this.registerCollapsible(key, childrenContainer, group, toggle, true);
+    group.append(toggle, childrenContainer);
+
+    return group;
+  }
+
+  // ---------- Nested path-segment tree rendering ----------
+
+  private renderPathNodes(
+    nodes: PathNode[],
+    treesByRoot: Map<string, TreeNode[]>,
+    projectId: string,
+    parentPrefix = ""
+  ): HTMLElement {
+    const frag = document.createElement("div");
+    for (const node of nodes) {
+      if (node.kind === "root") {
+        frag.appendChild(this.docsRootSection(node.root, treesByRoot.get(node.root.id) ?? []));
+      } else {
+        const fullSegment = parentPrefix ? `${parentPrefix}/${node.segment}` : node.segment;
+        const key = `pathseg:${projectId}:${fullSegment}`;
+        const body = this.renderPathNodes(node.children, treesByRoot, projectId, fullSegment);
+        body.classList.add("nav-dir-body");
+        const group = document.createElement("div");
+        group.className = "nav-subgroup nav-collapsible-dir";
+
+        const firstRoot = firstLeafRoot(node);
+
+        const { row: dirHeader, toggle: btn } = this.createDirectoryRow(
+          node.segment,
+          `#/project/${encodeURIComponent(projectId)}`,
+          `${node.segment} wiki`,
+          () => this.toggleCollapsible(key),
+          true
+        );
+        if (firstRoot) {
+          group.addEventListener("contextmenu", (e) => {
+            e.preventDefault();
+            e.stopPropagation();
+            this.openDirContextMenu(e.clientX, e.clientY, firstRoot, "");
+          });
+        }
+
+        this.registerCollapsible(key, body, group, btn, true);
+        group.append(dirHeader, body);
+        frag.appendChild(group);
+      }
+    }
+    return frag;
+  }
+
+  // ---------- Docs-root section ----------
+
+  private docsRootSection(root: DocsRootSummary, tree: TreeNode[]): HTMLElement {
+    const section = document.createElement("div");
+    section.className = "nav-subgroup nav-docs-root";
+
+    const finalSegment = root.displayPath.split("/").pop() ?? root.displayPath;
+    const shouldShowRootLabel = finalSegment.toLowerCase() !== "docs";
+    if (shouldShowRootLabel) {
+      const label = document.createElement("div");
+      label.className = "nav-root-path-label";
+      label.textContent = finalSegment;
+      section.appendChild(label);
+
+      label.addEventListener("contextmenu", (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        this.openDirContextMenu(e.clientX, e.clientY, root, "");
+      });
+    }
+
+    section.addEventListener("contextmenu", (e) => {
+      if ((e.target as HTMLElement | null)?.closest(".nav-link, .nav-dir-toggle")) return;
+      e.preventDefault();
+      e.stopPropagation();
+      this.openDirContextMenu(e.clientX, e.clientY, root, "");
+    });
+    this.enableDirectoryDropTarget(section, root.id, "");
+
+    section.appendChild(this.docsNodes(root, flattenRedundantDocsDir(tree), "", tree));
+    return section;
+  }
+
+  // ---------- Unified directory rendering ----------
+
+  private createDirectoryRow(
+    name: string,
+    wikiHref: string,
+    wikiTitle: string,
+    onToggle: (e?: Event) => void,
+    isProjectStructure = false  // true = greyed out, false = docs content
+  ): { row: HTMLElement; toggle: HTMLButtonElement } {
+    const row = document.createElement("div");
+    row.className = "nav-dir-header-row";
+
+    const btn = document.createElement("button");
+    btn.className = isProjectStructure ? "nav-dir-toggle nav-dir-project" : "nav-dir-toggle nav-dir-docs";
+    btn.type = "button";
+    
+    const chevron = document.createElement("span");
+    chevron.className = "nav-repo-chevron";
+    chevron.innerHTML = `<svg viewBox="0 0 16 16" width="10" height="10" fill="currentColor"><path d="M6 4l4 4-4 4"/></svg>`;
+    
+    const textSpan = document.createElement("span");
+    textSpan.textContent = name;
+    
+    btn.append(chevron, textSpan);
+    btn.addEventListener("click", onToggle);
+
+    const wikiLink = document.createElement("a");
+    wikiLink.className = "nav-repo-wiki-link nav-dir-wiki-link";
+    wikiLink.href = wikiHref;
+    wikiLink.title = wikiTitle;
+    wikiLink.innerHTML =
+      `<svg viewBox="0 0 14 14" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">` +
+      `<rect x="2" y="2" width="10" height="10" rx="2"/>` +
+      `<path d="M5 5h4M5 7h4M5 9h2"/>` +
+      `</svg>`;
+    wikiLink.addEventListener("click", (e) => e.stopPropagation());
+    this.links.set(wikiHref, wikiLink);
+
+    row.append(btn, wikiLink);
+    return { row, toggle: btn };
+  }
+
+  // ---------- Mixed docs + boards tree ----------
+
+  private docsNodes(root: DocsRootSummary, nodes: TreeNode[], parentPath: string, boardTree: TreeNode[]): HTMLElement {
+    const frag = document.createElement("div");
+
+    const docNodes = visibleDocsNodes(nodes);
+    const boardFiles = boardNodesAt(boardTree, parentPath);
+
+    type MixedNode =
+      | { kind: "doc"; node: TreeNode }
+      | { kind: "board"; name: string; boardId: string };
+
+    const mixed: MixedNode[] = [
+      ...docNodes.map((node) => ({ kind: "doc" as const, node })),
+      ...boardFiles.map((f) => ({
+        kind: "board" as const,
+        name: prettify(boardIdFromFilePath(f.path).split("/").pop() ?? boardIdFromFilePath(f.path)),
+        boardId: boardIdFromFilePath(f.path),
+      })),
+    ].sort((a, b) => {
+      const aIsIndex = a.kind === "doc" && a.node.type === "file" && a.node.name === "index.md";
+      const bIsIndex = b.kind === "doc" && b.node.type === "file" && b.node.name === "index.md";
+      if (aIsIndex !== bIsIndex) return aIsIndex ? -1 : 1;
+      const aIsDir = a.kind === "doc" && a.node.type === "dir";
+      const bIsDir = b.kind === "doc" && b.node.type === "dir";
+      if (aIsDir !== bIsDir) return aIsDir ? -1 : 1;
+      const aName = a.kind === "doc" ? a.node.name : a.name;
+      const bName = b.kind === "doc" ? b.node.name : b.name;
+      return aName.localeCompare(bName);
+    });
+
+    for (const item of mixed) {
+      if (item.kind === "board") {
+        const a = document.createElement("a");
+        a.className = "nav-link nav-link-board";
+        a.href = rootBoardHref(root.id, item.boardId);
+        a.insertAdjacentHTML("afterbegin", BOARD_ICON_HTML);
+        a.appendChild(document.createTextNode(item.name));
+        const key = `board:${root.id}:${item.boardId}`;
+        this.links.set(key, a);
+        this.links.set(a.href, a);
+        this.enableDragSource(a, {
+          kind: "board",
+          rootId: root.id,
+          boardId: item.boardId,
+        });
+        // Right-click on board link
+        a.addEventListener("contextmenu", (e) => {
+          e.preventDefault();
+          e.stopPropagation();
+          this.openBoardContextMenu(e.clientX, e.clientY, root, item.boardId);
+        });
+        frag.appendChild(a);
+      } else {
+        const { node } = item;
+        if (node.type === "file") {
+          if (!node.name.endsWith(".md")) continue;
+          const linkLabel = node.name === "index.md" ? "Overview" : prettify(node.name);
+          const a = this.link(rootDocHref(root.id, node.path), linkLabel, `doc:${root.id}:${node.path}`);
+          a.insertAdjacentHTML("afterbegin", DOC_ICON_HTML);
+          this.enableDragSource(a, {
+            kind: "doc",
+            rootId: root.id,
+            path: node.path,
+          });
+          // Right-click on doc link
+          a.addEventListener("contextmenu", (e) => {
+            e.preventDefault();
+            e.stopPropagation();
+            this.openDocContextMenu(e.clientX, e.clientY, root, node.path);
+          });
+          frag.appendChild(a);
+        } else {
+          const key = `doc:${root.id}:${node.path}`;
+          const childNodes = this.docsNodes(root, node.children, node.path, boardTree);
+          childNodes.classList.add("nav-dir-body");
+          const group = document.createElement("div");
+          group.className = "nav-subgroup nav-collapsible-dir";
+
+          // Use unified directory row creator (docs content = darker)
+          const { row: dirHeader, toggle: btn } = this.createDirectoryRow(
+            prettify(node.name),
+            `#/root/${encodeURIComponent(root.id)}/directory/${encodeURIComponent(node.path)}`,
+            `${node.name} wiki`,
+            (e) => {
+              if ((e as MouseEvent).button !== 0) return;
+              this.toggleCollapsible(key);
+            },
+            false  // isProjectStructure = false (darker, inside docs root)
+          );
+          
+          this.enableDragSource(btn, {
+            kind: "dir",
+            rootId: root.id,
+            path: node.path,
+          });
+
+          // Right-click on directory group
+          group.addEventListener("contextmenu", (e) => {
+            e.preventDefault();
+            e.stopPropagation();
+            this.openDirContextMenu(e.clientX, e.clientY, root, node.path);
+          });
+          this.enableDirectoryDropTarget(group, root.id, node.path);
+
+          this.registerCollapsible(key, childNodes, group, btn, true);
+          group.append(dirHeader, childNodes);
+          frag.appendChild(group);
+        }
+      }
+    }
+
+    return frag;
+  }
+
+  // ---------- Drag/drop movement ----------
+
+  private enableDragSource(el: HTMLElement, item: SidebarDragItem): void {
+    el.draggable = true;
+    el.addEventListener("dragstart", (e) => {
+      this.closeContextMenu();
+      this.draggedItem = item;
+      el.classList.add("nav-dragging");
+      e.dataTransfer?.setData("application/x-docs-nav-item", JSON.stringify(item));
+      e.dataTransfer?.setData("text/plain", dragItemLabel(item));
+      if (e.dataTransfer) e.dataTransfer.effectAllowed = "move";
+    });
+    el.addEventListener("dragend", () => {
+      el.classList.remove("nav-dragging");
+      this.draggedItem = undefined;
+      this.clearDropTargets();
+    });
+  }
+
+  private enableDirectoryDropTarget(el: HTMLElement, rootId: string, targetDir: string): void {
+    el.addEventListener("dragover", (e) => {
+      const item = this.currentDragItem(e);
+      if (!item || !this.canDropItem(item, rootId, targetDir)) return;
+      e.preventDefault();
+      e.stopPropagation();
+      if (e.dataTransfer) e.dataTransfer.dropEffect = "move";
+      el.classList.add("nav-drop-target");
+    });
+    el.addEventListener("dragleave", (e) => {
+      if (el.contains(e.relatedTarget as Node | null)) return;
+      el.classList.remove("nav-drop-target");
+    });
+    el.addEventListener("drop", (e) => {
+      const item = this.currentDragItem(e);
+      if (!item || !this.canDropItem(item, rootId, targetDir)) return;
+      e.preventDefault();
+      e.stopPropagation();
+      this.clearDropTargets();
+      this.moveDraggedItem(item, targetDir);
+    });
+  }
+
+  private currentDragItem(e: DragEvent): SidebarDragItem | undefined {
+    if (this.draggedItem) return this.draggedItem;
+    const raw = e.dataTransfer?.getData("application/x-docs-nav-item");
+    if (!raw) return undefined;
+    try {
+      const parsed = JSON.parse(raw) as SidebarDragItem;
+      if (
+        parsed &&
+        (parsed.kind === "doc" || parsed.kind === "board" || parsed.kind === "dir") &&
+        typeof parsed.rootId === "string"
+      ) {
+        return parsed;
+      }
+    } catch {
+      /* ignore */
+    }
+    return undefined;
+  }
+
+  private canDropItem(item: SidebarDragItem, rootId: string, targetDir: string): boolean {
+    if (item.rootId !== rootId) return false;
+    const normalizedTarget = normalizeDirPath(targetDir);
+    if (item.kind === "doc") return parentDir(item.path) !== normalizedTarget;
+    if (item.kind === "board") return parentDir(item.boardId) !== normalizedTarget;
+
+    const source = normalizeDirPath(item.path);
+    if (!source) return false;
+    if (source === normalizedTarget) return false;
+    if (parentDir(source) === normalizedTarget) return false;
+    return !normalizedTarget.startsWith(`${source}/`);
+  }
+
+  private moveDraggedItem(item: SidebarDragItem, targetDir: string): void {
+    const normalizedTarget = normalizeDirPath(targetDir);
+    if (item.kind === "doc") {
+      this.callbacks.onMoveDoc(item.rootId, item.path, normalizedTarget);
+    } else if (item.kind === "board") {
+      this.callbacks.onMoveBoard(item.rootId, item.boardId, normalizedTarget);
+    } else {
+      this.callbacks.onMoveDirectory(item.rootId, item.path, normalizedTarget);
+    }
+  }
+
+  private clearDropTargets(): void {
+    this.element.querySelectorAll(".nav-drop-target").forEach((node) => {
+      node.classList.remove("nav-drop-target");
+    });
+  }
+
+  // ---------- Inline editing (VS Code style) ----------
+
+  /**
+   * Replace a nav link's text with an inline input for renaming.
+   * Enter confirms, Escape cancels, blur confirms.
+   */
+  startInlineRename(
+    linkEl: HTMLElement,
+    currentName: string,
+    onConfirm: (newName: string) => void
+  ): void {
+    const input = document.createElement("input");
+    input.className = "nav-inline-input";
+    input.value = currentName.replace(/\.md$/, "");
+    // Preserve the link's position in the tree
+    const parent = linkEl.parentElement;
+    if (!parent) return;
+    linkEl.style.display = "none";
+    parent.insertBefore(input, linkEl.nextSibling);
+    input.focus();
+    input.select();
+
+    let settled = false;
+    const finish = (accept: boolean) => {
+      if (settled) return;
+      settled = true;
+      input.remove();
+      linkEl.style.display = "";
+      if (accept) {
+        const raw = input.value.trim();
+        if (raw && raw !== currentName.replace(/\.md$/, "")) {
+          onConfirm(raw);
+        }
+      }
+    };
+
+    input.addEventListener("keydown", (e) => {
+      e.stopPropagation();
+      if (e.key === "Enter") { e.preventDefault(); finish(true); }
+      if (e.key === "Escape") { e.preventDefault(); finish(false); }
+    });
+    input.addEventListener("blur", () => finish(true));
+  }
+
+  /**
+   * Show an inline input inside a container for creating a new item.
+   * Enter confirms, Escape cancels.
+   */
+  startInlineCreate(
+    container: HTMLElement,
+    placeholder: string,
+    onConfirm: (name: string) => void
+  ): void {
+    const input = document.createElement("input");
+    input.className = "nav-inline-input";
+    input.placeholder = placeholder;
+    container.insertBefore(input, container.firstChild);
+    input.focus();
+
+    let settled = false;
+    const finish = (accept: boolean) => {
+      if (settled) return;
+      settled = true;
+      input.remove();
+      if (accept) {
+        const raw = input.value.trim();
+        if (raw) onConfirm(raw);
+      }
+    };
+
+    input.addEventListener("keydown", (e) => {
+      e.stopPropagation();
+      if (e.key === "Enter") { e.preventDefault(); finish(true); }
+      if (e.key === "Escape") { e.preventDefault(); finish(false); }
+    });
+    input.addEventListener("blur", () => finish(true));
+  }
+
+  // ---------- Collapse / expand machinery ----------
+
+  /**
+   * Register a collapsible section. `defaultCollapsed` is always true —
+   * everything starts collapsed. Apply initial DOM state immediately.
+   */
+  private registerCollapsible(
+    key: string,
+    body: HTMLElement,
+    group: HTMLElement,
+    btn: HTMLButtonElement,
+    defaultCollapsed: boolean
+  ): void {
+    this.collapsibles.set(key, { body, group, btn });
+    this.applyCollapsed(key, this.collapsedState.get(key) ?? defaultCollapsed);
+  }
+
+  private applyCollapsed(key: string, collapsed: boolean): void {
+    const rec = this.collapsibles.get(key);
+    if (!rec) return;
+    this.collapsedState.set(key, collapsed);
+    rec.body.hidden = collapsed;
+    rec.group.classList.toggle("collapsed", collapsed);
+    rec.btn.setAttribute("aria-expanded", String(!collapsed));
+  }
+
+  private toggleCollapsible(key: string): void {
+    const rec = this.collapsibles.get(key);
+    if (!rec) return;
+    this.applyCollapsed(key, !rec.body.hidden);
+  }
+
+
+
+  // ---------- Context menus ----------
+
+  private openDirContextMenu(x: number, y: number, root: DocsRootSummary, dirPath: string): void {
+    const label = dirPath
+      ? prettify(dirPath.split("/").pop() ?? dirPath)
+      : (root.displayPath.split("/").pop() ?? root.displayPath);
+    
+    const items = [
+      {
+        icon: DIRECTORY_ICON_HTML, iconClass: "nav-ctx-dir", label: "New Directory",
+        action: () => this.callbacks.onCreateDirectory(root.id, dirPath),
+      },
+      {
+        icon: BOARD_ICON_HTML, iconClass: "nav-ctx-board", label: "New Board",
+        action: () => this.callbacks.onCreateBoard(root.id, dirPath),
+      },
+      {
+        icon: DOC_ICON_HTML, iconClass: "nav-ctx-doc", label: "New Doc",
+        action: () => this.callbacks.onCreateDoc(root.id, dirPath),
+      },
+      {
+        icon: CAPABILITY_ICON_HTML, iconClass: "nav-ctx-cap", label: "New Capability",
+        action: () => this.callbacks.onCreateCapability(root.id, dirPath),
+      },
+    ];
+    
+    // Add rename/delete for non-root directories
+    if (dirPath) {
+      items.push(
+        {
+          icon: RENAME_ICON_HTML, iconClass: "nav-ctx-rename", label: "Rename",
+          action: () => this.callbacks.onRenameDirectory(root.id, dirPath),
+        },
+        {
+          icon: TRASH_ICON_HTML, iconClass: "nav-ctx-delete", label: "Delete",
+          action: () => this.callbacks.onDeleteDirectory(root.id, dirPath),
+        }
+      );
+    }
+    
+    this.showContextMenu(x, y, label, items);
+  }
+
+  private openEmptyProjectContextMenu(x: number, y: number, projectId: string, label: string): void {
+    this.showContextMenu(x, y, label, [
+      {
+        icon: DIRECTORY_ICON_HTML, iconClass: "nav-ctx-dir", label: "New Directory",
+        action: () => this.callbacks.onCreateProjectDirectory(projectId),
+      },
+      {
+        icon: BOARD_ICON_HTML, iconClass: "nav-ctx-board", label: "New Board",
+        action: () => this.callbacks.onCreateProjectBoard(projectId),
+      },
+      {
+        icon: DOC_ICON_HTML, iconClass: "nav-ctx-doc", label: "New Doc",
+        action: () => this.callbacks.onCreateProjectDoc(projectId),
+      },
+    ]);
+  }
+
+  private openDocContextMenu(x: number, y: number, root: DocsRootSummary, filePath: string): void {
+    const name = filePath.split("/").pop() ?? filePath;
+    this.showContextMenu(x, y, name, [
+      {
+        icon: DOC_ICON_HTML, iconClass: "nav-ctx-doc", label: "Open",
+        action: () => this.callbacks.onOpenDoc(root.id, filePath),
+      },
+      {
+        icon: EDIT_ICON_HTML, iconClass: "nav-ctx-edit", label: "Edit",
+        action: () => this.callbacks.onEditDoc(root.id, filePath),
+      },
+      { kind: "divider" as const },
+      {
+        icon: RENAME_ICON_HTML, iconClass: "nav-ctx-rename", label: "Rename",
+        action: () => this.callbacks.onRenameDoc(root.id, filePath),
+      },
+      {
+        icon: TRASH_ICON_HTML, iconClass: "nav-ctx-delete", label: "Delete",
+        action: () => this.callbacks.onDeleteDoc(root.id, filePath),
+        danger: true,
+      },
+    ]);
+  }
+
+  private openBoardContextMenu(x: number, y: number, root: DocsRootSummary, boardId: string): void {
+    const name = prettify(boardId.split("/").pop() ?? boardId);
+    this.showContextMenu(x, y, name, [
+      {
+        icon: BOARD_ICON_HTML, iconClass: "nav-ctx-board", label: "Open",
+        action: () => this.callbacks.onOpenBoard(root.id, boardId),
+      },
+      { kind: "divider" as const },
+      {
+        icon: RENAME_ICON_HTML, iconClass: "nav-ctx-rename", label: "Rename",
+        action: () => this.callbacks.onRenameBoard(root.id, boardId),
+      },
+      {
+        icon: TRASH_ICON_HTML, iconClass: "nav-ctx-delete", label: "Delete",
+        action: () => this.callbacks.onDeleteBoard(root.id, boardId),
+        danger: true,
+      },
+    ]);
+  }
+
+  private showContextMenu(
+    x: number,
+    y: number,
+    label: string,
+    items: Array<
+      | { kind?: undefined; icon: string; iconClass: string; label: string; action: () => void; danger?: boolean }
+      | { kind: "divider" }
+    >
+  ): void {
+    this.closeContextMenu();
+
+    const menu = document.createElement("div");
+    menu.className = "nav-context-menu";
+    menu.addEventListener("pointerdown", (e) => e.stopPropagation());
+
+    const lbl = document.createElement("div");
+    lbl.className = "nav-context-label";
+    lbl.textContent = label;
+    menu.appendChild(lbl);
+
+    const topDivider = document.createElement("div");
+    topDivider.className = "nav-context-divider";
+    menu.appendChild(topDivider);
+
+    for (const item of items) {
+      if (item.kind === "divider") {
+        const d = document.createElement("div");
+        d.className = "nav-context-divider";
+        menu.appendChild(d);
+        continue;
+      }
+      const btn = document.createElement("button");
+      btn.className = "nav-context-item" + (item.danger ? " nav-context-item-danger" : "");
+      btn.type = "button";
+      const icon = document.createElement("span");
+      icon.className = `nav-ctx-icon ${item.iconClass}`;
+      icon.innerHTML = item.icon;
+      const text = document.createElement("span");
+      text.textContent = item.label;
+      btn.append(icon, text);
+      btn.addEventListener("click", () => {
+        this.closeContextMenu();
+        item.action();
+      });
+      menu.appendChild(btn);
+    }
+
+    menu.style.position = "fixed";
+    menu.style.left = `${x}px`;
+    menu.style.top = `${y}px`;
+    document.body.appendChild(menu);
+    this.contextMenu = menu;
+
+    requestAnimationFrame(() => {
+      if (!this.contextMenu) return;
+      const rect = menu.getBoundingClientRect();
+      if (rect.right > window.innerWidth) menu.style.left = `${Math.max(0, x - rect.width)}px`;
+      if (rect.bottom > window.innerHeight) menu.style.top = `${Math.max(0, y - rect.height)}px`;
+    });
+  }
+
+  private closeContextMenu(): void {
+    this.contextMenu?.remove();
+    this.contextMenu = undefined;
+  }
+
+  // ---------- Helpers ----------
+
+  private groupLabel(text: string): HTMLElement {
+    const el = document.createElement("div");
+    el.className = "nav-label";
+    el.textContent = text;
+    return el;
+  }
+
+  private link(href: string, label: string, key: string): HTMLAnchorElement {
+    const a = document.createElement("a");
+    a.className = "nav-link";
+    a.href = href;
+    a.textContent = label;
+    this.links.set(key, a);
+    this.links.set(href, a);
+    return a;
+  }
+}
+
+// ---------- Inline SVG icons ----------
+
+const BOARD_ICON_HTML =
+  `<svg class="nav-node-icon nav-node-icon-board" viewBox="0 0 16 16" aria-hidden="true">` +
+  `<rect x="1" y="1" width="6" height="6" rx="1"/>` +
+  `<rect x="9" y="1" width="6" height="6" rx="1"/>` +
+  `<rect x="1" y="9" width="6" height="6" rx="1"/>` +
+  `<rect x="9" y="9" width="6" height="6" rx="1"/>` +
+  `</svg>`;
+
+/** Skill icon: a star/spark shape. */
+const CAPABILITY_ICON_HTML =
+  `<svg class="nav-node-icon nav-node-icon-capability" viewBox="0 0 16 16" aria-hidden="true">` +
+  `<path d="M8 1l2 4.5 4.5 0.7-3.3 3.1 0.8 4.7-4-2.1-4 2.1 0.8-4.7L1.5 6.2l4.5-0.7z"/>` +
+  `</svg>`;
+
+const DOC_ICON_HTML =
+  `<svg class="nav-node-icon nav-node-icon-doc" viewBox="0 0 16 16" aria-hidden="true">` +
+  `<path d="M3 1.5h6.5l3 3V14.5H3z"/>` +
+  `<path d="M9.5 1.5V4.5h3" stroke="none"/>` +
+  `<line x1="5" y1="7" x2="11" y2="7" stroke="var(--bg-canvas)" stroke-width="0.8"/>` +
+  `<line x1="5" y1="9.5" x2="11" y2="9.5" stroke="var(--bg-canvas)" stroke-width="0.8"/>` +
+  `<line x1="5" y1="12" x2="9" y2="12" stroke="var(--bg-canvas)" stroke-width="0.8"/>` +
+  `</svg>`;
+
+const DIRECTORY_ICON_HTML =
+  `<svg class="nav-ctx-svg" viewBox="0 0 16 16" aria-hidden="true" fill="none" stroke="currentColor" stroke-width="1.45" stroke-linecap="round" stroke-linejoin="round">` +
+  `<path d="M2 4.5h4l1.4 1.6H14v6.4a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1z"/>` +
+  `<path d="M2 4.5v-1a1 1 0 0 1 1-1h3l1.4 2"/>` +
+  `</svg>`;
+
+// Context-menu-only icons (stroke-based, not fill).
+const EDIT_ICON_HTML =
+  `<svg class="nav-ctx-svg" viewBox="0 0 16 16" aria-hidden="true" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">` +
+  `<path d="M11 2l3 3-8 8H3v-3z"/>` +
+  `</svg>`;
+
+const RENAME_ICON_HTML =
+  `<svg class="nav-ctx-svg" viewBox="0 0 16 16" aria-hidden="true" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">` +
+  `<path d="M2 12h12M8 3v9M5 6l3-3 3 3"/>` +
+  `</svg>`;
+
+const TRASH_ICON_HTML =
+  `<svg class="nav-ctx-svg" viewBox="0 0 16 16" aria-hidden="true" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">` +
+  `<path d="M2 4h12M5 4V2h6v2M6 7v5M10 7v5M3 4l1 9a1 1 0 001 1h6a1 1 0 001-1l1-9"/>` +
+  `</svg>`;
+
+// ---------- Tree utilities ----------
+
+function visibleDocsNodes(nodes: TreeNode[]): TreeNode[] {
+  return nodes
+    .filter((node) => {
+      if (node.type === "file") return node.name.endsWith(".md");
+      if (SPECIAL_DIRS.has(node.name)) return false;
+      return true;
+    })
+    .map((node) => {
+      if (node.type === "file") return node;
+      return { ...node, children: visibleDocsNodes(node.children) };
+    });
+}
+
+function flattenRedundantDocsDir(nodes: TreeNode[]): TreeNode[] {
+  const docsDir = nodes.find((node) => node.type === "dir" && node.name.toLowerCase() === "docs");
+  if (!docsDir || docsDir.type !== "dir") return nodes;
+  return nodes
+    .filter((node) => node !== docsDir)
+    .concat(docsDir.children);
+}
+
+function boardNodesAt(tree: TreeNode[], parentPath: string): TreeNode[] {
+  const prefix = parentPath ? `${parentPath}/` : "";
+  return allBoardFiles(tree).filter((n) => {
+    if (!prefix) return !n.path.includes("/");
+    if (!n.path.startsWith(prefix)) return false;
+    return !n.path.slice(prefix.length).includes("/");
+  });
+}
+
+function allBoardFiles(tree: TreeNode[]): Array<Extract<TreeNode, { type: "file" }>> {
+  const out: Array<Extract<TreeNode, { type: "file" }>> = [];
+  const walk = (nodes: TreeNode[]) => {
+    for (const node of nodes) {
+      if (node.type === "file") {
+        if (node.name.endsWith(".board.json")) out.push(node);
+      } else {
+        walk(node.children);
+      }
+    }
+  };
+  walk(tree);
+  return out;
+}
+
+// ---------- Hash / href builders ----------
+
+function rootDocHref(rootId: string, path: string): string {
+  return `#/root/${encodeURIComponent(rootId)}/docs/${encodeURIComponent(path)}`;
+}
+
+function rootBoardsHref(rootId: string): string {
+  return `#/root/${encodeURIComponent(rootId)}/boards`;
+}
+
+function projectBoardsHref(projectId: string): string {
+  return `#/project/${encodeURIComponent(projectId)}/boards`;
+}
+
+function rootBoardHref(rootId: string, id: string): string {
+  return `#/root/${encodeURIComponent(rootId)}/boards/${encodeURIComponent(id)}`;
+}
+
+function rootCapabilitiesHref(rootId: string): string {
+  return `#/root/${encodeURIComponent(rootId)}/capabilities`;
+}
+
+function prettify(name: string): string {
+  const base = name.replace(/\.md$/, "").replace(/[-_]/g, " ");
+  return base.charAt(0).toUpperCase() + base.slice(1);
+}
+
+/** Check if a directory node has a "docs" child anywhere in its subtree. */
+function hasDocs(node: TreeNode): boolean {
+  if (node.type === "file") return false;
+  for (const child of node.children) {
+    if (child.type === "dir" && child.name === "docs") return true;
+    if (child.type === "dir" && hasDocs(child)) return true;
+  }
+  return false;
+}
+
+function normalizeDirPath(path: string): string {
+  return path.replace(/^\/+|\/+$/g, "");
+}
+
+function parentDir(path: string): string {
+  const normalized = normalizeDirPath(path);
+  const idx = normalized.lastIndexOf("/");
+  return idx === -1 ? "" : normalized.slice(0, idx);
+}
+
+function dragItemLabel(item: SidebarDragItem): string {
+  if (item.kind === "doc") return item.path;
+  if (item.kind === "board") return item.boardId;
+  return item.path;
+}
+
+/** Walk a PathNode subtree and return the first leaf DocsRootSummary found. */
+function firstLeafRoot(node: PathNode): DocsRootSummary | null {
+  if (node.kind === "root") return node.root;
+  for (const child of node.children) {
+    const found = firstLeafRoot(child);
+    if (found) return found;
+  }
+  return null;
+}