collabmd 0.1.49 → 0.1.51

package/src/client/application/preview-renderer.js

@@ -1,17 +1,17 @@
 import { MermaidPreviewHydrator } from './mermaid-preview-hydrator.js';
 import { PlantUmlPreviewHydrator } from './plantuml-preview-hydrator.js';
 import { DiagramChrome } from './diagram-chrome.js';
-import { IDLE_RENDER_TIMEOUT_MS } from './preview-diagram-utils.js';
 import { PreviewRenderExecutor } from './preview-render-executor.js';
 import { isLargeDocumentStats } from './preview-render-profile.js';
 import { PreviewRenderScheduler } from './preview-render-scheduler.js';
 import { resolveApiUrl } from '../domain/runtime-paths.js';
-
 export class PreviewRenderer {
   constructor({
     getContent,
     getFileList,
+    getPreviewVisible = null,
     getSourceFilePath,
+    getTheme = null,
     getWikiLinkAutoCreate = null,
     loadFileSource = null,
     onAfterRenderCommit,
@@ -26,7 +26,9 @@ export class PreviewRenderer {
   }) {
     this.getContent = getContent;
     this.getFileList = getFileList;
+    this.getPreviewVisible = getPreviewVisible;
     this.getSourceFilePath = getSourceFilePath;
+    this.getTheme = getTheme;
     this.getWikiLinkAutoCreate = getWikiLinkAutoCreate;
     this.loadFileSource = loadFileSource;
     this.onAfterRenderCommit = onAfterRenderCommit;
@@ -47,6 +49,7 @@ export class PreviewRenderer {
     this.isLargeDocument = false;
     this.hydrationPaused = false;
     this.frontmatterCollapsed = false;
+    this.previewRenderStale = false;
 
     this.handlePreviewClick = (event) => {
       const frontmatterToggle = event.target.closest('.frontmatter-toggle');
@@ -111,7 +114,6 @@ export class PreviewRenderer {
       getFileList: () => this.getFileList?.() ?? [],
       getSourceFilePath: () => this.getSourceFilePath?.() ?? '',
       getWikiLinkAutoCreate: () => this.getWikiLinkAutoCreate?.() ?? true,
-      idleTimeoutMs: IDLE_RENDER_TIMEOUT_MS,
     });
 
     this.previewElement?.addEventListener('click', this.handlePreviewClick);
@@ -204,8 +206,25 @@ export class PreviewRenderer {
     }
     this.mermaidHydrator.applyTheme(theme);
   }
+  markStale() {
+    this.previewRenderStale = true;
+    this.renderScheduler.cancel();
+  }
 
   queueRender() {
+    if (!(this.getPreviewVisible?.() ?? true)) {
+      this.markStale();
+      return;
+    }
+
+    this.previewRenderStale = false;
+    this._deferredPreviewStylesPromise ??= Promise.all([
+      import('./highlight-theme.js').then(({ ensureHighlightThemeStylesheet }) => {
+        ensureHighlightThemeStylesheet();
+        this.applyTheme(this.getTheme?.() ?? 'dark');
+      }),
+      import('../styles/deferred-preview.css'),
+    ]);
     const markdownText = this.getContent();
     this.renderScheduler.cancel();
     this.mermaidHydrator.markPending();
@@ -215,12 +234,13 @@ export class PreviewRenderer {
     this.renderScheduler.queue({
       markdownText,
       onRenderRequested: (queuedText, renderVersion) => {
-        void this.render(queuedText, renderVersion);
+        void this._deferredPreviewStylesPromise.then(() => this.render(queuedText, renderVersion));
       },
       renderVersion: scheduledVersion,
     });
   }
 
+
   async render(markdownText = this.getContent(), renderVersion = this.pendingRenderVersion) {
     if (!this.previewElement) {
       return;
@@ -291,9 +311,6 @@ export class PreviewRenderer {
     this.updateHydrationPhase();
   }
 
-  scheduleWorkerPrewarm({ timeout = IDLE_RENDER_TIMEOUT_MS } = {}) {
-    this.renderExecutor.schedulePrewarm({ timeout });
-  }
 
   commitBaseRender({ html, stats }, renderVersion) {
     this.activeRenderVersion = renderVersion;

package/src/client/application/workspace-coordinator.js

@@ -269,6 +269,26 @@ export class WorkspaceCoordinator {
       });
       return true;
     }
+    let fileOpenReady = false;
+    let liveSyncComplete = false;
+    const bootstrapPromise = this.loadBootstrapContent
+      ? (async () => {
+        this.reportFileOpenMetric('bootstrap_fetch_started', loadToken);
+        try {
+          const content = await this.loadBootstrapContent(filePath);
+          this.reportFileOpenMetric('bootstrap_fetch_completed', loadToken, {
+            found: content !== null,
+          });
+          return content;
+        } catch (error) {
+          this.reportFileOpenMetric('bootstrap_fetch_completed', loadToken, {
+            error: error.message,
+            found: false,
+          });
+          return null;
+        }
+      })()
+      : Promise.resolve(null);
 
     const EditorSession = await this.loadEditorSessionClass();
     const session = this.createEditorSession(EditorSession, {
@@ -303,10 +323,7 @@ export class WorkspaceCoordinator {
     this.onSessionAssigned?.(session);
 
     try {
-      let fileOpenReady = false;
       let fileOpenFinalized = false;
-      let liveSyncComplete = false;
-
       const readySession = async (reason) => {
         if (fileOpenReady || loadToken !== this.stateStore.sessionLoadToken) {
           return;
@@ -335,24 +352,6 @@ export class WorkspaceCoordinator {
         });
       };
 
-      const bootstrapPromise = this.loadBootstrapContent
-        ? (async () => {
-          this.reportFileOpenMetric('bootstrap_fetch_started', loadToken);
-          try {
-            const content = await this.loadBootstrapContent(filePath);
-            this.reportFileOpenMetric('bootstrap_fetch_completed', loadToken, {
-              found: content !== null,
-            });
-            return content;
-          } catch (error) {
-            this.reportFileOpenMetric('bootstrap_fetch_completed', loadToken, {
-              error: error.message,
-              found: false,
-            });
-            return null;
-          }
-        })()
-        : Promise.resolve(null);
 
       const initializePromise = session.initialize(filePath);
       const liveSyncPromise = (async () => {

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 }) => {
@@ -216,7 +237,6 @@ export class CollabMdAppShell {
             'edit_excalidraw',
             'inspect_excalidraw',
             'read_document',
-            'render_excalidraw',
             'verify_excalidraw',
           ].includes(name)
           || input.path !== this.currentFilePath
@@ -244,6 +264,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 }) => {
@@ -308,6 +340,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 +361,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 +379,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 +387,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 +456,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 +612,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 +623,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 +648,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 +832,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/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/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,47 @@
+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 };
+
+export function highlightFence(source, language, { ignoreIllegals = false } = {}) {
+  if (language && hljs.getLanguage(language)) {
+    return hljs.highlight(source, { ignoreIllegals, language }).value;
+  }
+
+  return hljs.highlightAuto(source, AUTO_HIGHLIGHT_LANGUAGES).value;
+}

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/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)}`;
 }