@andespindola/brainlink 0.1.0-beta.41 → 0.1.0-beta.43

package/dist/application/frontend/client-worker-js.js

@@ -0,0 +1,66 @@
+export const createClientWorkerJs = () => `const normalize = value => String(value || '')
+  .normalize('NFKD')
+  .replace(/\\p{Diacritic}/gu, '')
+  .toLowerCase()
+
+let nodeIndex = []
+
+const toNodeIndex = nodes =>
+  (Array.isArray(nodes) ? nodes : [])
+    .map(node => {
+      const id = typeof node.id === 'string' ? node.id : ''
+      if (!id) {
+        return null
+      }
+      const title = normalize(node.title)
+      const path = normalize(node.path)
+      const tags = Array.isArray(node.tags) ? node.tags.map(tag => normalize(tag)) : []
+      return {
+        id,
+        text: [title, path, ...tags].join(' ')
+      }
+    })
+    .filter(Boolean)
+
+const scoreText = (text, query) => {
+  if (!query) return 0
+  if (!text.includes(query)) return 0
+  if (text.startsWith(query)) return 4
+  return 1
+}
+
+const filterIds = (query, limit) => {
+  const normalizedQuery = normalize(query).trim()
+  if (!normalizedQuery) {
+    return []
+  }
+  const rows = []
+  for (let index = 0; index < nodeIndex.length; index += 1) {
+    const row = nodeIndex[index]
+    const score = scoreText(row.text, normalizedQuery)
+    if (score > 0) {
+      rows.push({ id: row.id, score })
+    }
+  }
+  rows.sort((left, right) => right.score - left.score || left.id.localeCompare(right.id))
+  return rows.slice(0, Math.max(1, Number.isFinite(limit) ? limit : rows.length)).map(row => row.id)
+}
+
+self.onmessage = event => {
+  const payload = event.data
+  if (!payload || typeof payload !== 'object') {
+    return
+  }
+  if (payload.type === 'load-nodes') {
+    nodeIndex = toNodeIndex(payload.nodes)
+    return
+  }
+  if (payload.type === 'filter') {
+    const token = payload.token
+    const ids = filterIds(payload.query, payload.limit)
+    self.postMessage({ type: 'filter-result', token, ids })
+  }
+}
+
+self.postMessage({ type: 'ready' })
+`;

package/dist/application/index-vault.js

