@andespindola/brainlink 0.1.0-beta.85 → 0.1.0-beta.87

package/README.md

@@ -84,11 +84,11 @@ Legacy `.jsonl.gz` packs are upgraded to `.blpk` automatically on first search/c
 - Graph renderer optimized for large datasets with viewport-driven node culling and edge lookup by visible nodes.
 - Canvas graph rendering uses the same batched node and edge pipeline for every graph size, reducing per-frame draw calls while keeping selected and hovered items highlighted.
 - WebGL acceleration is used when available for dense node and edge drawing, with Canvas 2D preserved as the interaction and fallback layer.
-- Graph zoom-out renders connected ecosystem clusters of up to 1000 notes before expanding into individual notes, keeping vaults visually oriented with a smaller render scope.
+- Graph zoom-out renders hierarchical ecosystem subgraphs only above 1000 notes: distant groups stay as small sand-like points and expand near the user's focus into smaller graph meshes before individual notes are rendered.
 - Large graph layout API automatically uses compact payload encoding with link-coverage-aware edge selection to reduce initial client load without hiding major relationships.
 - Large-segment layout spacing now grows logarithmically to keep initial visual density consistent between medium and very large vaults (for example, ~1k vs ~50k notes).
 - Graph coordinates are visually compacted across graph sizes so reset starts from a stable macro mass and zoom-in progressively expands toward local detail.
-- Zoomed-out graph LOD clusters dense regions and progressively expands the focused viewport as zoom increases, including very large vaults.
+- Zoomed-out graph LOD renders nested subgraphs and progressively expands only the focused cluster as zoom increases, including very large vaults.
 - Graph reset starts in macro "galaxy" overview mode and progressively reveals nearby nodes as zoom increases, including smaller vaults.
 - Graph filtering runs in a dedicated browser worker to keep the UI thread responsive during heavy datasets.
 - Edge rendering budgets adapt to zoom level to prevent frame spikes on large graph panoramas.
@@ -602,7 +602,7 @@ The graph UI shows:
 - WebGL node and edge acceleration when supported, falling back to Canvas 2D without changing graph behavior
 - compact macro-to-micro density progression so reset keeps the graph mass oriented and zoom-in separates local neighborhoods progressively
 - graph camera treats hub-centered navigation as structural only when the hub is dominant; diffuse stress graphs reset and zoom around the full graph mass
-- graph LOD progression: very low zoom uses connected ecosystem clusters of up to 1000 notes with aggregated real links, then progressively raises the focused node budget as zoom increases so dense local areas keep nearby notes and links visible
+- graph LOD progression: graphs up to 1000 notes render directly; larger graphs use connected sand-like ecosystem points of up to 1000 notes, zoom-in spreads only focused clusters into 250-note and 60-note subgraphs with aggregated real links, then progressively raises the focused node budget so local areas keep nearby notes and links visible
 
 The server indexes before starting by default. Use `--no-index` to skip that step:
 

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

@@ -22,8 +22,13 @@ const worldCoordinateLimit = 5_000_000
 const transformCoordinateLimit = 20_000_000
 const hoverHitTestIntervalMs = 64
 const ecosystemGroupSize = 1000
+const ecosystemActivationNodeThreshold = 1000
+const ecosystemGroupSizes = [1000, 250, 60]
 const ecosystemClusterEdgeLimit = 520
-const ecosystemClusterScaleThreshold = 0.08
+const ecosystemClusterScaleThreshold = 0.32
+const ecosystemSubgraphScaleThreshold = 0.18
+const ecosystemMicroScaleThreshold = 0.08
+const ecosystemFocusedParentLimit = 3
 const zoomRecoveryGuardMs = 4200
 const zoomCapTargetViewportShare = 0.72
 const meshEdgeScaleThreshold = 0.09
