@andespindola/brainlink 1.0.4 → 1.0.6

package/README.md

@@ -115,6 +115,11 @@ blink --help
 
 Use `brainlink` when clarity matters. Use `blink` for faster daily terminal usage.
 
+Brainlink checks npm for a newer package version at most once per day and prints
+an update notice to `stderr` when one is available. It does not update itself
+silently. Disable this with `BRAINLINK_NO_UPDATE_CHECK=1` or with
+`"autoUpdateCheck": false` in config.
+
 The npm package page may show `npm i @andespindola/brainlink`. That installs
 Brainlink as a project dependency. Use `-g` when you want the terminal commands
 available globally, or run it without a global install:
@@ -569,7 +574,7 @@ By default, Brainlink enforces bootstrap and auto-runs it for read tools when se
 If you disable `autoBootstrapOnRead` through `brainlink_policy`, read tools return a preflight instruction with suggested `brainlink_bootstrap` arguments.
 `brainlink_bootstrap`, `brainlink_policy` and preflight responses include structured `nextActions` so MCP clients can continue automatically without custom parsing.
 For one-call planning, use `brainlink_recommendations` to get the recommended tool sequence for the current vault/agent/query.
-The MCP context tools are plug-and-play by default: omit `strategy` to use the configured default (`rag` unless changed), pass `strategy: "cag"` for repeated/stable task context, or pass `strategy: "auto"` so Brainlink chooses CAG on fresh pack hits and RAG otherwise. `brainlink_recommendations`, preflight responses and policy next actions include executable context arguments so clients can continue without custom parsing.
+The MCP context tools are plug-and-play by default: omit `strategy` to use the configured token-efficient default (`auto` unless changed), pass `strategy: "cag"` for repeated/stable task context, or pass `strategy: "rag"` when fresh retrieval is required. `brainlink_recommendations`, preflight responses and policy next actions include executable context arguments so clients can continue without custom parsing.
 
 The same linking rule applies through MCP: `brainlink_context` is read-only, and real graph links require Markdown notes with explicit `## Context Links` sections. `brainlink_add_note` and `brainlink_add_file` reindex by default and include index + `writeConnectivity` metadata. Brainlink does not auto-link new notes to fallback hubs.
 
@@ -657,8 +662,8 @@ Routes:
 - `GET /api/graph-view?x=<x>&y=<y>&w=<width>&h=<height>&scale=<scale>`
 - `GET /api/graph-stream?x=<x>&y=<y>&w=<width>&h=<height>&scale=<scale>&nodeBudget=<n>&edgeBudget=<n>`
 - `GET /api/graph-node?id=<node-id>`
-- `GET /api/search?q=<query>&limit=10&mode=hybrid`
-- `GET /api/context?q=<query>&limit=12&tokens=2000&mode=hybrid`
+- `GET /api/search?q=<query>&limit=8&mode=hybrid`
+- `GET /api/context?q=<query>&limit=8&tokens=1500&mode=hybrid`
 - `GET /api/links`
 - `GET /api/backlinks?title=<title>`
 - `GET /api/stats`
@@ -936,7 +941,7 @@ Context selection uses a middle-out strategy: it starts from the strongest chunk
 ### `context`
 
 ```bash
-blink context "question" --vault ./vault --limit 12 --tokens 2000
+blink context "question" --vault ./vault --limit 8 --tokens 1500
 blink context "question" --vault ./vault --agent coding-agent --json
 blink context "question" --vault ./vault --agent coding-agent --mode hybrid --json
 blink context "question" --vault ./vault --agent coding-agent --strategy cag --json
@@ -947,7 +952,7 @@ blink context-packs --vault ./vault --stale --clear
 
 Builds a compact context package for an agent.
 Repeated calls with the same vault, agent, query, mode and token/limit settings are served from a short in-memory cache while the index is unchanged.
-The default strategy is configured by `defaultContextStrategy` and starts as `rag`, which retrieves and assembles context from the current index. `--strategy cag` enables cache-augmented context generation by reading or refreshing a persisted context pack under `.brainlink/context-packs`; `--strategy auto` uses CAG when a fresh pack exists and RAG otherwise, refreshing a pack for future calls. Context responses include `cache`, `metrics`, `requestedStrategy` and `recommendedStrategy` metadata. Packs are derived artifacts and become stale when the index or volatile memory signature changes.
+The default strategy is configured by `defaultContextStrategy` and starts as `auto`, which uses CAG when a fresh pack exists and RAG otherwise, refreshing a pack for future calls. `--strategy cag` enables cache-augmented context generation by reading or refreshing a persisted context pack under `.brainlink/context-packs`; `--strategy rag` forces fresh retrieval assembly from the current index. Context responses include `cache`, `metrics`, `requestedStrategy` and `recommendedStrategy` metadata. Packs are derived artifacts and become stale when the index or volatile memory signature changes.
 
 ### `links`
 
@@ -1088,9 +1093,11 @@ If no `vault` is configured and no `--vault` flag is passed, Brainlink uses `$HO
   "defaultAgent": "shared",
   "autoIndexOnWrite": true,
   "autoCanonicalContextLinks": true,
