@andespindola/brainlink 0.1.0-beta.119 → 0.1.0-beta.120

package/README.md

@@ -88,7 +88,7 @@ Legacy `.jsonl.gz` packs are upgraded to `.blpk` automatically on first search/c
 - 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 fitted scene and zoom-in progressively reveals local detail.
-- Zoomed-out graph LOD samples visible nodes, priority links and stable hierarchy groups without replacing the whole scene during zoom.
+- Zoomed-out graph LOD renders hierarchy groups as normal graph nodes and expands the focused group into child nodes progressively as zoom increases.
 - Graph reset fits the full graph scene instead of starting in a separate macro overview mode.
 - 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.
@@ -604,7 +604,7 @@ The graph UI shows:
 - graph rendering safeguards (batched canvas drawing across graph sizes, edge draw caps, lower redraw rate, zoom-aware interaction)
 - adaptive CPU safeguards for large graphs: idle frame pacing, throttled background physics updates and cached viewport dimensions to reduce redraw/layout overhead while preserving interaction responsiveness
 - WebGL node and edge acceleration when supported, falling back to Canvas 2D without changing graph behavior
-- large graph LOD keeps the same real-node scene model as smaller graphs: visible nodes are sampled near the viewport/focus, real links are prioritized, and stable hierarchy groups provide zoom-out context without a synthetic 3D projection
+- large graph LOD keeps a recursive graph-of-graphs model: zoom-out shows one level of group nodes, zoom-in expands the focused node into its child graph, and deeper zoom repeats the same visual rule without a background glow layer
 
 The server indexes before starting by default. Use `--no-index` to skip that step:
 

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

@@ -12,6 +12,8 @@ const massiveSegmentedScaleThreshold = 0.45
 const massiveSegmentRepresentativeBudget = 760
 const massiveAutoFitMacroScale = 0.018
 const hierarchyGroupScaleThreshold = 0.62
+const hierarchyExpansionStartScale = 0.18
+const hierarchyExpansionEndScale = 0.62
 const minNodePixelRadius = 2.3
 const viewportPaddingPx = 280
 const worldCoordinateLimit = 5_000_000