@@ -97,12 +97,33 @@ const readChangedDocuments = async (absoluteVaultPath, changedSummaries) => {
     return new Map(parsed.map((document) => [document.path, document]));
 };
 export const indexVault = async (vaultPath) => {
+    return indexVaultWithOptions(vaultPath, {});
+};
+export const indexVaultWithOptions = async (vaultPath, options) => {
+    const startedAt = process.hrtime.bigint();
+    const elapsedMs = () => Number(process.hrtime.bigint() - startedAt) / 1_000_000;
+    const emit = (phase, status, message, details) => {
+        options.onProgress?.({
+            phase,
+            status,
+            message,
+            elapsedMs: elapsedMs(),
+            timestamp: new Date().toISOString(),
+            details
+        });
+    };
+    emit('start', 'start', 'Indexing started');
     const absoluteVaultPath = await ensureVault(vaultPath);
     const config = await loadBrainlinkConfig();
+    emit('scan', 'start', 'Scanning markdown files');
     const [summaries, previousState] = await Promise.all([
         readMarkdownFileSummaries(absoluteVaultPath),
         readIndexState(absoluteVaultPath)
     ]);
+    emit('scan', 'finish', 'Scan complete', {
+        markdownFiles: summaries.length,
+        hasPreviousState: previousState != null
+    });
     const index = openFileIndex(absoluteVaultPath);
     try {
         const existingIndexedDocuments = await index.getIndexedDocuments();
@@ -133,10 +154,28 @@ export const indexVault = async (vaultPath) => {
             !hasDeletes &&
             existingIndexedDocuments.length === summaries.length &&
             previousState != null) {
-            return toIndexResult(existingIndexedDocuments);
+            const result = {
+                ...toIndexResult(existingIndexedDocuments),
+                elapsedMs: elapsedMs(),
+                changedDocumentCount: 0,
+                packs: {
+                    rebuilt: false,
+                    reason: 'No changes detected'
+                }
+            };
+            emit('complete', 'skip', 'Index skipped: no changes detected', {
+                elapsedMs: result.elapsedMs
+            });
+            return result;
         }
         const changedSummaries = summaries.filter((summary) => changedPaths.has(summary.relativePath));
+        emit('parse', 'start', 'Parsing changed markdown files', {
+            changedFiles: changedSummaries.length
+        });
         const changedDocumentsByPath = await readChangedDocuments(absoluteVaultPath, changedSummaries);
+        emit('parse', 'finish', 'Parse complete', {
+            changedDocuments: changedDocumentsByPath.size
+        });
         const documents = summaries.flatMap((summary) => {
             const changed = changedDocumentsByPath.get(summary.relativePath);
             if (changed) {
@@ -146,9 +185,15 @@ export const indexVault = async (vaultPath) => {
             return existing ? [existing.document] : [];
         });
         const titleMaps = createTitleMaps(documents);
+        emit('embed', 'start', 'Embedding changed chunks', {
+            changedDocuments: changedDocumentsByPath.size
+        });
         const changedIndexedDocuments = changedDocumentsByPath.size > 0
             ? await embedIndexedDocuments(Array.from(changedDocumentsByPath.values()).map((document) => createIndexedDocument(document, createScopedTitleResolver(document, titleMaps), config.chunkSize)), config.embeddingProvider)
             : [];
+        emit('embed', changedDocumentsByPath.size > 0 ? 'finish' : 'skip', changedDocumentsByPath.size > 0 ? 'Embedding complete' : 'Embedding skipped', {
+            changedIndexedDocuments: changedIndexedDocuments.length
+        });
         const changedIndexedByPath = new Map(changedIndexedDocuments.map((document) => [document.document.path, document]));
         const needsRelink = settingsChanged || hasDeletes || changedPaths.size > 0;
         const indexedDocuments = documents.map((document) => {
@@ -162,8 +207,12 @@ export const indexVault = async (vaultPath) => {
             }
             return needsRelink ? relinkIndexedDocument(existing, titleMaps) : existing;
         });
+        emit('persist', 'start', 'Persisting index');
         await index.reset();
         await index.saveDocuments(indexedDocuments);
+        emit('persist', 'finish', 'Index persisted', {
+            indexedDocuments: indexedDocuments.length
+        });
         const existingPackManifest = await hasPackManifest(absoluteVaultPath);
         const changedCount = changedPaths.size;
         const documentCount = Math.max(indexedDocuments.length, 1);
@@ -176,21 +225,78 @@ export const indexVault = async (vaultPath) => {
             changedCount >= 400 ||
             changeRatio >= 0.04 ||
             pendingPackChanges >= 1200;
+        let packResult;
+        const packReason = !existingPackManifest
+            ? 'Missing pack manifest'
+            : settingsChanged
+                ? 'Index settings changed'
+                : hasDeletes
+                    ? 'Document deletions detected'
+                    : changedCount >= 400
+                        ? 'Changed file count threshold reached'
+                        : changeRatio >= 0.04
+                            ? 'Change ratio threshold reached'
+                            : pendingPackChanges >= 1200
+                                ? 'Pending pack changes threshold reached'
+                                : 'Pack rebuild skipped';
         if (shouldRebuildPacks) {
+            emit('packs', 'start', 'Rebuilding compressed search packs', {
+                reason: packReason
+            });
             try {
-                await buildSearchPacks(absoluteVaultPath, indexedDocuments);
+                packResult = await buildSearchPacks(absoluteVaultPath, indexedDocuments);
+                emit('packs', 'finish', 'Compressed packs rebuilt', {
+                    reason: packReason,
+                    packCount: packResult.packCount,
+                    recordCount: packResult.recordCount,
+                    durationMs: packResult.durationMs,
+                    compressionRatio: packResult.compression.ratio
+                });
             }
             catch {
                 // Pack generation is best-effort. The JSON index remains the primary path.
+                emit('packs', 'skip', 'Pack rebuild failed; continuing with JSON index', {
+                    reason: packReason
+                });
             }
         }
+        else {
+            emit('packs', 'skip', 'Pack rebuild not required', {
+                reason: packReason
+            });
+        }
+        const packsRebuilt = packResult != null;
+        const packResultReason = shouldRebuildPacks && !packsRebuilt ? `${packReason} (failed)` : packReason;
         await writeIndexState(absoluteVaultPath, {
             chunkSize: config.chunkSize,
             embeddingProvider: config.embeddingProvider,
             files: currentSnapshot,
-            pendingPackChanges: shouldRebuildPacks ? 0 : pendingPackChanges
+            pendingPackChanges: packsRebuilt ? 0 : pendingPackChanges
+        });
+        const result = {
+            ...toIndexResult(indexedDocuments),
+            elapsedMs: elapsedMs(),
+            changedDocumentCount: changedDocumentsByPath.size,
+            packs: {
+                rebuilt: packsRebuilt,
+                reason: packResultReason,
+                ...(packResult
+                    ? {
+                        packCount: packResult.packCount,
+                        recordCount: packResult.recordCount,
+                        durationMs: packResult.durationMs,
+                        compression: packResult.compression
+                    }
+                    : {})
+            }
+        };
+        emit('complete', 'finish', 'Indexing complete', {
+            documentCount: result.documentCount,
+            chunkCount: result.chunkCount,
+            linkCount: result.linkCount,
+            elapsedMs: result.elapsedMs
         });
-        return toIndexResult(indexedDocuments);
+        return result;
     }
     finally {
         index.close();

package/dist/application/server/routes.js

@@ -11,6 +11,7 @@ import { loadBrainlinkConfig, sanitizeSearchMode } from '../../infrastructure/co
 import { createClientCss } from '../frontend/client-css.js';
 import { createClientHtml } from '../frontend/client-html.js';
 import { createClientJs } from '../frontend/client-js.js';
+import { createClientWorkerJs } from '../frontend/client-worker-js.js';
 import { contentTypes, createJsonResponse, isReadMethod, parsePositiveInteger } from './http.js';
 const readSearchMode = async (url) => {
     const config = await loadBrainlinkConfig();
@@ -51,10 +52,41 @@ const sameEntityTag = (candidate, signature) => {
     return decodeEntityTag(candidate) === signature;
 };
 const readAgentQuery = (url) => url.searchParams.get('agent') ?? undefined;
+const compactGraphLayoutThreshold = 12_000;
+const compactGraphLayoutEdgeLimit = 60_000;
+const compactGraphLayoutEdgeLimitFor = (nodeCount) => {
+    if (nodeCount > 100_000)
+        return 15_000;
+    if (nodeCount > 50_000)
+        return 22_000;
+    if (nodeCount > 25_000)
+        return 30_000;
+    return compactGraphLayoutEdgeLimit;
+};
 const stripLayoutContent = (layout) => ({
     ...layout,
     nodes: layout.nodes.map(({ content, ...node }) => node)
 });
+const compactLayoutPayload = (layout) => {
+    const edgeLimit = compactGraphLayoutEdgeLimitFor(layout.nodes.length);
+    const compactNodes = layout.nodes.map((node) => [node.id, node.title, node.x, node.y, node.group, node.segment]);
+    const compactEdges = [...layout.edges]
+        .sort((left, right) => (right.weight ?? 1) - (left.weight ?? 1))
+        .slice(0, edgeLimit)
+        .map((edge) => [edge.source, edge.target, edge.weight, edge.priority]);
+    return {
+        compact: true,
+        layout: {
+            nodes: compactNodes,
+            edges: compactEdges
+        },
+        totals: {
+            nodes: layout.nodes.length,
+            edges: layout.edges.length
+        }
+    };
+};
+const encodeLayoutPayload = (layout) => layout.nodes.length > compactGraphLayoutThreshold ? compactLayoutPayload(layout) : { compact: false, layout: stripLayoutContent(layout) };
 export const route = async (request, url, vaultPath) => {
     if (isReadMethod(request) && (url.pathname === '/' || url.pathname === '/index.html')) {
         return createResponse(createClientHtml(), 200, contentTypes['.html']);
@@ -65,6 +97,9 @@ export const route = async (request, url, vaultPath) => {
     if (isReadMethod(request) && url.pathname === '/app.js') {
         return createResponse(createClientJs(), 200, contentTypes['.js']);
     }
+    if (isReadMethod(request) && url.pathname === '/app-worker.js') {
+        return createResponse(createClientWorkerJs(), 200, contentTypes['.js']);
+    }
     if (isReadMethod(request) && url.pathname === '/api/graph') {
         return createResponse(createJsonResponse(await getGraph(vaultPath, readAgentQuery(url))), 200, contentTypes['.json']);
     }
@@ -73,7 +108,7 @@ export const route = async (request, url, vaultPath) => {
         const requestEtags = request.headers['if-none-match'];
         const notModified = sameEntityTag(requestEtags, signature);
         const etag = encodeEntityTag(signature);
-        const body = createJsonResponse({ signature, layout: stripLayoutContent(layout) });
+        const body = createJsonResponse({ signature, ...encodeLayoutPayload(layout) });
         const jsonResponse = createResponse(body, 200, contentTypes['.json']);
         const notModifiedResponse = createResponse('', 304, contentTypes['.json']);
         if (notModified) {

package/dist/application/start-server.js

@@ -1,9 +1,78 @@
 import { createServer } from 'node:http';
+import { brotliCompressSync, constants, gzipSync } from 'node:zlib';
 import { indexVault } from './index-vault.js';
 import { startVaultWatcher } from './watch-vault.js';
 import { assertLoopbackHost } from './server/host-security.js';
 import { contentTypes, createJsonResponse, isHttpError } from './server/http.js';
 import { route } from './server/routes.js';
+const compressionThresholdBytes = 1024;
+const normalizeEncodingToken = (value) => value.trim().toLowerCase();
+const supportsEncoding = (acceptEncoding, target) => {
+    if (!acceptEncoding) {
+        return false;
+    }
+    return acceptEncoding
+        .split(',')
+        .map((entry) => entry.split(';')[0] ?? '')
+        .map(normalizeEncodingToken)
+        .includes(target);
+};
+const isCompressibleContentType = (contentType) => {
+    const normalized = contentType?.toLowerCase() ?? '';
+    return (normalized.includes('application/json') ||
+        normalized.includes('text/javascript') ||
+        normalized.includes('text/css') ||
+        normalized.includes('text/html') ||
+        normalized.startsWith('text/'));
+};
+const maybeCompressResponse = (requestHeaders, statusCode, headers, body) => {
+    if (statusCode === 204 || statusCode === 304) {
+        return { headers, body: '' };
+    }
+    if (!isCompressibleContentType(headers['content-type'])) {
+        return { headers, body };
+    }
+    const bodyBuffer = Buffer.from(body, 'utf8');
+    if (bodyBuffer.byteLength < compressionThresholdBytes) {
+        return { headers, body };
+    }
+    if (headers['content-encoding']) {
+        return { headers, body };
+    }
+    const acceptEncodingHeader = Array.isArray(requestHeaders['accept-encoding'])
+        ? requestHeaders['accept-encoding'].join(',')
+        : requestHeaders['accept-encoding'];
+    const vary = headers.vary ? `${headers.vary}, Accept-Encoding` : 'Accept-Encoding';
+    const withVary = {
+        ...headers,
+        vary
+    };
+    if (supportsEncoding(acceptEncodingHeader, 'br')) {
+        return {
+            headers: {
+                ...withVary,
+                'content-encoding': 'br'
+            },
+            body: brotliCompressSync(bodyBuffer, {
+                params: {
+                    [constants.BROTLI_PARAM_QUALITY]: 5
+                }
+            })
+        };
+    }
+    if (supportsEncoding(acceptEncodingHeader, 'gzip')) {
+        return {
+            headers: {
+                ...withVary,
+                'content-encoding': 'gzip'
+            },
+            body: gzipSync(bodyBuffer, {
+                level: 6
+            })
+        };
+    }
+    return { headers: withVary, body };
+};
 export const startServer = async (input) => {
     assertLoopbackHost(input.host);
     if (input.shouldIndex) {
@@ -19,14 +88,16 @@ export const startServer = async (input) => {
         const url = new URL(request.url ?? '/', `http://${request.headers.host ?? input.host}`);
         route(request, url, input.vaultPath)
             .then((result) => {
-            response.writeHead(result.statusCode, result.headers);
-            response.end(result.body);
+            const encoded = maybeCompressResponse(request.headers, result.statusCode, result.headers, result.body);
+            response.writeHead(result.statusCode, encoded.headers);
+            response.end(encoded.body);
         })
             .catch((error) => {
             const message = error instanceof Error ? error.message : String(error);
             const statusCode = isHttpError(error) ? error.statusCode : 500;
-            response.writeHead(statusCode, { 'content-type': contentTypes['.json'] });
-            response.end(createJsonResponse({ error: message }));
+            const fallback = maybeCompressResponse(request.headers, statusCode, { 'content-type': contentTypes['.json'] }, createJsonResponse({ error: message }));
+            response.writeHead(statusCode, fallback.headers);
+            response.end(fallback.body);
         });
     });
     await new Promise((resolve, reject) => {

package/dist/application/watch-vault.js

@@ -1,5 +1,5 @@
 import { watch } from 'node:fs';
-import { indexVault } from './index-vault.js';
+import { indexVaultWithOptions } from './index-vault.js';
 import { isBucketVaultPath, resolveVaultPath } from '../infrastructure/file-system-vault.js';
 const shouldIgnore = (filename) => {
     if (!filename) {
@@ -14,6 +14,27 @@ export const startVaultWatcher = (input) => {
     const absoluteVaultPath = resolveVaultPath(input.vaultPath);
     const debounceMs = input.debounceMs ?? 350;
     let timeout = null;
+    let running = false;
+    let pending = false;
+    const runIndex = () => {
+        if (running) {
+            pending = true;
+            return;
+        }
+        running = true;
+        indexVaultWithOptions(absoluteVaultPath, {
+            onProgress: input.onProgress
+        })
+            .then(input.onIndex)
+            .catch(input.onError)
+            .finally(() => {
+            running = false;
+            if (pending) {
+                pending = false;
+                runIndex();
+            }
+        });
+    };
     const schedule = (filename) => {
         if (shouldIgnore(filename)) {
             return;
@@ -22,7 +43,7 @@ export const startVaultWatcher = (input) => {
             clearTimeout(timeout);
         }
         timeout = setTimeout(() => {
-            indexVault(absoluteVaultPath).then(input.onIndex).catch(input.onError);
+            runIndex();
         }, debounceMs);
     };
     const watcher = watch(absoluteVaultPath, { recursive: true }, (_eventType, filename) => {

package/dist/cli/commands/write-commands.js

@@ -7,7 +7,7 @@ import { addNoteWithMetadata } from '../../application/add-note.js';
 import { buildContextPackage } from '../../application/build-context.js';
 import { resolveDuplicateNotes, scanDuplicateNotes } from '../../application/dedupe-notes.js';
 import { importLegacySqliteDatabase } from '../../application/import-legacy-sqlite.js';
-import { indexVault } from '../../application/index-vault.js';
+import { indexVault, indexVaultWithOptions } from '../../application/index-vault.js';
 import { migrateVaultContent, planVaultMigration, previewVaultMigration, shouldMigrateDefaultVault } from '../../application/migrate-vault.js';
 import { startServer } from '../../application/start-server.js';
 import { startVaultWatcher } from '../../application/watch-vault.js';
@@ -37,9 +37,59 @@ const parseScore = (value, fallback) => {
     }
     return parsed;
 };
-const spawnDetached = (command, args) => {
+const formatBytes = (bytes) => {
+    if (!Number.isFinite(bytes) || bytes == null) {
+        return 'n/a';
+    }
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ['KB', 'MB', 'GB', 'TB'];
+    let value = bytes / 1024;
+    let unitIndex = 0;
+    while (value >= 1024 && unitIndex < units.length - 1) {
+        value /= 1024;
+        unitIndex += 1;
+    }
+    return `${value.toFixed(value >= 10 ? 1 : 2)} ${units[unitIndex]}`;
+};
+const formatMs = (value) => Number.isFinite(value) && value != null ? `${value.toFixed(value >= 100 ? 0 : 1)}ms` : 'n/a';
+const benchEventLabel = (event) => `${event.phase}:${event.status}`;
+const printBenchRealtimeEvent = (json, event) => {
+    print(json, {
+        event: 'bench-progress',
+        ...event
+    }, () => `[bench] ${benchEventLabel(event)} ${event.message} (${formatMs(event.elapsedMs)})`);
+};
+const printBenchSummary = (json, trigger, vault, result) => {
+    print(json, {
+        event: 'bench-result',
+        trigger,
+        vault,
+        result
+    }, () => {
+        const packs = result.packs;
+        const compression = packs?.compression;
+        const savedPercent = compression && compression.inputBytes > 0
+            ? `${((1 - compression.ratio) * 100).toFixed(1)}%`
+            : 'n/a';
+        return [
+            `[bench] trigger=${trigger}`,
+            `documents=${result.documentCount} chunks=${result.chunkCount} links=${result.linkCount}`,
+            `changedDocuments=${result.changedDocumentCount ?? 0} totalElapsed=${formatMs(result.elapsedMs)}`,
+            `packsRebuilt=${packs?.rebuilt ? 'yes' : 'no'} reason=${packs?.reason ?? 'n/a'}`,
+            packs?.rebuilt
+                ? `packCount=${packs.packCount ?? 0} packDuration=${formatMs(packs.durationMs)} input=${formatBytes(compression?.inputBytes)} output=${formatBytes(compression?.outputBytes)} saved=${savedPercent}`
+                : 'packCompression=n/a'
+        ].join('\n');
+    });
+};
+const spawnDetached = (command, args, envOverrides) => {
     try {
-        const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+        const child = spawn(command, args, {
+            detached: true,
+            stdio: 'ignore',
+            env: envOverrides ? { ...process.env, ...envOverrides } : process.env
+        });
         child.unref();
         return true;
     }
@@ -219,6 +269,7 @@ const commandExists = (command) => {
 };
 const envFlagEnabled = (name) => process.env[name] === '1' || process.env[name] === 'true';
 const spawnAnyDetached = (candidates) => candidates.some(([command, args]) => spawnDetached(command, args));
+const spawnAnyDetachedWithEnv = (candidates) => candidates.some(([command, args, env]) => spawnDetached(command, args, env));
 const windowsStartCandidates = (program, args = []) => [
     ['cmd', ['/c', 'start', '', program, ...args]]
 ];
@@ -318,6 +369,16 @@ const openGraphInAppWindow = (url) => {
         ]);
     }
     const appArgument = `--app=${url}`;
+    const linuxChromiumStableFlags = [
+        '--ozone-platform=x11',
+        '--disable-gpu',
+        '--disable-features=Vulkan,VaapiVideoDecoder',
+        '--disable-background-networking'
+    ];
+    const linuxChromiumEnv = {
+        GDK_BACKEND: 'x11',
+        OZONE_PLATFORM: 'x11'
+    };
     const linuxAppWindowCandidates = [
         'microsoft-edge',
         'microsoft-edge-stable',
@@ -327,7 +388,11 @@ const openGraphInAppWindow = (url) => {
         'chromium-browser',
         'brave-browser'
     ].filter((candidate) => commandExists(candidate));
-    return spawnAnyDetached(linuxAppWindowCandidates.map((command) => [command, [appArgument, '--new-window']]));
+    return spawnAnyDetachedWithEnv(linuxAppWindowCandidates.map((command) => [
+        command,
+        [...linuxChromiumStableFlags, appArgument, '--new-window'],
+        linuxChromiumEnv
+    ]));
 };
 const openGraphInDetectedBrowser = (url) => {
     if (platform() === 'win32') {
@@ -339,18 +404,28 @@ const openGraphInDetectedBrowser = (url) => {
             ...windowsStartCandidates('brave', [url])
         ]);
     }
+    const linuxChromiumStableFlags = [
+        '--ozone-platform=x11',
+        '--disable-gpu',
+        '--disable-features=Vulkan,VaapiVideoDecoder',
+        '--disable-background-networking'
+    ];
+    const linuxChromiumEnv = {
+        GDK_BACKEND: 'x11',
+        OZONE_PLATFORM: 'x11'
+    };
     const linuxBrowserCandidates = [
-        ['microsoft-edge', [url]],
-        ['microsoft-edge-stable', [url]],
-        ['google-chrome', [url]],
-        ['google-chrome-stable', [url]],
-        ['chromium', [url]],
-        ['chromium-browser', [url]],
-        ['brave-browser', [url]],
-        ['firefox', ['-new-window', url]]
+        ['microsoft-edge', [...linuxChromiumStableFlags, url], linuxChromiumEnv],
+        ['microsoft-edge-stable', [...linuxChromiumStableFlags, url], linuxChromiumEnv],
+        ['google-chrome', [...linuxChromiumStableFlags, url], linuxChromiumEnv],
+        ['google-chrome-stable', [...linuxChromiumStableFlags, url], linuxChromiumEnv],
+        ['chromium', [...linuxChromiumStableFlags, url], linuxChromiumEnv],
+        ['chromium-browser', [...linuxChromiumStableFlags, url], linuxChromiumEnv],
+        ['brave-browser', [...linuxChromiumStableFlags, url], linuxChromiumEnv],
+        ['firefox', ['-new-window', url], undefined]
     ];
     const available = linuxBrowserCandidates.filter(([command]) => commandExists(command));
-    return spawnAnyDetached(available);
+    return spawnAnyDetachedWithEnv(available);
 };
 const openUrlInUi = (url, parentPid) => {
     const openDisabled = process.env.BRAINLINK_NO_BROWSER === '1' ||
@@ -605,6 +680,58 @@ export const registerWriteCommands = (program) => {
         const result = await indexVault(resolved.vault);
         print(options.json, result, () => `Indexed ${result.documentCount} documents, ${result.chunkCount} chunks and ${result.linkCount} links`);
     });
+    program
+        .command('bench')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-w, --watch', 'watch markdown changes and re-run benchmark in realtime')
+        .option('--debounce <ms>', 'watch debounce in milliseconds', '350')
+        .option('--json', 'print machine-readable JSON events')
+        .description('benchmark indexing in realtime, including compressed pack behavior')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const emitProgress = (event) => {
+            printBenchRealtimeEvent(options.json, event);
+        };
+        const printBenchError = (error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            print(options.json, { event: 'bench-error', message }, () => `[bench] error ${message}`);
+        };
+        const runAndPrint = async (trigger) => {
+            const result = await indexVaultWithOptions(resolved.vault, {
+                onProgress: emitProgress
+            });
+            printBenchSummary(options.json, trigger, resolved.vault, result);
+            return result;
+        };
+        if (!options.watch) {
+            await runAndPrint('manual');
+            return;
+        }
+        const debounceMs = parsePositiveInteger(options.debounce ?? '350', 350);
+        await runAndPrint('manual');
+        print(options.json, {
+            event: 'bench-watching',
+            vault: resolved.vault,
+            debounceMs
+        }, () => `[bench] watching ${resolved.vault} (debounce=${debounceMs}ms)`);
+        const watcher = startVaultWatcher({
+            vaultPath: resolved.vault,
+            debounceMs,
+            onProgress: emitProgress,
+            onIndex: (result) => {
+                printBenchSummary(options.json, 'watch', resolved.vault, result);
+            },
+            onError: printBenchError
+        });
+        await new Promise((resolveSignal) => {
+            const shutdown = () => {
+                watcher.close();
+                resolveSignal();
+            };
+            process.once('SIGINT', shutdown);
+            process.once('SIGTERM', shutdown);
+        });
+    });
     program
         .command('doctor')
         .option('-v, --vault <vault>', 'vault directory')