@@ -68,7 +73,7 @@ const state = {
   visibleNodeSpatial: { cellSize: 220, minX: 0, minY: 0, maxX: 0, maxY: 0, buckets: new Map() },
   visibleEdgeByNode: new Map(),
   ecosystemClusters: [],
-  ecosystemEdges: [],
+  ecosystemClustersBySize: new Map(),
   macroCenter: { x: 0, y: 0 },
   macroRepresentative: null,
   primaryHub: null,
@@ -565,11 +570,11 @@ const recomputeVisibility = () => {
   state.visibleEdges = limitedEdges
   state.visibleNodeSpatial = createSpatialIndex(nodes)
   state.visibleEdgeByNode = createVisibleEdgeLookup(limitedEdges)
-  const ecosystemGraph = nodes.length > 1
-    ? buildEcosystemGraph(nodes, limitedEdges)
-    : { clusters: [], edges: [] }
+  const ecosystemGraph = nodes.length > ecosystemActivationNodeThreshold
+    ? buildEcosystemGraph(nodes)
+    : { clusters: [], clustersBySize: new Map() }
   state.ecosystemClusters = ecosystemGraph.clusters
-  state.ecosystemEdges = ecosystemGraph.edges
+  state.ecosystemClustersBySize = ecosystemGraph.clustersBySize
   const primaryHub = rankedHubNodes()[0] ?? null
   state.primaryHub = primaryHub
   state.hubNeighborDistance = nearestHubNeighborDistance(primaryHub, nodes)
@@ -738,32 +743,168 @@ const buildEcosystemCluster = (nodes, index) => {
     x: sum.x / count,
     y: sum.y / count,
     count,
+    nodeIds: nodes.map(node => node.id),
     representative,
     label: ecosystemKeyForNode(nodes[0] ?? representative ?? { path: '' })
   }
 }
 
-const buildEcosystemGraph = (nodes, edges) => {
-  if (nodes.length === 0) {
-    return { clusters: [], edges: [] }
-  }
-
-  const sortedNodes = [...nodes].sort(compareNodesForEcosystem)
+const buildEcosystemLevel = (sortedNodes, size, parentLookup) => {
   const clusters = []
   const clusterByNodeId = new Map()
 
-  for (let offset = 0; offset < sortedNodes.length; offset += ecosystemGroupSize) {
-    const clusterNodes = sortedNodes.slice(offset, offset + ecosystemGroupSize)
-    const cluster = buildEcosystemCluster(clusterNodes, clusters.length)
+  for (let offset = 0; offset < sortedNodes.length; offset += size) {
+    const clusterNodes = sortedNodes.slice(offset, offset + size)
+    const parentCluster = parentLookup?.get(clusterNodes[0]?.id)
+    const cluster = {
+      ...buildEcosystemCluster(clusterNodes, clusters.length),
+      id: 'ecosystem-' + size + '-' + clusters.length,
+      size,
+      parentId: parentCluster?.id ?? null,
+      parentX: parentCluster?.x ?? null,
+      parentY: parentCluster?.y ?? null
+    }
     clusters.push(cluster)
     for (let index = 0; index < clusterNodes.length; index += 1) {
       clusterByNodeId.set(clusterNodes[index].id, cluster)
     }
   }
 
+  return { clusters, clusterByNodeId }
+}
+
+const buildEcosystemGraph = (nodes) => {
+  if (nodes.length === 0) {
+    return { clusters: [], clustersBySize: new Map() }
+  }
+
+  const sortedNodes = [...nodes].sort(compareNodesForEcosystem)
+  const clustersBySize = new Map()
+  let parentLookup = null
+
+  for (let index = 0; index < ecosystemGroupSizes.length; index += 1) {
+    const size = ecosystemGroupSizes[index]
+    const level = buildEcosystemLevel(sortedNodes, size, parentLookup)
+    clustersBySize.set(size, level.clusters)
+    parentLookup = level.clusterByNodeId
+  }
+
+  return {
+    clusters: clustersBySize.get(ecosystemGroupSize) ?? [],
+    clustersBySize
+  }
+}
+
+const isClusterInViewport = (cluster, viewport) =>
+  cluster.x >= viewport.minX &&
+  cluster.x <= viewport.maxX &&
+  cluster.y >= viewport.minY &&
+  cluster.y <= viewport.maxY
+
+const filterEcosystemClustersByViewport = (clusters, viewport) => {
+  const visible = clusters.filter(cluster => isClusterInViewport(cluster, viewport))
+  return visible.length > 0 ? visible : [...clusters]
+}
+
+const ecosystemFocusPoint = () => {
+  const now = performance.now()
+  if (now - state.lastZoomFocus.at <= 1800) {
+    return { x: state.lastZoomFocus.x, y: state.lastZoomFocus.y }
+  }
+  return viewportCenterWorldPoint()
+}
+
+const nearestEcosystemParentIds = (clusters, focusPoint, limit) =>
+  clusters
+    .map(cluster => ({
+      cluster,
+      distance: Math.hypot(cluster.x - focusPoint.x, cluster.y - focusPoint.y)
+    }))
+    .sort((left, right) => left.distance - right.distance)
+    .slice(0, limit)
+    .map(item => item.cluster.id)
+
+const smoothStep = value => {
+  const clamped = Math.max(0, Math.min(1, value))
+  return clamped * clamped * (3 - clamped * 2)
+}
+
+const zoomProgress = (scale, start, end) =>
+  smoothStep((scale - start) / Math.max(end - start, 0.0001))
+
+const ecosystemPlanForScale = scale => {
+  if (scale <= ecosystemMicroScaleThreshold) {
+    return { baseSize: 1000, childSize: null, spread: 0 }
+  }
+  if (scale <= ecosystemSubgraphScaleThreshold) {
+    return {
+      baseSize: 1000,
+      childSize: 250,
+      spread: zoomProgress(scale, ecosystemMicroScaleThreshold, ecosystemSubgraphScaleThreshold)
+    }
+  }
+  return {
+    baseSize: 250,
+    childSize: 60,
+    spread: zoomProgress(scale, ecosystemSubgraphScaleThreshold, ecosystemClusterScaleThreshold)
+  }
+}
+
+const spreadChildClusterFromParent = (cluster, spread) => {
+  if (!Number.isFinite(cluster.parentX) || !Number.isFinite(cluster.parentY)) {
+    return cluster
+  }
+
+  return {
+    ...cluster,
+    x: cluster.parentX + (cluster.x - cluster.parentX) * spread,
+    y: cluster.parentY + (cluster.y - cluster.parentY) * spread
+  }
+}
+
+const selectHierarchicalEcosystemClusters = viewport => {
+  const plan = ecosystemPlanForScale(state.transform.scale)
+  const baseClusters = state.ecosystemClustersBySize.get(plan.baseSize) ?? state.ecosystemClusters
+  const visibleBaseClusters = filterEcosystemClustersByViewport(baseClusters, viewport)
+
+  if (!plan.childSize) {
+    return visibleBaseClusters
+  }
+
+  const focusPoint = ecosystemFocusPoint()
+  const expandedParentIds = new Set(nearestEcosystemParentIds(
+    visibleBaseClusters,
+    focusPoint,
+    ecosystemFocusedParentLimit
+  ))
+  const childClusters = state.ecosystemClustersBySize.get(plan.childSize) ?? []
+  const visibleChildClusters = childClusters.filter(cluster =>
+    expandedParentIds.has(cluster.parentId) &&
+    isClusterInViewport(cluster, viewport)
+  ).map(cluster => spreadChildClusterFromParent(cluster, plan.spread))
+
+  if (visibleChildClusters.length === 0) {
+    return visibleBaseClusters
+  }
+
+  return [
+    ...visibleBaseClusters.filter(cluster => !expandedParentIds.has(cluster.id)),
+    ...visibleChildClusters
+  ]
+}
+
+const ecosystemEdgesForClusters = clusters => {
+  const clusterByNodeId = new Map()
+  for (let clusterIndex = 0; clusterIndex < clusters.length; clusterIndex += 1) {
+    const cluster = clusters[clusterIndex]
+    for (let nodeIndex = 0; nodeIndex < cluster.nodeIds.length; nodeIndex += 1) {
+      clusterByNodeId.set(cluster.nodeIds[nodeIndex], cluster)
+    }
+  }
+
   const edgeByClusterPair = new Map()
-  for (let index = 0; index < edges.length; index += 1) {
-    const edge = edges[index]
+  for (let index = 0; index < state.visibleEdges.length; index += 1) {
+    const edge = state.visibleEdges[index]
     const sourceCluster = clusterByNodeId.get(edge.source)
     const targetCluster = clusterByNodeId.get(edge.target)
     if (!sourceCluster || !targetCluster || sourceCluster.id === targetCluster.id) {
@@ -788,27 +929,9 @@ const buildEcosystemGraph = (nodes, edges) => {
     })
   }
 
-  const aggregatedEdges = Array.from(edgeByClusterPair.values())
+  return Array.from(edgeByClusterPair.values())
     .sort((left, right) => right.weight - left.weight)
     .slice(0, ecosystemClusterEdgeLimit)
-
-  return { clusters, edges: aggregatedEdges }
-}
-
-const filterEcosystemClustersByViewport = viewport =>
-  state.ecosystemClusters.filter((cluster) =>
-    cluster.x >= viewport.minX &&
-    cluster.x <= viewport.maxX &&
-    cluster.y >= viewport.minY &&
-    cluster.y <= viewport.maxY
-  )
-
-const ecosystemEdgesForClusters = clusters => {
-  const clusterIds = new Set(clusters.map(cluster => cluster.id))
-  return state.ecosystemEdges.filter(edge =>
-    clusterIds.has(edge.sourceCluster.id) &&
-    clusterIds.has(edge.targetCluster.id)
-  )
 }
 
 const edgeBudgetForCurrentFrame = () => {
@@ -2245,6 +2368,17 @@ const baseNodeRadius = node => {
 
 const nodeRadius = node => Math.max(baseNodeRadius(node), minNodePixelRadius / Math.max(state.transform.scale, 0.0001))
 
+const clusterRadiusPx = cluster => {
+  if (cluster.id === 'macro-galaxy') {
+    return 10
+  }
+  if (String(cluster.id).startsWith('ecosystem-')) {
+    const base = cluster.size >= 1000 ? 2.4 : cluster.size >= 250 ? 2.1 : 1.8
+    return Math.max(1.8, Math.min(4.2, base + Math.log10(cluster.count + 1) * 0.28))
+  }
+  return Math.max(8, Math.min(28, 8 + Math.log2(cluster.count + 1) * 3))
+}
+
 const worldViewportBounds = () => {
   const rect = canvas.getBoundingClientRect()
   const width = Math.max(rect.width, 320)
@@ -2406,12 +2540,13 @@ const computeRenderVisibility = () => {
     return
   }
 
-  if (state.transform.scale <= ecosystemClusterScaleThreshold && state.ecosystemClusters.length > 0) {
-    const viewportClusters = filterEcosystemClustersByViewport(viewport)
+  if (
+    state.visibleNodes.length > ecosystemActivationNodeThreshold &&
+    state.transform.scale <= ecosystemClusterScaleThreshold &&
+    state.ecosystemClusters.length > 0
+  ) {
+    const clusters = selectHierarchicalEcosystemClusters(viewport)
       .sort((left, right) => right.count - left.count)
-    const clusters = viewportClusters.length > 0
-      ? viewportClusters
-      : state.ecosystemClusters
     state.renderClusters = clusters
     state.renderClusterEdges = ecosystemEdgesForClusters(clusters)
     state.renderNodes = []
@@ -2671,20 +2806,21 @@ const render = now => {
     }
     state.renderClusters.forEach(cluster => {
       const isMacro = cluster.id === 'macro-galaxy'
-      const radiusPx = isMacro
-        ? 10
-        : Math.max(8, Math.min(28, 8 + Math.log2(cluster.count + 1) * 3))
+      const isEcosystem = String(cluster.id).startsWith('ecosystem-')
+      const radiusPx = clusterRadiusPx(cluster)
       const radius = radiusPx / safeScale
-      const haloRadius = (radiusPx + (isMacro ? 8 : 4)) / safeScale
-      ctx.beginPath()
-      ctx.arc(cluster.x, cluster.y, haloRadius, 0, Math.PI * 2)
-      ctx.fillStyle = isMacro ? 'rgba(243, 247, 251, 0.28)' : graphTheme.nodeHalo
-      ctx.fill()
+      const haloRadius = (radiusPx + (isMacro ? 8 : isEcosystem ? 1.1 : 4)) / safeScale
+      if (!isEcosystem || state.transform.scale >= ecosystemSubgraphScaleThreshold) {
+        ctx.beginPath()
+        ctx.arc(cluster.x, cluster.y, haloRadius, 0, Math.PI * 2)
+        ctx.fillStyle = isMacro ? 'rgba(243, 247, 251, 0.28)' : graphTheme.nodeHalo
+        ctx.fill()
+      }
       ctx.beginPath()
       ctx.arc(cluster.x, cluster.y, radius, 0, Math.PI * 2)
       ctx.fillStyle = isMacro ? '#f3f7fb' : graphTheme.node
       ctx.fill()
-      ctx.lineWidth = 1.4 / safeScale
+      ctx.lineWidth = (isEcosystem ? 0.7 : 1.4) / safeScale
       ctx.strokeStyle = isMacro ? '#ffffff' : graphTheme.nodeStroke
       ctx.stroke()
       if (isMacro && cluster.representative?.title) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/brainlink",
-  "version": "0.1.0-beta.85",
+  "version": "0.1.0-beta.87",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",