collabmd 0.1.49 → 0.1.52

package/src/client/bootstrap/collabmd-app-shell.js

@@ -1,4 +1,5 @@
 import { PdfPreviewController } from '../application/pdf-preview-controller.js';
+import { analyzeMarkdownComplexity, isLargeDocumentStats } from '../application/preview-render-profile.js';
 import { PreviewRenderer } from '../application/preview-renderer.js';
 import { renderWebMcpDiagram } from '../application/webmcp-diagram-renderer.js';
 import { ensureQuickSwitcherInstance, toggleQuickSwitcherInstance } from '../application/quick-switcher-loader.js';
@@ -19,15 +20,18 @@ import { uiFeatureSidebarMethods } from '../application/app-shell/ui-feature-sid
 import { uiFeatureTabActivityMethods } from '../application/app-shell/ui-feature-tab-activity.js';
 import { uiFeatureToolbarMethods } from '../application/app-shell/ui-feature-toolbar.js';
 import { workspaceFeature } from '../application/app-shell/workspace-feature.js';
+import { LOBBY_CHAT_MESSAGE_MAX_LENGTH } from '../domain/lobby-chat.js';
 import { agentConnectionApiClient } from '../infrastructure/agent-connection-api-client.js';
-import { LOBBY_CHAT_MESSAGE_MAX_LENGTH, LobbyPresence } from '../infrastructure/lobby-presence.js';
 import { BrowserPreferencesPort } from '../infrastructure/browser-preferences-port.js';