-  "defaultSearchLimit": 10,
-  "defaultContextTokens": 2000,
-  "defaultContextStrategy": "rag",
+  "autoUpdateCheck": true,
+  "updateCheckIntervalMs": 86400000,
+  "defaultSearchLimit": 8,
+  "defaultContextTokens": 1500,
+  "defaultContextStrategy": "auto",
   "embeddingProvider": "local",
   "defaultSearchMode": "hybrid",
   "chunkSize": 1200,
@@ -1105,7 +1112,7 @@ If no `vault` is configured and no `--vault` flag is passed, Brainlink uses `$HO
     "coding-agent": {
       "defaultSearchMode": "semantic",
       "defaultSearchLimit": 8,
-      "defaultContextTokens": 2400,
+      "defaultContextTokens": 1500,
       "defaultContextStrategy": "auto"
     },
     "*": {
@@ -1120,6 +1127,7 @@ If no `vault` is configured and no `--vault` flag is passed, Brainlink uses `$HO
 
 `autoIndexOnWrite` is optional and defaults to `true`. Set it to `false` to defer indexing after writes.
 `autoCanonicalContextLinks` is optional and defaults to `true`. When enabled, `blink add`, `brainlink_add_note` and `brainlink_add_file` add a canonical `## Context Links` entry to the inferred context hub, creating that hub when needed.
+`autoUpdateCheck` is optional and defaults to `true`. Brainlink checks the npm registry no more often than `updateCheckIntervalMs` and prints an update notice to `stderr`; it never installs updates automatically.
 
 ## Remote MCP Server
 

package/dist/application/add-note.js

@@ -2,7 +2,7 @@ import { writeMarkdownFile } from '../infrastructure/file-system-vault.js';
 import { sanitizeAgentId, sharedAgentId } from '../domain/agents.js';
 import { validateNoteInput } from '../domain/note-safety.js';
 import { ensureVault } from '../infrastructure/file-system-vault.js';
-import { addCanonicalContextLinkToContent, ensureCanonicalContextHub } from './canonical-context-links.js';
+import { addCanonicalContextLinkToContent, ensureCanonicalContextHub, loadVisualContextRules } from './canonical-context-links.js';
 const slugify = (title) => title
     .normalize('NFKD')
     .replace(/[\u0300-\u036f]/g, '')