@@ -42,6 +44,7 @@ const state = {
   groups: [],
   groupById: new Map(),
   leafGroups: [],
+  nodeLeafGroupById: new Map(),
   nodeById: new Map(),
   edges: [],
   visibleNodes: [],
@@ -1155,7 +1158,6 @@ const drawAcceleratedGraph = (width, height, drawEdges) => {
   ctx.save()
   ctx.translate(state.transform.x, state.transform.y)
   ctx.scale(state.transform.scale, state.transform.scale)
-  drawHierarchyGroups()
   if (drawEdges) {
     graphParts.selectedEdges.forEach(edge => drawGraphEdge(edge))
   }
@@ -1171,9 +1173,14 @@ const focusedGroup = () => {
     return null
   }
 
+  const selectedGroupId = state.selected?.groupId ?? state.hovered?.groupId
+  if (selectedGroupId) {
+    return state.groupById.get(selectedGroupId) ?? null
+  }
+
   const selectedId = state.selected?.id ?? state.hovered?.id
   if (selectedId) {
-    const selectedGroup = state.leafGroups.find(group => group.nodeIds.includes(selectedId))
+    const selectedGroup = state.nodeLeafGroupById.get(selectedId)
     if (selectedGroup) {
       return selectedGroup
     }
@@ -1190,75 +1197,149 @@ const focusedGroup = () => {
     .sort((left, right) => left.distance - right.distance)[0]?.group ?? null
 }
 
-const hierarchyGroupOpacity = (group, focus) => {
-  if (state.transform.scale >= hierarchyGroupScaleThreshold || state.groups.length === 0) {
-    return 0
-  }
+const groupRenderNodeId = group => 'group:' + group.id
+
+const hierarchyExpansionProgress = () => {
+  const scale = state.transform.scale
+  if (scale <= hierarchyExpansionStartScale) return 0
+  if (scale >= hierarchyExpansionEndScale) return 1
+  const progress = (scale - hierarchyExpansionStartScale) / (hierarchyExpansionEndScale - hierarchyExpansionStartScale)
+  return progress * progress * (3 - 2 * progress)
+}
+
+const groupRenderRadius = group => {
+  const childCount = Math.max(group.nodeIds.length, group.childGroupIds.length, 1)
+  return 10 + Math.min(Math.log2(childCount + 1) * 4.2, 22)
+}
+
+const createGroupRenderNode = group => ({
+  id: groupRenderNodeId(group),
+  groupId: group.id,
+  isGroupNode: true,
+  title: group.title,
+  path: '',
+  tags: [],
+  group: group.group,
+  segment: group.segment,
+  x: group.x,
+  y: group.y,
+  vx: 0,
+  vy: 0,
+  radius: groupRenderRadius(group)
+})
+
+const interpolateNodeFromGroup = (node, group, progress) => ({
+  ...node,
+  x: group.x + (node.x - group.x) * progress,
+  y: group.y + (node.y - group.y) * progress,
+  vx: 0,
+  vy: 0
+})
 
-  const base = state.transform.scale < 0.08 ? 0.28 : state.transform.scale < 0.22 ? 0.2 : 0.12
-  if (!focus) {
-    return base
+const parentHierarchyGroups = () =>
+  state.groups.filter(group => group.parentId === null)
+
+const hierarchyGroupsForScale = () => {
+  if (state.groups.length === 0) {
+    return []
   }
-  if (group.id === focus.id || group.childGroupIds.includes(focus.id) || group.id === focus.parentId) {
-    return Math.min(0.36, base + 0.12)
+  if (state.transform.scale < hierarchyExpansionStartScale) {
+    return parentHierarchyGroups()
   }
-
-  return base * 0.58
+  return state.leafGroups
 }
 
-const visibleHierarchyGroups = () => {
-  if (state.groups.length === 0 || state.transform.scale >= hierarchyGroupScaleThreshold) {
+const groupEdgesForRenderedGroups = (groupNodes) => {
+  if (groupNodes.length <= 1) {
     return []
   }
 
-  const viewport = expandViewportBounds(worldViewportBounds(), 900 / Math.max(state.transform.scale, 0.0001))
-  const groups = state.groups.filter(group =>
-    group.x + group.radius >= viewport.minX &&
-    group.x - group.radius <= viewport.maxX &&
-    group.y + group.radius >= viewport.minY &&
-    group.y - group.radius <= viewport.maxY
-  )
-  const level = groups.some(group => group.parentId === null && group.childGroupIds.length > 0 && state.transform.scale < 0.18)
-    ? 1
-    : 0
+  const groupByNodeId = new Map()
+  const groupNodeIds = (group) => {
+    if (!group) return []
+    if (group.nodeIds.length > 0) return group.nodeIds
+    return group.childGroupIds.flatMap(childGroupId => groupNodeIds(state.groupById.get(childGroupId)))
+  }
+
+  groupNodes.forEach((groupNode) => {
+    const group = state.groupById.get(groupNode.groupId)
+    groupNodeIds(group).forEach((nodeId) => {
+      groupByNodeId.set(nodeId, groupNode)
+    })
+  })
+
+  const selected = new Map()
+  for (let index = 0; index < state.visibleEdges.length; index += 1) {
+    const edge = state.visibleEdges[index]
+    if (!edge.target) continue
+    const sourceGroup = groupByNodeId.get(edge.source)
+    const targetGroup = groupByNodeId.get(edge.target)
+    if (!sourceGroup || !targetGroup || sourceGroup.id === targetGroup.id) continue
+
+    const key = sourceGroup.id < targetGroup.id
+      ? sourceGroup.id + '|' + targetGroup.id
+      : targetGroup.id + '|' + sourceGroup.id
+    const current = selected.get(key)
+    if (current && edgeWeight(current) >= edgeWeight(edge)) continue
+
+    selected.set(key, {
+      source: sourceGroup.id,
+      target: targetGroup.id,
+      targetTitle: targetGroup.title,
+      weight: edgeWeight(edge),
+      priority: edge.priority || 'normal',
+      sourceNode: sourceGroup,
+      targetNode: targetGroup
+    })
+  }
 
-  return groups
-    .filter(group => group.level === level || group.parentId === null)
-    .slice(0, 1400)
+  return Array.from(selected.values()).slice(0, edgeBudgetForCurrentFrame())
 }
 
-const drawHierarchyGroups = () => {
-  const groups = visibleHierarchyGroups()
-  if (groups.length === 0) {
-    return
+const computeHierarchyRenderVisibility = (viewport) => {
+  if (state.groups.length === 0 || state.visibleNodes.length <= 1000 || state.transform.scale >= hierarchyGroupScaleThreshold) {
+    return false
   }
 
+  const progress = hierarchyExpansionProgress()
   const focus = focusedGroup()
-  for (let index = 0; index < groups.length; index += 1) {
-    const group = groups[index]
-    const opacity = hierarchyGroupOpacity(group, focus)
-    if (opacity <= 0) {
-      continue
-    }
-
-    const isFocus = focus && (group.id === focus.id || group.childGroupIds.includes(focus.id) || group.id === focus.parentId)
-    ctx.beginPath()
-    ctx.arc(group.x, group.y, group.radius * (isFocus ? 1.04 : 1), 0, Math.PI * 2)
-    ctx.fillStyle = 'rgba(148, 163, 184, ' + (opacity * 0.12) + ')'
-    ctx.fill()
-    ctx.lineWidth = isFocus ? 2.2 : 1.2
-    ctx.strokeStyle = 'rgba(148, 163, 184, ' + opacity + ')'
-    ctx.stroke()
+  const groups = hierarchyGroupsForScale()
+    .filter(group =>
+      group.x + group.radius >= viewport.minX &&
+      group.x - group.radius <= viewport.maxX &&
+      group.y + group.radius >= viewport.minY &&
+      group.y - group.radius <= viewport.maxY
+    )
+    .slice(0, renderNodeBudget)
+  const groupNodes = groups.map(createGroupRenderNode)
+
+  if (progress <= 0.02 || !focus) {
+    state.renderNodes = groupNodes
+    state.renderEdges = groupEdgesForRenderedGroups(groupNodes)
+    return true
+  }
+
+  const focusIds = new Set(focus.nodeIds)
+  const childLimit = Math.max(160, Math.min(zoomedMassiveRenderNodeBudget, Math.floor(renderNodeBudget * progress * 2.4)))
+  const childNodes = selectStableSampleNodes(
+    state.visibleNodes.filter(node => focusIds.has(node.id)),
+    childLimit
+  ).map(node => interpolateNodeFromGroup(node, focus, progress))
+  const childIds = new Set(childNodes.map(node => node.id))
+  const childById = new Map(childNodes.map(node => [node.id, node]))
+  const visibleGroupNodes = groupNodes.filter(node => node.groupId !== focus.id || progress < 0.92)
+  const groupEdges = groupEdgesForRenderedGroups(visibleGroupNodes)
+  const childEdges = progress > 0.32
+    ? collectVisibleEdgesForNodes(childIds).map(edge => ({
+      ...edge,
+      sourceNode: childById.get(edge.source) ?? edge.sourceNode,
+      targetNode: childById.get(edge.target) ?? edge.targetNode
+    }))
+    : []
 
-    if (state.transform.scale >= 0.12 && groups.length <= 220) {
-      ctx.fillStyle = 'rgba(226, 232, 240, ' + Math.min(0.86, opacity + 0.34) + ')'
-      ctx.font = '12px Inter, system-ui, sans-serif'
-      ctx.textAlign = 'center'
-      ctx.textBaseline = 'middle'
-      ctx.fillText(group.title.slice(0, 36), group.x, group.y)
-    }
-  }
-  ctx.globalAlpha = 1
+  state.renderNodes = mergeUniqueNodes(childNodes, visibleGroupNodes, Math.max(renderNodeBudget, childLimit + visibleGroupNodes.length))
+  state.renderEdges = childEdges.concat(groupEdges).slice(0, edgeBudgetForCurrentFrame())
+  return true
 }
 
 const edgePairKey = (source, target) =>
@@ -1651,6 +1732,7 @@ const ensureHubNodesInRenderedSet = (nodes) => {
 }
 
 const zoomCapByNodeCount = (nodeCount) => {
+  if (state.groups.length > 0) return 512
   if (nodeCount > 50000) return 5.4
   if (nodeCount > 20000) return 4.8
   if (nodeCount > 6000) return 4.2
@@ -2243,7 +2325,7 @@ const settleNeighborhoodAroundNode = (dragNode) => {
 const hitNode = point => {
   computeRenderVisibility()
   const hitScaleFloor = state.nodes.length > massiveGraphNodeThreshold
-    ? 0.2
+    ? (state.renderNodes.some(node => node.isGroupNode) ? 0 : 0.2)
     : state.nodes.length > largeGraphNodeThreshold
       ? 0.34
       : 0
@@ -2263,6 +2345,9 @@ const hitNode = point => {
 }
 
 const baseNodeRadius = node => {
+  if (node.isGroupNode && Number.isFinite(node.radius)) {
+    return node.radius
+  }
   const degree = state.nodeDegrees.get(node.id) ?? 0
   return 9 + Math.min(degree, 8) * 1.6
 }
@@ -2340,6 +2425,10 @@ const computeRenderVisibility = () => {
   state.lastViewportKey = viewportKey
   state.renderVisibilityDirty = false
 
+  if (computeHierarchyRenderVisibility(viewport)) {
+    return
+  }
+
   if (state.visibleNodes.length <= 2000) {
     state.renderNodes = state.visibleNodes
     const ids = new Set(state.renderNodes.map((node) => node.id))
@@ -2577,7 +2666,6 @@ const render = now => {
     ctx.save()
     ctx.translate(state.transform.x, state.transform.y)
     ctx.scale(state.transform.scale, state.transform.scale)
-    drawHierarchyGroups()
     if (drawEdges) {
       drawGraphEdges()
     }
@@ -2639,7 +2727,7 @@ const fetchNodeDetails = async node => {
 const wait = async (milliseconds) => new Promise(resolve => setTimeout(resolve, milliseconds))
 
 const openContentDialog = async node => {
-  if (!node) return
+  if (!node || node.isGroupNode) return
   elements.contentTitle.textContent = node.title || 'Loading...'
   elements.contentPath.textContent = node.path || 'Loading...'
   elements.contentTags.innerHTML = Array.isArray(node.tags) && node.tags.length
@@ -2683,6 +2771,23 @@ const openContentDialog = async node => {
 }
 
 const selectNode = (node, options = { openContent: false }) => {
+  if (node?.isGroupNode) {
+    state.selected = node
+    const rect = canvas.getBoundingClientRect()
+    const targetScale = clampScale(Math.max(state.transform.scale * 1.8, hierarchyExpansionStartScale * 1.08))
+    state.zoomTransition = {
+      active: true,
+      source: 'group',
+      screenX: Math.max(rect.width, 320) / 2,
+      screenY: Math.max(rect.height, 320) / 2,
+      worldX: node.x,
+      worldY: node.y,
+      targetScale
+    }
+    state.lastZoomFocus = { x: node.x, y: node.y, at: performance.now() }
+    markRenderDirty()
+    return
+  }
   state.selected = node
   if (node && options.openContent) {
     openContentDialog(node).catch(() => {
@@ -2986,6 +3091,7 @@ const loadGraph = async (options = { reset: false }) => {
   state.groups = layout.groups
   state.groupById = new Map(state.groups.map(group => [group.id, group]))
   state.leafGroups = state.groups.filter(group => group.nodeIds.length > 0)
+  state.nodeLeafGroupById = new Map(state.leafGroups.flatMap(group => group.nodeIds.map(nodeId => [nodeId, group])))
   state.nodeById = new Map(state.nodes.map((node) => [node.id, node]))
   state.edges = layout.edges
   state.nodeDegrees = state.edges.reduce((degrees, edge) => {

package/docs/AGENT_USAGE.md

@@ -607,7 +607,7 @@ Without `--vault`, the graph UI serves `$HOME/.brainlink/vault`.
 
 The frontend includes an agent selector that shows only the agent id. Selecting an agent calls the same read APIs with `agent=<agent-id>` and renders that namespace instead of merging every agent into one graph.
 
-Graph navigation controls include zoom in, zoom out, fit visible nodes and reset-to-fit-all nodes. Mouse wheel zoom (including `cmd+scroll` and `ctrl+scroll`) is anchored to the cursor. Keyboard shortcuts are `+` (zoom in), `-` (zoom out) and `0` (reset fit). Double-click on canvas zooms in at cursor position. Totals for notes, links and tags stay visible as floating metrics under the Brainlink title, and node details open on click in a modal (tags, outgoing links, backlinks and Markdown content). Vaults above 1000 notes also expose stable hierarchy groups of up to 1000 direct nodes, with recursive parent groups when a level exceeds 1000 groups; zoom-out draws those groups as context while preserving the real-node scene.
+Graph navigation controls include zoom in, zoom out, fit visible nodes and reset-to-fit-all nodes. Mouse wheel zoom (including `cmd+scroll` and `ctrl+scroll`) is anchored to the cursor. Keyboard shortcuts are `+` (zoom in), `-` (zoom out) and `0` (reset fit). Double-click on canvas zooms in at cursor position. Totals for notes, links and tags stay visible as floating metrics under the Brainlink title, and node details open on click in a modal (tags, outgoing links, backlinks and Markdown content). Vaults above 1000 notes also expose stable hierarchy groups of up to 1000 direct nodes, with recursive parent groups when a level exceeds 1000 groups; zoom-out renders those groups as normal graph nodes, and zoom-in expands the focused group into its child graph without drawing a background glow layer.
 During graph filtering, Brainlink keeps hub context nodes visible (`Memory Hub`/`MOC`/high-degree fallback) so filtered views still show relationship anchors.
 
 The command reindexes by default, then serves:

package/package.json

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