@andespindola/brainlink 0.1.0-beta.86 → 0.1.0-beta.88

package/README.md

@@ -84,7 +84,7 @@ 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 hierarchical ecosystem subgraphs: macro clusters of up to 1000 notes expand near the user's focus into smaller graph meshes before individual notes are rendered.
+- Graph zoom-out renders hierarchical ecosystem subgraphs only above 1000 notes: the memory hub stays centered, 1000-note groups stay as compact sand-like points, and focused groups gradually expand 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.
@@ -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, zoom-in expands 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
+- graph LOD progression: graphs up to 1000 notes render directly; larger graphs use a compact memory-hub-centered mesh of connected 1000-note points, 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,10 @@ 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 ecosystemHubEdgeLimit = 120
 const ecosystemClusterScaleThreshold = 0.32
 const ecosystemSubgraphScaleThreshold = 0.18
 const ecosystemMicroScaleThreshold = 0.08
@@ -73,6 +75,8 @@ const state = {
   visibleEdgeByNode: new Map(),
   ecosystemClusters: [],
   ecosystemClustersBySize: new Map(),
+  ecosystemNodeClusterBySize: new Map(),
+  ecosystemHubCluster: null,
   macroCenter: { x: 0, y: 0 },
   macroRepresentative: null,
   primaryHub: null,
@@ -569,11 +573,6 @@ const recomputeVisibility = () => {
   state.visibleEdges = limitedEdges
   state.visibleNodeSpatial = createSpatialIndex(nodes)
   state.visibleEdgeByNode = createVisibleEdgeLookup(limitedEdges)
-  const ecosystemGraph = nodes.length > 1
-    ? buildEcosystemGraph(nodes)
-    : { clusters: [], clustersBySize: new Map() }
-  state.ecosystemClusters = ecosystemGraph.clusters
-  state.ecosystemClustersBySize = ecosystemGraph.clustersBySize
   const primaryHub = rankedHubNodes()[0] ?? null
   state.primaryHub = primaryHub
   state.hubNeighborDistance = nearestHubNeighborDistance(primaryHub, nodes)
@@ -585,6 +584,13 @@ const recomputeVisibility = () => {
       y: macroHub ? macroHub.y : (bounds.minY + bounds.maxY) / 2
     }
     : { x: 0, y: 0 }
+  const ecosystemGraph = nodes.length > ecosystemActivationNodeThreshold
+    ? buildEcosystemGraph(nodes, state.macroCenter, primaryHub)
+    : { clusters: [], clustersBySize: new Map(), nodeClusterBySize: new Map(), hubCluster: null }
+  state.ecosystemClusters = ecosystemGraph.clusters
+  state.ecosystemClustersBySize = ecosystemGraph.clustersBySize
+  state.ecosystemNodeClusterBySize = ecosystemGraph.nodeClusterBySize
+  state.ecosystemHubCluster = ecosystemGraph.hubCluster
   state.macroRepresentative = resolveMacroRepresentative(nodes)
   markRenderDirty()
 }
@@ -729,18 +735,32 @@ const selectEcosystemRepresentative = nodes => {
   return representative
 }
 
-const buildEcosystemCluster = (nodes, index) => {
+const ecosystemLayoutSpacingForSize = size => {
+  if (size >= 1000) return 360
+  if (size >= 250) return 92
+  return 28
+}
+
+const ecosystemCompactPoint = (index, total, center, spacing) => {
+  if (total <= 1) {
+    return { x: center.x, y: center.y }
+  }
+  const angle = index * 2.399963229728653
+  const radius = spacing * Math.sqrt(index + 1)
+  return {
+    x: center.x + Math.cos(angle) * radius,
+    y: center.y + Math.sin(angle) * radius
+  }
+}
+
+const buildEcosystemCluster = (nodes, index, point) => {
   const count = Math.max(nodes.length, 1)
-  const sum = nodes.reduce((accumulator, node) => ({
-    x: accumulator.x + node.x,
-    y: accumulator.y + node.y
-  }), { x: 0, y: 0 })
   const representative = selectEcosystemRepresentative(nodes)
 
   return {
     id: 'ecosystem-' + index,
-    x: sum.x / count,
-    y: sum.y / count,
+    x: point.x,
+    y: point.y,
     count,
     nodeIds: nodes.map(node => node.id),
     representative,
@@ -748,18 +768,47 @@ const buildEcosystemCluster = (nodes, index) => {
   }
 }
 
-const buildEcosystemLevel = (sortedNodes, size, parentLookup) => {
+const buildEcosystemHubCluster = (hub, center) => hub
+  ? {
+      id: 'ecosystem-hub',
+      x: center.x,
+      y: center.y,
+      count: 1,
+      size: 1,
+      nodeIds: [hub.id],
+      representative: hub,
+      label: hub.title || 'Memory Hub',
+      parentId: null,
+      parentX: null,
+      parentY: null,
+      isHub: true
+    }
+  : null
+
+const buildEcosystemLevel = (sortedNodes, size, parentLookup, center) => {
   const clusters = []
   const clusterByNodeId = new Map()
+  const parentChildIndex = new Map()
 
   for (let offset = 0; offset < sortedNodes.length; offset += size) {
     const clusterNodes = sortedNodes.slice(offset, offset + size)
     const parentCluster = parentLookup?.get(clusterNodes[0]?.id)
+    const siblingIndex = parentCluster
+      ? (parentChildIndex.get(parentCluster.id) ?? 0)
+      : clusters.length
+    if (parentCluster) {
+      parentChildIndex.set(parentCluster.id, siblingIndex + 1)
+    }
+    const point = parentCluster
+      ? ecosystemCompactPoint(siblingIndex, Math.ceil((parentCluster.count || size) / size), parentCluster, ecosystemLayoutSpacingForSize(size))
+      : ecosystemCompactPoint(clusters.length, Math.ceil(sortedNodes.length / size), center, ecosystemLayoutSpacingForSize(size))
     const cluster = {
-      ...buildEcosystemCluster(clusterNodes, clusters.length),
+      ...buildEcosystemCluster(clusterNodes, clusters.length, point),
       id: 'ecosystem-' + size + '-' + clusters.length,
       size,
-      parentId: parentCluster?.id ?? null
+      parentId: parentCluster?.id ?? null,
+      parentX: parentCluster?.x ?? null,
+      parentY: parentCluster?.y ?? null
     }
     clusters.push(cluster)
     for (let index = 0; index < clusterNodes.length; index += 1) {
@@ -770,25 +819,32 @@ const buildEcosystemLevel = (sortedNodes, size, parentLookup) => {
   return { clusters, clusterByNodeId }
 }
 
-const buildEcosystemGraph = (nodes) => {
+const buildEcosystemGraph = (nodes, center, hub) => {
   if (nodes.length === 0) {
-    return { clusters: [], clustersBySize: new Map() }
+    return { clusters: [], clustersBySize: new Map(), nodeClusterBySize: new Map(), hubCluster: null }
   }
 
-  const sortedNodes = [...nodes].sort(compareNodesForEcosystem)
+  const hubCluster = buildEcosystemHubCluster(hub, center)
+  const sortedNodes = nodes
+    .filter(node => node.id !== hub?.id)
+    .sort(compareNodesForEcosystem)
   const clustersBySize = new Map()
+  const nodeClusterBySize = new Map()
   let parentLookup = null
 
   for (let index = 0; index < ecosystemGroupSizes.length; index += 1) {
     const size = ecosystemGroupSizes[index]
-    const level = buildEcosystemLevel(sortedNodes, size, parentLookup)
+    const level = buildEcosystemLevel(sortedNodes, size, parentLookup, center)
     clustersBySize.set(size, level.clusters)
+    nodeClusterBySize.set(size, level.clusterByNodeId)
     parentLookup = level.clusterByNodeId
   }
 
   return {
     clusters: clustersBySize.get(ecosystemGroupSize) ?? [],
-    clustersBySize
+    clustersBySize,
+    nodeClusterBySize,
+    hubCluster
   }
 }
 
@@ -821,61 +877,124 @@ const nearestEcosystemParentIds = (clusters, focusPoint, limit) =>
     .slice(0, limit)
     .map(item => item.cluster.id)
 
-const ecosystemPlanForScale = scale => {
-  if (scale <= ecosystemMicroScaleThreshold) {
-    return { baseSize: 1000, childSize: null }
+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 expandFocusedClusters = (parentClusters, childSize, spread, viewport) => {
+  const focusPoint = ecosystemFocusPoint()
+  const expandedParentIds = new Set(nearestEcosystemParentIds(
+    parentClusters,
+    focusPoint,
+    ecosystemFocusedParentLimit
+  ))
+  const childClusters = state.ecosystemClustersBySize.get(childSize) ?? []
+  const visibleChildClusters = childClusters
+    .filter(cluster => expandedParentIds.has(cluster.parentId))
+    .map(cluster => spreadChildClusterFromParent(cluster, spread))
+    .filter(cluster => isClusterInViewport(cluster, viewport))
+
+  return {
+    expandedParentIds,
+    childClusters: visibleChildClusters
   }
-  if (scale <= ecosystemSubgraphScaleThreshold) {
-    return { baseSize: 1000, childSize: 250 }
+}
+
+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
   }
-  return { baseSize: 250, childSize: 60 }
 }
 
 const selectHierarchicalEcosystemClusters = viewport => {
-  const plan = ecosystemPlanForScale(state.transform.scale)
-  const baseClusters = state.ecosystemClustersBySize.get(plan.baseSize) ?? state.ecosystemClusters
+  const baseClusters = state.ecosystemClustersBySize.get(ecosystemGroupSize) ?? state.ecosystemClusters
   const visibleBaseClusters = filterEcosystemClustersByViewport(baseClusters, viewport)
+  const hubClusters = state.ecosystemHubCluster ? [state.ecosystemHubCluster] : []
 
-  if (!plan.childSize) {
-    return visibleBaseClusters
+  if (state.transform.scale <= ecosystemMicroScaleThreshold) {
+    return [...hubClusters, ...visibleBaseClusters]
   }
 
-  const focusPoint = ecosystemFocusPoint()
-  const expandedParentIds = new Set(nearestEcosystemParentIds(
+  const midExpansion = expandFocusedClusters(
     visibleBaseClusters,
-    focusPoint,
-    ecosystemFocusedParentLimit
-  ))
-  const childClusters = state.ecosystemClustersBySize.get(plan.childSize) ?? []
-  const visibleChildClusters = childClusters.filter(cluster =>
-    expandedParentIds.has(cluster.parentId) &&
-    isClusterInViewport(cluster, viewport)
+    250,
+    state.transform.scale <= ecosystemSubgraphScaleThreshold
+      ? zoomProgress(state.transform.scale, ecosystemMicroScaleThreshold, ecosystemSubgraphScaleThreshold)
+      : 1,
+    viewport
   )
+  if (midExpansion.childClusters.length === 0) {
+    return [...hubClusters, ...visibleBaseClusters]
+  }
 
-  if (visibleChildClusters.length === 0) {
-    return visibleBaseClusters
+  const remainingBaseClusters = visibleBaseClusters.filter(cluster => !midExpansion.expandedParentIds.has(cluster.id))
+  if (state.transform.scale <= ecosystemSubgraphScaleThreshold) {
+    return [
+      ...hubClusters,
+      ...remainingBaseClusters,
+      ...midExpansion.childClusters
+    ]
+  }
+
+  const microExpansion = expandFocusedClusters(
+    midExpansion.childClusters,
+    60,
+    zoomProgress(state.transform.scale, ecosystemSubgraphScaleThreshold, ecosystemClusterScaleThreshold),
+    viewport
+  )
+  if (microExpansion.childClusters.length === 0) {
+    return [
+      ...hubClusters,
+      ...remainingBaseClusters,
+      ...midExpansion.childClusters
+    ]
   }
 
   return [
-    ...visibleBaseClusters.filter(cluster => !expandedParentIds.has(cluster.id)),
-    ...visibleChildClusters
+    ...hubClusters,
+    ...remainingBaseClusters,
+    ...midExpansion.childClusters.filter(cluster => !microExpansion.expandedParentIds.has(cluster.id)),
+    ...microExpansion.childClusters
   ]
 }
 
 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 clusterById = new Map(clusters.map(cluster => [cluster.id, cluster]))
+  const clusterIds = new Set(clusterById.keys())
+  const levelBySize = new Map()
+  for (let index = 0; index < clusters.length; index += 1) {
+    const cluster = clusters[index]
+    if (!cluster.size || cluster.isHub) continue
+    levelBySize.set(cluster.size, state.ecosystemNodeClusterBySize.get(cluster.size) ?? new Map())
+  }
+  const resolveClusterForNode = nodeId => {
+    if (state.ecosystemHubCluster?.nodeIds.includes(nodeId) && clusterIds.has(state.ecosystemHubCluster.id)) {
+      return state.ecosystemHubCluster
+    }
+    for (const [size, lookup] of levelBySize) {
+      const cluster = lookup.get(nodeId)
+      if (cluster && clusterIds.has(cluster.id)) {
+        return clusterById.get(cluster.id) ?? cluster
+      }
     }
+    return null
   }
 
   const edgeByClusterPair = new Map()
   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)
+    const sourceCluster = resolveClusterForNode(edge.source)
+    const targetCluster = resolveClusterForNode(edge.target)
     if (!sourceCluster || !targetCluster || sourceCluster.id === targetCluster.id) {
       continue
     }
@@ -898,9 +1017,34 @@ const ecosystemEdgesForClusters = clusters => {
     })
   }
 
-  return Array.from(edgeByClusterPair.values())
+  const edges = Array.from(edgeByClusterPair.values())
     .sort((left, right) => right.weight - left.weight)
     .slice(0, ecosystemClusterEdgeLimit)
+  const hubCluster = state.ecosystemHubCluster && clusterIds.has(state.ecosystemHubCluster.id)
+    ? state.ecosystemHubCluster
+    : null
+  if (!hubCluster) {
+    return edges
+  }
+
+  const existingHubTargets = new Set(edges.flatMap(edge =>
+    edge.sourceCluster.id === hubCluster.id
+      ? [edge.targetCluster.id]
+      : edge.targetCluster.id === hubCluster.id
+        ? [edge.sourceCluster.id]
+        : []
+  ))
+  const syntheticHubEdges = clusters
+    .filter(cluster => cluster.id !== hubCluster.id && !existingHubTargets.has(cluster.id))
+    .slice(0, ecosystemHubEdgeLimit)
+    .map(cluster => ({
+      id: hubCluster.id + ':' + cluster.id,
+      sourceCluster: hubCluster,
+      targetCluster: cluster,
+      weight: 1,
+      inferred: true
+    }))
+  return edges.concat(syntheticHubEdges)
 }
 
 const edgeBudgetForCurrentFrame = () => {
@@ -2337,6 +2481,20 @@ 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 (cluster.isHub) {
+    return 5.2
+  }
+  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)
@@ -2498,7 +2656,11 @@ const computeRenderVisibility = () => {
     return
   }
 
-  if (state.transform.scale <= ecosystemClusterScaleThreshold && state.ecosystemClusters.length > 0) {
+  if (
+    state.visibleNodes.length > ecosystemActivationNodeThreshold &&
+    state.transform.scale <= ecosystemClusterScaleThreshold &&
+    state.ecosystemClusters.length > 0
+  ) {
     const clusters = selectHierarchicalEcosystemClusters(viewport)
       .sort((left, right) => right.count - left.count)
     state.renderClusters = clusters
@@ -2760,20 +2922,22 @@ 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 isHub = Boolean(cluster.isHub)
+      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 : isHub ? 4 : isEcosystem ? 1.1 : 4)) / safeScale
+      if (isHub || !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 && !isHub ? 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.86",
+  "version": "0.1.0-beta.88",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",