@@ -31,7 +31,7 @@ export const addNoteWithMetadata = async (vaultPath, title, content, agentId = s
     await ensureVault(vaultPath);
     const canonical = options.autoContextLinks === false
         ? null
-        : addCanonicalContextLinkToContent(title, content.trim());
+        : addCanonicalContextLinkToContent(title, content.trim(), await loadVisualContextRules(vaultPath), filename);
     const hub = canonical?.changed
         ? await ensureCanonicalContextHub(vaultPath, canonical.context, sanitizedAgentId)
         : null;

package/dist/application/build-context.js

@@ -74,7 +74,7 @@ export const buildContextPackage = async (vaultPath, query, limit, maxTokens, ag
     const cacheKey = toCacheKey(vaultPath, query, limit, maxTokens, agentId, mode, strategy);
     const dataSignature = await readContextDataSignature(vaultPath);
     const cached = contextCacheGet(cacheKey, dataSignature, contextCacheTtlMs);
-    if (cached) {
+    if (cached && cached.sections.length > 0) {
         return cached;
     }
     const shouldUseContextPack = strategy === 'cag' || strategy === 'auto';
@@ -83,7 +83,7 @@ export const buildContextPackage = async (vaultPath, query, limit, maxTokens, ag
         const packReadStart = performance.now();
         const pack = await readContextPack(vaultPath, { query, limit, maxTokens, agentId, mode }, dataSignature);
         packReadMs = elapsedMs(packReadStart);
-        if (pack.status === 'hit') {
+        if (pack.status === 'hit' && pack.context.sections.length > 0) {
             const contextFromPack = {
                 ...pack.context,
                 strategy: 'cag',
@@ -133,8 +133,12 @@ export const buildContextPackage = async (vaultPath, query, limit, maxTokens, ag
                     : 'RAG was requested; Brainlink assembled context directly from current retrieval results.'
         }
     };
+    // Never persist an empty assembly: a transient empty context (e.g. an index
+    // that was momentarily unavailable) must not be cached as a fresh pack and
+    // then served on every later read until the data signature changes.
+    const hasSections = sections.length > 0;
     const packWriteStart = performance.now();
-    const packPath = shouldUseContextPack
+    const packPath = shouldUseContextPack && hasSections
         ? await writeContextPack(vaultPath, { query, limit, maxTokens, agentId, mode }, dataSignature, context)
         : undefined;
     const packWriteMs = packPath ? elapsedMs(packWriteStart) : 0;
@@ -154,13 +158,15 @@ export const buildContextPackage = async (vaultPath, query, limit, maxTokens, ag
             packWriteMs
         })
     };
-    contextCacheSet({
-        key: cacheKey,
-        createdAt: Date.now(),
-        dataSignature,
-        strategy,
-        context: contextWithMetrics
-    });
+    if (hasSections) {
+        contextCacheSet({
+            key: cacheKey,
+            createdAt: Date.now(),
+            dataSignature,
+            strategy,
+            context: contextWithMetrics
+        });
+    }
     return contextWithMetrics;
 };
 export const buildContext = async (vaultPath, query, limit, maxTokens, agentId, mode, strategy, contextCacheTtlMs = 120_000) => {

package/dist/application/canonical-context-links.js

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { inferVisualGraphContext } from '../domain/graph-contexts.js';
+import { deriveVisualContextRules, inferVisualGraphContext } from '../domain/graph-contexts.js';
 import { sanitizeAgentId, sharedAgentId } from '../domain/agents.js';
 import { extractContextLinkWeights, parseMarkdownDocument } from '../domain/markdown.js';
 import { ensureVault, readMarkdownFileSummaries, writeMarkdownFile } from '../infrastructure/file-system-vault.js';
@@ -60,6 +60,42 @@ const buildHubContent = (hubTitle, contextTitle, agentId) => [
     `Canonical hub for the ${contextTitle} context. #memory #hub`,
     ''
 ].join('\n');
+const isHubNotePath = (relativePath) => /(^|\/)[^/]*-hub\.md$/i.test(relativePath);
+// Hub notes change rarely, but loadVisualContextRules runs on every auto-linked
+// note write. Cache the derived rules per vault for a short window so a burst of
+// writes reads the hub notes once. Creating a hub clears the cache so a new
+// context is picked up immediately.
+const visualContextRulesCacheTtlMs = 15_000;
+const visualContextRulesCache = new Map();
+const invalidateVisualContextRulesCache = () => {
+    visualContextRulesCache.clear();
+};
+// Build visual-context rules from the vault's hub notes only, so a single-note
+// write path can classify into vault-specific contexts without reading the
+// whole vault.
+export const loadVisualContextRules = async (vaultPath) => {
+    const absoluteVaultPath = await ensureVault(vaultPath);
+    const cached = visualContextRulesCache.get(absoluteVaultPath);
+    if (cached && Date.now() - cached.createdAt <= visualContextRulesCacheTtlMs) {
+        return cached.rules;
+    }
+    const summaries = await readMarkdownFileSummaries(absoluteVaultPath);
+    const documents = await Promise.all(summaries
+        .filter((summary) => isHubNotePath(summary.relativePath))
+        .map(async (summary) => {
+        const content = await readFile(summary.absolutePath, 'utf8');
+        return parseMarkdownDocument({
+            absolutePath: summary.absolutePath,
+            vaultPath: absoluteVaultPath,
+            content,
+            createdAt: summary.createdAt,
+            updatedAt: summary.updatedAt
+        });
+    }));
+    const rules = deriveVisualContextRules(documents);
+    visualContextRulesCache.set(absoluteVaultPath, { createdAt: Date.now(), rules });
+    return rules;
+};
 const readNotes = async (vaultPath) => {
     const absoluteVaultPath = await ensureVault(vaultPath);
     const summaries = await readMarkdownFileSummaries(absoluteVaultPath);
@@ -92,6 +128,7 @@ export const ensureCanonicalContextHub = async (vaultPath, contextTitle, agentId
         };
     }
     const path = await writeMarkdownFile(vaultPath, hubPath, buildHubContent(hubTitle, contextTitle, agentId));
+    invalidateVisualContextRulesCache();
     return {
         created: true,
         title: hubTitle,
@@ -102,6 +139,7 @@ export const canonicalizeContextLinks = async (vaultPath, options = {}) => {
     const agentId = options.agentId ? sanitizeAgentId(options.agentId) : undefined;
     const createMissingHubs = options.createMissingHubs !== false;
     const notes = await readNotes(vaultPath);
+    const rules = deriveVisualContextRules(notes.map((note) => note.document));
     const scopedNotes = agentId ? notes.filter((note) => note.document.agentId === agentId) : notes;
     const knownTitles = new Set(notes.map((note) => normalizeTitle(note.document.title)));
     const entries = [];
@@ -124,6 +162,7 @@ export const canonicalizeContextLinks = async (vaultPath, options = {}) => {
         knownTitles.add(normalizeTitle(hubTitle));
         if (!options.dryRun) {
             await writeMarkdownFile(vaultPath, path, buildHubContent(hubTitle, contextTitle, targetAgentId));
+            invalidateVisualContextRulesCache();
         }
         entries.push({
             path,
@@ -136,7 +175,7 @@ export const canonicalizeContextLinks = async (vaultPath, options = {}) => {
         return true;
     };
     for (const note of scopedNotes) {
-        const context = inferVisualGraphContext(note.document);
+        const context = inferVisualGraphContext(note.document, rules);
         const hubTitle = hubTitleForContext(context.title);
         const isHub = normalizeTitle(note.document.title) === normalizeTitle(hubTitle);
         if (isHub) {
@@ -189,15 +228,15 @@ export const canonicalizeContextLinks = async (vaultPath, options = {}) => {
         entries
     };
 };
-export const addCanonicalContextLinkToContent = (title, content) => {
+export const addCanonicalContextLinkToContent = (title, content, rules = [], notePath = '') => {
     const context = inferVisualGraphContext({
         id: '',
         agentId: sharedAgentId,
         title,
-        path: '',
+        path: notePath,
         content,
         tags: [],
-    });
+    }, rules);
     const hubTitle = hubTitleForContext(context.title);
     const nextContent = normalizeTitle(title) === normalizeTitle(hubTitle) ? content : upsertCanonicalContextLink(content, hubTitle);
     return {

package/dist/application/check-package-update.js

@@ -0,0 +1,105 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { getBrainlinkHomePath } from '../infrastructure/paths.js';
+const defaultTimeoutMs = 800;
+const registryBaseUrl = 'https://registry.npmjs.org';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const parseCache = (value) => isRecord(value) ? { checkedAt: typeof value.checkedAt === 'string' ? value.checkedAt : undefined, latestVersion: typeof value.latestVersion === 'string' ? value.latestVersion : undefined } : {};
+const readCache = async (path) => {
+    try {
+        return parseCache(JSON.parse(await readFile(path, 'utf8')));
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return {};
+        }
+        return {};
+    }
+};
+const writeCache = async (path, cache) => {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, `${JSON.stringify(cache, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+};
+const parseVersionParts = (version) => {
+    const [core] = version.split('-');
+    const parts = core?.split('.').map((part) => Number.parseInt(part, 10)) ?? [];
+    return parts.length > 0 && parts.every((part) => Number.isFinite(part) && part >= 0) ? parts : null;
+};
+export const comparePackageVersions = (left, right) => {
+    const leftParts = parseVersionParts(left);
+    const rightParts = parseVersionParts(right);
+    if (!leftParts || !rightParts) {
+        return left.localeCompare(right);
+    }
+    const length = Math.max(leftParts.length, rightParts.length);
+    for (let index = 0; index < length; index += 1) {
+        const leftPart = leftParts[index] ?? 0;
+        const rightPart = rightParts[index] ?? 0;
+        if (leftPart !== rightPart) {
+            return leftPart > rightPart ? 1 : -1;
+        }
+    }
+    return 0;
+};
+const isCacheFresh = (cache, now, intervalMs) => {
+    if (!cache.checkedAt) {
+        return false;
+    }
+    const checkedAt = new Date(cache.checkedAt).getTime();
+    return Number.isFinite(checkedAt) && now.getTime() - checkedAt < intervalMs;
+};
+const createSkippedStatus = (input, now, reason, latestVersion = null) => ({
+    currentVersion: input.currentVersion,
+    latestVersion,
+    updateAvailable: latestVersion ? comparePackageVersions(latestVersion, input.currentVersion) > 0 : false,
+    checkedAt: now.toISOString(),
+    installCommand: `npm install -g ${input.packageName}@latest`,
+    skipped: true,
+    reason
+});
+const readLatestVersion = async (packageName, fetchImpl, timeoutMs) => {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetchImpl(`${registryBaseUrl}/${encodeURIComponent(packageName)}/latest`, { signal: controller.signal });
+        if (!response.ok) {
+            return null;
+        }
+        const payload = await response.json();
+        return isRecord(payload) && typeof payload.version === 'string' ? payload.version : null;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+};
+export const checkPackageUpdate = async (input) => {
+    const now = input.now ?? new Date();
+    const cachePath = input.cachePath ?? join(getBrainlinkHomePath(), 'update-check.json');
+    const cache = await readCache(cachePath);
+    if (!input.enabled) {
+        return createSkippedStatus(input, now, 'disabled');
+    }
+    if (isCacheFresh(cache, now, input.intervalMs)) {
+        return createSkippedStatus(input, now, 'cache-fresh', cache.latestVersion ?? null);
+    }
+    const fetchImpl = input.fetch ?? globalThis.fetch;
+    if (!fetchImpl) {
+        return createSkippedStatus(input, now, 'fetch-unavailable');
+    }
+    const latestVersion = await readLatestVersion(input.packageName, fetchImpl, input.timeoutMs ?? defaultTimeoutMs);
+    if (!latestVersion) {
+        return createSkippedStatus(input, now, 'latest-unavailable');
+    }
+    await writeCache(cachePath, {
+        checkedAt: now.toISOString(),
+        latestVersion
+    });
+    return {
+        currentVersion: input.currentVersion,
+        latestVersion,
+        updateAvailable: comparePackageVersions(latestVersion, input.currentVersion) > 0,
+        checkedAt: now.toISOString(),
+        installCommand: `npm install -g ${input.packageName}@latest`,
+        skipped: false
+    };
+};

package/dist/application/frontend/client/chunk-fetch.js

@@ -0,0 +1,236 @@
+export const createChunkFetchJs = () => `
+const fitFromChunk = () => {
+  const nodes = normalizeList(state.chunk.nodes)
+  if (nodes.length === 0) {
+    return
+  }
+
+  let minX = Infinity
+  let minY = Infinity
+  let maxX = -Infinity
+  let maxY = -Infinity
+
+  for (let index = 0; index < nodes.length; index += 1) {
+    const node = nodes[index]
+    const x = Number(node[2])
+    const y = Number(node[3])
+    if (!Number.isFinite(x) || !Number.isFinite(y)) {
+      continue
+    }
+    if (x < minX) minX = x
+    if (y < minY) minY = y
+    if (x > maxX) maxX = x
+    if (y > maxY) maxY = y
+  }
+
+  if (!Number.isFinite(minX) || !Number.isFinite(minY) || !Number.isFinite(maxX) || !Number.isFinite(maxY)) {
+    return
+  }
+
+  const width = Math.max(1, maxX - minX)
+  const height = Math.max(1, maxY - minY)
+  const scaleX = state.viewport.width / width
+  const scaleY = state.viewport.height / height
+  const scale = clampScale(Math.min(scaleX, scaleY) * 0.72)
+
+  state.camera.scale = scale
+  state.camera.x = state.viewport.width / 2 - (minX + width / 2) * scale
+  state.camera.y = state.viewport.height / 2 - (minY + height / 2) * scale
+  updateWorkerCamera()
+}
+
+const fetchChunk = async ({ fit } = { fit: false }) => {
+  const token = ++state.fetchToken
+  if (state.fetchAbortController) {
+    state.fetchAbortController.abort()
+  }
+  const controller = new AbortController()
+  state.fetchAbortController = controller
+  const worldTopLeft = screenToWorld(0, 0)
+  const worldBottomRight = screenToWorld(state.viewport.width, state.viewport.height)
+  const x = Math.min(worldTopLeft.x, worldBottomRight.x)
+  const y = Math.min(worldTopLeft.y, worldBottomRight.y)
+  const w = Math.abs(worldBottomRight.x - worldTopLeft.x)
+  const h = Math.abs(worldBottomRight.y - worldTopLeft.y)
+
+  const params = new URLSearchParams({
+    x: String(x),
+    y: String(y),
+    w: String(Math.max(1, w)),
+    h: String(Math.max(1, h)),
+    scale: String(state.camera.scale),
+    nodeBudget: String(getZoomNodeBudget()),
+    edgeBudget: String(getZoomEdgeBudget())
+  })
+
+  if (state.agentId) {
+    params.set('agent', state.agentId)
+  }
+  if (state.contextId) {
+    params.set('context', state.contextId)
+  }
+
+  const requestKey = graphStreamRequestKey({ x, y, w, h })
+  if (!fit && state.lastChunkRequestKey === requestKey && state.chunk.nodes.length > 0) {
+    return
+  }
+
+  const response = await fetch('/api/graph-stream?' + params.toString(), { signal: controller.signal })
+  if (!response.ok) {
+    throw new Error('Failed to fetch graph stream chunk')
+  }
+
+  const chunk = await response.json()
+  if (controller.signal.aborted) {
+    return
+  }
+  if (token !== state.fetchToken) {
+    return
+  }
+
+  state.graphSignature = typeof chunk.signature === 'string' ? chunk.signature : ''
+  state.lastChunkRequestKey = requestKey
+  ensureNodePositionsLoaded()
+  await syncNodePositionsFromServer()
+  state.graphMode = typeof chunk.mode === 'string' ? chunk.mode : 'near'
+  const chunkNodes = applyManualNodePositions(chunk.nodes)
+  state.chunk = {
+    nodes: chunkNodes,
+    edges: normalizeList(chunk.edges)
+  }
+  state.miniMapDirty = true
+  state.spatialIndex.key = ''
+  const renderChunk = { ...chunk, nodes: chunkNodes }
+  state.totals = {
+    nodes: Number.isFinite(chunk?.totals?.nodes) ? Number(chunk.totals.nodes) : state.chunk.nodes.length,
+    edges: Number.isFinite(chunk?.totals?.edges) ? Number(chunk.totals.edges) : state.chunk.edges.length
+  }
+
+  updateTotals()
+
+  if (fit) {
+    fitFromChunk()
+  }
+
+  if (state.renderWorker && state.workerReady) {
+    state.renderWorker.postMessage({ type: 'chunk', chunk: renderChunk })
+    state.renderWorker.postMessage({ type: 'select', id: state.selectedNodeId })
+    state.renderWorker.postMessage({ type: 'highlight', ids: Array.from(state.searchResultIds) })
+  }
+
+  updateGraphOverlays()
+  drawFallback()
+}
+
+const scheduleChunkFetch = ({ fit } = { fit: false }) => {
+  if (state.fetchTimer) {
+    clearTimeout(state.fetchTimer)
+  }
+
+  const now = performance.now()
+  const recentlyWheeling = now - state.lastWheelAt < 320
+  const heavyScene = state.lastVisibleNodes > 1200 || state.lastVisibleEdges > 3500
+  const delay = fit ? 0 : (state.pointer.down ? 320 : (recentlyWheeling ? (heavyScene ? 420 : 300) : (heavyScene ? 120 : 72)))
+  state.fetchTimer = setTimeout(() => {
+    state.fetchTimer = null
+    fetchChunk({ fit }).catch((error) => {
+      if (error && error.name === 'AbortError') {
+        return
+      }
+      console.error(error)
+    })
+  }, delay)
+}
+
+const setViewportFromCanvas = () => {
+  const rect = canvas.getBoundingClientRect()
+  state.viewport.width = Math.max(320, rect.width)
+  state.viewport.height = Math.max(320, rect.height)
+  state.viewport.ratio = window.devicePixelRatio || 1
+  state.miniMapDirty = true
+  updateWorkerSize()
+  drawFallback()
+}
+
+const pickFallbackNode = (screenX, screenY) => {
+  const nodes = spatialCandidates(screenX, screenY)
+  if (nodes.length === 0) {
+    return null
+  }
+
+  let bestNode = null
+  let bestDistance = Infinity
+  for (let index = 0; index < nodes.length; index += 1) {
+    const node = nodes[index]
+    const id = typeof node[0] === 'string' ? node[0] : ''
+    if (!id) continue
+    const x = Number(node[2])
+    const y = Number(node[3])
+    const weight = Number(node[7])
+    if (!Number.isFinite(x) || !Number.isFinite(y)) continue
+    const point = worldToScreen(x, y)
+    const radius = Math.max(3.2, Math.min(16.5, 5 + (Number.isFinite(weight) ? weight : 0) * 0.65))
+    const distance = Math.hypot(screenX - point.x, screenY - point.y)
+    if (distance <= radius && distance < bestDistance) {
+      bestDistance = distance
+      bestNode = node
+    }
+  }
+
+  return bestNode
+}
+
+const pickFallbackNodeId = (screenX, screenY) => {
+  const node = pickFallbackNode(screenX, screenY)
+  return typeof node?.[0] === 'string' ? node[0] : ''
+}
+
+const handlePickedNode = (node) => {
+  const nodeId = typeof node?.id === 'string' ? node.id : typeof node?.[0] === 'string' ? node[0] : ''
+  if (!nodeId) {
+    return
+  }
+
+  const kind = typeof node?.kind === 'string' ? node.kind : nodeKind(node)
+  if (kind === 'cluster') {
+    const currentScale = state.camera.scale
+    const targetScale = currentScale < 0.22 ? 0.28 : Math.min(1.1, currentScale * 1.6)
+    focusNodeInViewport(nodeId, targetScale)
+    return
+  }
+
+  loadNodeDetails(nodeId).catch((error) => console.error(error))
+}
+
+const pickAt = (screenX, screenY) => {
+  if (state.rendererMode === 'fallback') {
+    const node = pickFallbackNode(screenX, screenY)
+    if (node) {
+      handlePickedNode(node)
+    }
+    return
+  }
+
+  if (!state.renderWorker || !state.workerReady) {
+    return
+  }
+
+  const requestId = Math.random().toString(36).slice(2)
+  state.renderWorker.postMessage({
+    type: 'pick',
+    requestId,
+    x: screenX,
+    y: screenY
+  })
+}
+
+const zoomAtPoint = (screenX, screenY, factor) => {
+  const clamped = Math.max(0.92, Math.min(1.09, factor))
+  const before = screenToWorld(screenX, screenY)
+  state.camera.scale = clampScale(state.camera.scale * clamped)
+  state.camera.x = screenX - before.x * state.camera.scale
+  state.camera.y = screenY - before.y * state.camera.scale
+  updateWorkerCamera()
+  scheduleChunkFetch()
+}
+`;