+import { hostedApiClient } from '../infrastructure/hosted-api-client.js';
 import { BrowserNotificationPort } from '../infrastructure/browser-notification-port.js';
 import { AppVersionMonitor } from '../infrastructure/app-version-monitor.js';
 import { gitApiClient } from '../infrastructure/git-api-client.js';
 import {
+  getActiveVaultId,
   getHashRoute,
   getRuntimeConfig,
+  setActiveVaultId,
   navigateToFile,
   navigateToGitCommit,
   navigateToGitDiff,
@@ -38,9 +42,11 @@ import {
 import { TabActivityLock } from '../infrastructure/tab-activity-lock.js';
 import { vaultApiClient } from '../infrastructure/vault-api-client.js';
 import { WebMcpToolRegistry } from '../infrastructure/webmcp-tool-registry.js';
-import { WorkspaceSyncClient } from '../infrastructure/workspace-sync-client.js';
+import { createLazyLobbyPresence, createLazyWorkspaceSyncClient } from './lazy-collab-clients.js';
 import { AgentConnectionController } from '../presentation/agent-connection-controller.js';
 import { BacklinksPanel } from '../presentation/backlinks-panel.js';
+import { HostedWorkspaceGateController } from '../presentation/hosted-workspace-gate-controller.js';
+import { TeamSettingsController } from '../presentation/team-settings-controller.js';
 import { CommentOverviewController } from '../presentation/comment-overview-controller.js';
 import { CommentUiController } from '../presentation/comment-ui-controller.js';
 import { FileExplorerController } from '../presentation/file-explorer-controller.js';
@@ -152,12 +158,12 @@ export class CollabMdAppShell {
       runtimeConfig: this.runtimeConfig,
     });
 
-    this.lobby = new LobbyPresence({
+    this.lobby = createLazyLobbyPresence({
       preferredUserName: this.getStoredUserName(),
       onChange: (users) => this.updateGlobalUsers(users),
       onChatChange: (messages, meta) => this.updateChatMessages(messages, meta),
     });
-    this.workspaceSync = new WorkspaceSyncClient({
+    this.workspaceSync = createLazyWorkspaceSyncClient({
       onTreeChange: (tree, metadata = {}) => {
         this.fileExplorer.setTree(tree, metadata);
         this.handleCommentOverviewWorkspaceTreeChange?.();
@@ -179,6 +185,21 @@ export class CollabMdAppShell {
       toastController: this.toastController,
       trigger: this.elements.connectAgentButton,
     });
+    this.teamSettingsController = new TeamSettingsController({
+      apiClient: hostedApiClient,
+      closeToolbarMenu: () => this.closeToolbarOverflowMenu(),
+      content: this.elements.teamSettingsContent,
+      dialog: this.elements.teamSettingsDialog,
+      toastController: this.toastController,
+      trigger: this.elements.teamSettingsButton,
+    });
+    this.hostedGateController = new HostedWorkspaceGateController({
+      apiClient: hostedApiClient,
+      appRoot: this.elements.appShell,
+      gate: this.elements.hostedGate,
+      runtimeConfig: this.runtimeConfig,
+      teamSettingsController: this.teamSettingsController,
+    });
     const callAgentTool = (...args) => this.vaultApiClient.callAgentTool(...args);
     this.webMcpTools = new WebMcpToolRegistry({
       acknowledgeToolCall: ({ input, name, preparation, result, signal }) => {
@@ -200,12 +221,21 @@ export class CollabMdAppShell {
             signal: options?.signal,
           })
         : callAgentTool(name, input, options),
-      getActiveContext: () => ({
-        activeDiagramPath: this.isExcalidrawFile(this.currentFilePath)
-          ? this.currentFilePath
-          : null,
-        activePath: this.currentFilePath,
-      }),
+      getActiveContext: async () => {
+        const activePath = this.currentFilePath;
+        const session = this.session;
+        const context = session?.activeFilePath === activePath
+          ? await session.getAgentContext()
+          : null;
+        if (activePath !== this.currentFilePath || session !== this.session) {
+          throw new Error('Active document changed; request active context again');
+        }
+        return {
+          ...context,
+          activeDiagramPath: this.isExcalidrawFile(activePath) ? activePath : null,
+          activePath,
+        };
+      },
       getIsTabActive: () => this.isTabActive,
       onDidMutate: () => {
         this.toastController.show('Agent-assisted Vault change applied. Review it before committing.');
@@ -216,7 +246,6 @@ export class CollabMdAppShell {
             'edit_excalidraw',
             'inspect_excalidraw',
             'read_document',
-            'render_excalidraw',
             'verify_excalidraw',
           ].includes(name)
           || input.path !== this.currentFilePath
@@ -244,6 +273,18 @@ export class CollabMdAppShell {
       showFileExtensions: this.preferences.getFileTreeShowExtensions(),
       toastController: this.toastController,
       vaultClient: this.vaultApiClient,
+      // ponytail: reload keeps the file hash, so the same path reopens in the new vault
+      vaultSwitcher: {
+        activeVaultId: getActiveVaultId(this.runtimeConfig),
+        vaults: this.runtimeConfig.vaults ?? [],
+        onVaultSelect: (vaultId) => {
+          if (!vaultId || vaultId === getActiveVaultId(this.runtimeConfig)) {
+            return;
+          }
+          setActiveVaultId(vaultId);
+          window.location.reload();
+        },
+      },
     });
     this.commentsOverview = new CommentOverviewController({
       onOverviewChange: (_overview, { threadCounts }) => {
@@ -258,7 +299,7 @@ export class CollabMdAppShell {
       enabled: this.runtimeConfig.gitEnabled !== false,
       gitApiClient: this.gitApiClient,
       onCommitStaged: () => this.openGitCommitDialog(),
-      onOpenPullBackup: (filePath) => filePath && this.navigation.navigateToFile(filePath),
+      onOpenPullBackup: (backupId) => backupId && window.open(gitApiClient.getPullBackupSummaryUrl(backupId), '_blank', 'noopener,noreferrer'),
       onPullBranch: () => this.pullGitBranch(),
       onPushBranch: () => this.pushGitBranch(),
       onRepoChange: (isGitRepo, status) => this.handleGitRepoChange(isGitRepo, status),
@@ -308,6 +349,11 @@ export class CollabMdAppShell {
     this.previewRenderer = new PreviewRenderer({
       getContent: () => this.getPreviewSource(),
       getFileList: () => this.fileExplorer.flatDocumentFiles,
+      getPreviewVisible: () => (
+        Boolean(this._staticPreviewDocument)
+        || this.layoutController?.currentView !== 'editor'
+      ),
+      getTheme: () => this.themeController?.getTheme?.() ?? 'dark',
       getWikiLinkAutoCreate: () => this.runtimeConfig.wikiLinkAutoCreate !== false,
       loadFileSource: async (filePath) => {
         const payload = await this.vaultApiClient.readFile(filePath);
@@ -324,10 +370,10 @@ export class CollabMdAppShell {
         this.drawioEmbed.reconcileEmbeds(this.elements.previewContent);
         this.excalidrawEmbed.reconcileEmbeds(this.elements.previewContent, { isLargeDocument: stats.isLargeDocument });
         this.scrollSyncController.setLargeDocumentMode(stats.isLargeDocument);
-        this.syncPreviewCodeCopyButtons();
         this.syncPreviewHeadingFoldButtons();
         this.syncPreviewHeadingLinkButtons();
         this.applyPendingPreviewRouteAnchor({ behavior: 'auto', clearMissing: true });
+
         this.schedulePreviewLayoutSync({ delayMs: 0 });
         this.refreshCommentUiLayout();
       },
@@ -342,11 +388,6 @@ export class CollabMdAppShell {
         this.schedulePreviewLayoutSync({ delayMs: 0 });
         this.refreshCommentUiLayout();
       },
-      onRenderComplete: () => {
-        this.applyPendingPreviewRouteAnchor({ allowExpired: true, behavior: 'auto', clearMissing: true });
-        this.schedulePreviewLayoutSync({ delayMs: 0 });
-        this.refreshCommentUiLayout();
-      },
       outlineController: this.outlineController,
       plantUmlRenderClient: this.vaultApiClient,
       previewContainer: this.elements.previewContainer,
@@ -355,8 +396,16 @@ export class CollabMdAppShell {
     });
     this.themeController = new ThemeController({ onChange: (theme) => this.handleThemeChange(theme) });
     this.layoutController = new LayoutController({
+      preferredView: this.preferences.getViewMode() || 'split',
       mobileBreakpointQuery: this.mobileBreakpointQuery,
       onMeasureEditor: () => this.session?.requestMeasure(),
+      onPreferredViewChange: (view) => this.preferences.setViewMode(view),
+      onViewChange: () => {
+        if (!this.currentFilePath && !this._staticPreviewDocument) {
+          return;
+        }
+        this.previewRenderer.queueRender();
+      },
       onViewRequest: (view) => this.handleLayoutViewRequest(view),
     });
     this.scrollSyncController = new ScrollSyncController({
@@ -416,7 +465,10 @@ export class CollabMdAppShell {
       commentsDrawerList: this.elements.commentsDrawerList,
       commentsToggleButton: this.elements.commentsToggleButton,
       editorContainer: this.elements.editorContainer,
-      onWillOpenDrawer: () => this.outlineController.close(),
+      onWillOpenDrawer: () => {
+        this._deferredCollabStylesPromise ??= import('../styles/deferred-collab.css');
+        this.outlineController.close();
+      },
       previewContainer: this.elements.previewContainer,
       previewElement: this.elements.previewContent,
       onCreateThread: ({ anchor, body }) => this.createCommentThread({ anchor, body }),
@@ -569,6 +621,7 @@ export class CollabMdAppShell {
       onBeforeFileOpen: () => {
         clearTimeout(this._basePreviewRenderTimer);
         this._basePreviewRenderTimer = null;
+        this.connectWorkspaceSync?.();
         this.session = null;
         this.commentUi.attachSession(null);
         this.layoutController.reset();
@@ -579,7 +632,7 @@ export class CollabMdAppShell {
         this.clearInitialFileBootstrap();
       },
       onConnectionChange: (state) => this.handleConnectionChange(state),
-      onContentChange: ({ isBase, isHtml, isMermaid, isPlantUml, isStructurizrWorkspace }) => {
+      onContentChange: ({ isBase, isHtml, isStructurizrWorkspace }) => {
         void this.webMcpTools.refresh();
         this.handleCommentEditorContentChange();
         if (isHtml) {
@@ -604,10 +657,16 @@ export class CollabMdAppShell {
           return;
         }
 
-        this.previewRenderer.queueRender();
-        if (!isMermaid && !isPlantUml) {
-          this.scheduleBacklinkRefresh();
+        const markdownText = this.session?.getText?.() ?? '';
+        if (
+          !this.preferences.getViewMode()
+          && this.layoutController.currentView === 'split'
+          && isLargeDocumentStats(analyzeMarkdownComplexity(markdownText))
+        ) {
+          this.layoutController.setView('editor', { persist: false });
         }
+
+        this.previewRenderer.queueRender();
       },
       onCommentsChange: (threads) => this.handleCommentThreadsChange(threads),
       onFileAwarenessChange: (users) => this.updateFileAwareness(users),
@@ -782,29 +841,15 @@ export class CollabMdAppShell {
     return this._editorSessionModulePromise;
   }
 
-  scheduleEditorSessionPrewarm({ timeout = 1500 } = {}) {
-    if (this._editorSessionModulePromise || this._editorSessionPrewarmHandle) {
-      return;
-    }
-
-    const runPrewarm = () => {
-      this._editorSessionPrewarmHandle = null;
-      void this.loadEditorSessionClass();
-    };
-
-    if (typeof window.requestIdleCallback === 'function') {
-      this._editorSessionPrewarmHandle = window.requestIdleCallback(runPrewarm, { timeout });
-      return;
-    }
-
-    this._editorSessionPrewarmHandle = window.setTimeout(runPrewarm, 0);
-  }
 
   loadQuickSwitcherController() {
-    return import('../presentation/quick-switcher-controller.js')
-      .then((module) => module.QuickSwitcherController);
+    return Promise.all([
+      import('../presentation/quick-switcher-controller.js'),
+      import('../styles/features/quick-switcher.css'),
+    ]).then(([module]) => module.QuickSwitcherController);
   }
 
+
   async ensureQuickSwitcher() {
     return ensureQuickSwitcherInstance(this);
   }

package/src/client/bootstrap/lazy-collab-clients.js

@@ -0,0 +1,90 @@
+import { createRandomUser } from '../domain/room.js';
+
+function createLazyClient(load) {
+  let impl = null;
+  let loadPromise = null;
+
+  function ensure() {
+    loadPromise ??= Promise.resolve().then(load).then((created) => {
+      impl = created;
+      return created;
+    });
+    return loadPromise;
+  }
+
+  return {
+    ensure,
+    getImpl: () => impl,
+    get provider() {
+      return impl?.provider ?? null;
+    },
+    connect() {
+      void ensure().then((client) => {
+        client.connect();
+      });
+    },
+    disconnect() {
+      impl?.disconnect();
+    },
+    destroy() {
+      impl?.destroy();
+    },
+  };
+}
+
+export function createLazyLobbyPresence(options = {}) {
+  let currentFile = null;
+  let localUser = createRandomUser(options.preferredUserName);
+  const client = createLazyClient(async () => {
+    const { LobbyPresence } = await import('../infrastructure/lobby-presence.js');
+    const impl = new LobbyPresence({
+      ...options,
+      preferredUserName: localUser.name,
+    });
+    impl.localUser = localUser;
+    if (currentFile) {
+      impl.setCurrentFile(currentFile);
+    }
+    return impl;
+  });
+
+  return {
+    get provider() {
+      return client.provider;
+    },
+    connect: () => client.connect(),
+    disconnect: () => client.disconnect(),
+    destroy: () => client.destroy(),
+    getConnectionState() {
+      return client.getImpl()?.getConnectionState?.()
+        ?? { status: 'connecting', unreachable: false };
+    },
+    setCurrentFile(filePath) {
+      currentFile = filePath;
+      client.getImpl()?.setCurrentFile(filePath);
+    },
+    setUserName(name) {
+      if (!name) {
+        return;
+      }
+      localUser = { ...localUser, name };
+      client.getImpl()?.setUserName(name);
+    },
+    getLocalUser() {
+      return client.getImpl()?.getLocalUser() ?? localUser;
+    },
+    sendChatMessage(text) {
+      return client.getImpl()?.sendChatMessage(text) ?? null;
+    },
+    sendWorkspaceEvent(payload) {
+      return client.getImpl()?.sendWorkspaceEvent(payload);
+    },
+  };
+}
+
+export function createLazyWorkspaceSyncClient(options = {}) {
+  return createLazyClient(async () => {
+    const { WorkspaceSyncClient } = await import('../infrastructure/workspace-sync-client.js');
+    return new WorkspaceSyncClient(options);
+  });
+}

package/src/client/browser-utils.js

@@ -83,7 +83,7 @@ export function isNearViewport(element, root, marginPx) {
 }
 
 export function downloadBlob(blob, fileName, {
-  removeDelayMs = 30_000,
+  removeDelayMs = 1000,
   revokeDelayMs = removeDelayMs,
 } = {}) {
   const windowRef = getWindowRef();

package/src/client/domain/excalidraw-scene-reconcile.js

@@ -1,5 +1,6 @@
 export function buildReconciledExcalidrawSceneUpdate({
   appStateOverrides = {},
+  authoritative = false,
   currentAppState,
   currentElements = [],
   documentViewState = {},
@@ -10,7 +11,7 @@ export function buildReconciledExcalidrawSceneUpdate({
   scene,
   theme = 'dark',
 } = {}) {
-  const restoredElements = restoreElementsFn(scene?.elements || [], currentElements, {
+  const restoredElements = restoreElementsFn(scene?.elements || [], authoritative ? [] : currentElements, {
     repairBindings: true,
   });
   const restoredAppState = restoreAppStateFn(scene?.appState || {}, currentAppState);
@@ -27,7 +28,9 @@ export function buildReconciledExcalidrawSceneUpdate({
     )),
   );
   const update = {
-    elements: reconcileElementsFn(currentElements, restoredElements, currentAppState),
+    elements: authoritative
+      ? restoredElements
+      : reconcileElementsFn(currentElements, restoredElements, currentAppState),
   };
 
   if (Object.keys(appStateUpdate).length > 0) {

package/src/client/domain/excalidraw-scene.js

@@ -84,17 +84,6 @@ export function createExcalidrawExportOptions(scene, {
   };
 }
 
-export function buildStoredScene(elements, appState, files) {
-  return normalizeScene({
-    elements: elements.filter((element) => !element.isDeleted),
-    appState: {
-      gridSize: appState.gridSize ?? null,
-      viewBackgroundColor: appState.viewBackgroundColor ?? '#ffffff',
-    },
-    files: files || {},
-  });
-}
-
 export function buildLiveCollaborationScene(elements, appState, files) {
   return normalizeScene({
     elements: Array.isArray(elements) ? elements : [],

package/src/client/domain/file-search.js

@@ -40,6 +40,7 @@ export function createFileSearchEntry(filePath) {
   const rawFileName = String(filePath ?? '').split('/').pop() || String(filePath ?? '');
 
   return {
+    dirPath: displayName.includes('/') ? displayName.slice(0, displayName.lastIndexOf('/')) : '',
     displayName,
     fileName,
     filePath,

package/src/client/domain/hash-routes.js

@@ -9,6 +9,11 @@ export const HASH_ROUTE_KEYS = Object.freeze({
   gitHistory: 'git-history',
 });
 
+export function isGitHashRouteType(type) {
+  return String(type ?? '').startsWith('git-');
+}
+
+
 export function getHashParamsFromRaw(hash = '') {
   const rawHash = String(hash ?? '');
   const normalizedHash = rawHash.startsWith('#')

package/src/client/domain/highlight-runtime.js

@@ -0,0 +1,74 @@
+import hljs from 'highlight.js/lib/core';
+import bash from 'highlight.js/lib/languages/bash';
+import css from 'highlight.js/lib/languages/css';
+import javascript from 'highlight.js/lib/languages/javascript';
+import json from 'highlight.js/lib/languages/json';
+import markdown from 'highlight.js/lib/languages/markdown';
+import python from 'highlight.js/lib/languages/python';
+import sql from 'highlight.js/lib/languages/sql';
+import typescript from 'highlight.js/lib/languages/typescript';
+import xml from 'highlight.js/lib/languages/xml';
+import yaml from 'highlight.js/lib/languages/yaml';
+
+export const AUTO_HIGHLIGHT_LANGUAGES = [
+  'bash',
+  'css',
+  'javascript',
+  'json',
+  'markdown',
+  'python',
+  'sql',
+  'typescript',
+  'xml',
+  'yaml',
+];
+
+hljs.registerLanguage('bash', bash);
+hljs.registerLanguage('css', css);
+hljs.registerLanguage('javascript', javascript);
+hljs.registerLanguage('json', json);
+hljs.registerLanguage('markdown', markdown);
+hljs.registerLanguage('python', python);
+hljs.registerLanguage('sql', sql);
+hljs.registerLanguage('typescript', typescript);
+hljs.registerLanguage('xml', xml);
+hljs.registerLanguage('yaml', yaml);
+hljs.registerAliases(['cql', 'mariadb', 'mssql', 'mysql', 'plsql', 'sqlite'], { languageName: 'sql' });
+hljs.registerAliases(['ecmascript', 'node'], { languageName: 'javascript' });
+
+export { hljs };
+
+// Unchanged fences re-highlight on every preview compile while typing, so
+// memoize results. Huge one-off sources bypass the cache to bound memory.
+const HIGHLIGHT_CACHE_LIMIT = 200;
+const HIGHLIGHT_CACHE_MAX_SOURCE_CHARS = 20000;
+const highlightCache = new Map();
+
+export function getHighlightCacheSize() {
+  return highlightCache.size;
+}
+
+export function highlightFence(source, language, { ignoreIllegals = false } = {}) {
+  const text = String(source);
+  const cacheable = text.length <= HIGHLIGHT_CACHE_MAX_SOURCE_CHARS;
+  const cacheKey = cacheable ? `${language ?? ''}\n${ignoreIllegals ? 1 : 0}\n${text}` : null;
+  if (cacheKey) {
+    const cached = highlightCache.get(cacheKey);
+    if (cached !== undefined) {
+      return cached;
+    }
+  }
+
+  const result = language && hljs.getLanguage(language)
+    ? hljs.highlight(text, { ignoreIllegals, language }).value
+    : hljs.highlightAuto(text, AUTO_HIGHLIGHT_LANGUAGES).value;
+
+  if (cacheKey) {
+    if (highlightCache.size >= HIGHLIGHT_CACHE_LIMIT) {
+      highlightCache.delete(highlightCache.keys().next().value);
+    }
+    highlightCache.set(cacheKey, result);
+  }
+
+  return result;
+}

package/src/client/domain/lobby-chat.js

@@ -0,0 +1,2 @@
+export const LOBBY_CHAT_MESSAGE_MAX_LENGTH = 280;
+export const LOBBY_CHAT_MAX_MESSAGES = 40;

package/src/client/domain/markdown-math.js

@@ -0,0 +1,14 @@
+import katex from 'katex';
+import katexPluginModule from '@vscode/markdown-it-katex';
+
+const katexPlugin = katexPluginModule?.default ?? katexPluginModule;
+
+const RENDERED_MATH_PATTERN = /class="katex(?:-block|-error)?"/u;
+
+export function enableMarkdownMath(markdown) {
+  markdown.use(katexPlugin, { katex, strict: false, throwOnError: false, trust: false });
+}
+
+export function hasRenderedMath(html = '') {
+  return RENDERED_MATH_PATTERN.test(String(html ?? ''));
+}

package/src/client/domain/runtime-paths.js

@@ -58,8 +58,48 @@ function applyBasePath(basePath, pathValue) {
   return normalizedBasePath ? `${normalizedBasePath}/${normalizedPath}` : `/${normalizedPath}`;
 }
 
+export const ACTIVE_VAULT_STORAGE_KEY = 'collabmd.activeVault';
+
+// ponytail: agent/hosted/auth/plantuml/structurizr/test stay global; everything else is vault-scoped
+const VAULT_UNSCOPED_API_PATHS = ['/auth/', '/hosted/', '/agent/', '/test/', '/plantuml/', '/structurizr/'];
+
+function isVaultScopedApiPath(pathname) {
+  if (pathname === '/api' || pathname === '/api/' || pathname === '/api/vaults') {
+    return false;
+  }
+  const sub = pathname.startsWith('/api/') ? pathname.slice('/api'.length) : pathname;
+  return !VAULT_UNSCOPED_API_PATHS.some((prefix) => sub === prefix.slice(0, -1) || sub.startsWith(prefix));
+}
+
+export function getActiveVaultId(config = getClientRuntimeConfig()) {
+  const vaults = Array.isArray(config?.vaults) ? config.vaults.map((vault) => vault?.id).filter(Boolean) : [];
+  if (vaults.length === 0) {
+    return null;
+  }
+  try {
+    const stored = globalThis.window?.localStorage?.getItem(ACTIVE_VAULT_STORAGE_KEY);
+    if (stored && vaults.includes(stored)) {
+      return stored;
+    }
+  } catch {
+    // Ignore storage failures and fall back to the server default.
+  }
+  if (config?.activeVault && vaults.includes(config.activeVault)) {
+    return config.activeVault;
+  }
+  return vaults[0] ?? null;
+}
+
+export function setActiveVaultId(vaultId) {
+  try {
+    globalThis.window?.localStorage?.setItem(ACTIVE_VAULT_STORAGE_KEY, String(vaultId ?? ''));
+  } catch {
+    // Ignore storage failures; the server default still applies.
+  }
+}
 export function getClientRuntimeConfig() {
   const rawConfig = {
+    activeVault: '',
     agentAccess: {
       enabled: false,
       endpoint: '',
@@ -92,6 +132,7 @@ export function getClientRuntimeConfig() {
       version: '',
     },
     structurizrEnabled: false,
+    vaults: [],
     wikiLinkAutoCreate: true,
     wsBasePath: '/ws',
     ...(window.__COLLABMD_CONFIG__ ?? {}),
@@ -142,11 +183,17 @@ export function resolveApiUrl(pathValue = '/', config = getClientRuntimeConfig()
     return resolveAppPath('/api', config);
   }
 
-  if (normalizedPath.startsWith('/api')) {
-    return resolveAppPath(normalizedPath, config);
+  const apiPath = normalizedPath.startsWith('/api')
+    ? normalizedPath
+    : `/api${normalizedPath.startsWith('/') ? normalizedPath : `/${normalizedPath}`}`;
+  const queryIndex = apiPath.indexOf('?');
+  const pathname = queryIndex === -1 ? apiPath : apiPath.slice(0, queryIndex);
+  const query = queryIndex === -1 ? '' : apiPath.slice(queryIndex);
+  const vaultId = getActiveVaultId(config);
+  if (vaultId && isVaultScopedApiPath(pathname)) {
+    return resolveAppPath(`/api/v/${vaultId}${pathname.slice('/api'.length)}${query}`, config);
   }
-
-  return resolveAppPath(`/api${normalizedPath.startsWith('/') ? normalizedPath : `/${normalizedPath}`}`, config);
+  return resolveAppPath(`${pathname}${query}`, config);
 }
 
 export function resolveWsServerOverride(config = getClientRuntimeConfig()) {
@@ -172,15 +219,17 @@ export function resolveWsServerOverride(config = getClientRuntimeConfig()) {
 }
 
 export function resolveWsBaseUrl(config = getClientRuntimeConfig()) {
+  const vaultId = getActiveVaultId(config);
+  const vaultSuffix = vaultId ? `/v/${vaultId}` : '';
   const serverOverride = resolveWsServerOverride(config);
   if (serverOverride) {
-    return serverOverride;
+    return `${serverOverride}${vaultSuffix}`;
   }
 
   if (config.publicWsBaseUrl) {
-    return trimTrailingSlash(config.publicWsBaseUrl);
+    return `${trimTrailingSlash(config.publicWsBaseUrl)}${vaultSuffix}`;
   }
 
   const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
-  return `${protocol}//${window.location.host}${resolveAppPath(config.wsBasePath, config)}`;
+  return `${protocol}//${window.location.host}${resolveAppPath(`${config.wsBasePath}${vaultSuffix}`, config)}`;
 }

package/src/client/domain/vault-utils.js

@@ -18,6 +18,17 @@ export function escapeHtml(text) {
     .replace(/'/g, ''');
 }
 
+/**
+ * Builds a document fragment from an HTML string for a single
+ * replaceChildren() call. Escape untrusted parts before calling.
+ *
+ * @param {string} markup — trusted HTML markup
+ * @returns {DocumentFragment} parsed fragment
+ */
+export function createFragment(markup) {
+  return document.createRange().createContextualFragment(markup);
+}
+
 /**
  * Clamps a numeric value between a minimum and maximum bound.
  *