@andespindola/brainlink 0.1.0-beta.130 → 0.1.0-beta.132

package/README.md

@@ -606,7 +606,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 a recursive graph-of-graphs model: zoom-out fills the projected macro level toward 1000 lightweight group nodes with sparse strongest-link edges, zoom-in expands the framed node from its current viewport position into its own radial child graph capped at 1000 nodes, micro view renders only that focused subgraph with dense-node label suppression in a local frame anchored to the rendered group node, and zoom-out restores sibling groups
+- large graph LOD keeps a recursive graph-of-graphs model: zoom-out fills the projected macro level toward 1000 lightweight group nodes with every aggregated link between visible groups, zoom-in grows the focused node into a local child graph anchored at the same point, once the child graph is framed the sibling groups stop rendering, groups with child groups open another graph level instead of jumping to leaf notes, and zoom-out restores sibling groups
 
 The server indexes before starting by default. Use `--no-index` to skip that step:
 

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

@@ -12,10 +12,13 @@ const massiveSegmentedScaleThreshold = 0.45
 const massiveSegmentRepresentativeBudget = 760
 const massiveAutoFitMacroScale = 0.018
 const hierarchyExpansionStartScale = 0.18
-const hierarchyMicroEnterCoverage = 0.72
-const hierarchyMicroExitCoverage = 0.52
-const hierarchyMicroEnterScale = 0.24
-const hierarchyMicroExitScale = 0.16
+const hierarchyMicroEnterCoverage = 0.58
+const hierarchyMicroExitCoverage = 0.38
+const hierarchyMicroEnterScale = 0.18
+const hierarchyMicroExitScale = 0.12
+const hierarchyFocusedOnlyProgress = 0.5
+const hierarchyFocusedOnlyCoverage = 0.4
+const hierarchyChildGraphFitMargin = 1.28
 const minNodePixelRadius = 2.3
 const viewportPaddingPx = 280
 const worldCoordinateLimit = 5_000_000
@@ -82,6 +85,7 @@ const state = {
   lastManualZoomAt: 0,
   lastZoomFocus: { x: 0, y: 0, at: 0 },
   hierarchyFocusGroupId: null,
+  hierarchyFocusStack: [],
   zoomTransition: {
     active: false,
     source: 'generic',
@@ -645,7 +649,7 @@ const createVisibleEdgeLookup = edges => {
 
 const edgeBudgetForCurrentFrame = () => {
   const zoom = state.transform.scale
-  if (zoom < 0.12) return 380
+  if (zoom < 0.12) return state.groups.length > 0 ? 1200 : 380
   if (zoom < 0.18) return 900
   if (zoom < 0.28) return 1700
   if (zoom < 0.45) return 2800
@@ -1317,6 +1321,43 @@ const arrangeChildGraphNodes = (nodes, group, origin = group) => {
   return arranged
 }
 
+const arrangeChildGroupNodes = (groups, parentGroup, origin) => {
+  if (groups.length <= 1) {
+    return groups.map(group => ({
+      ...createGroupRenderNode(group),
+      x: origin.x,
+      y: origin.y
+    }))
+  }
+
+  const targetRadius = childGraphRenderRadius(parentGroup)
+  const centerGroup = groups
+    .map(group => ({
+      group,
+      score: Math.max(group.nodeIds.length, group.childGroupIds.length, 1)
+    }))
+    .sort((left, right) => right.score - left.score || left.group.title.localeCompare(right.group.title))[0]?.group
+  const outerGroups = groups
+    .filter(group => group.id !== centerGroup?.id)
+    .sort((left, right) => left.segment.localeCompare(right.segment) || left.title.localeCompare(right.title))
+  const goldenAngle = Math.PI * (3 - Math.sqrt(5))
+  const arranged = centerGroup
+    ? [{ ...createGroupRenderNode(centerGroup), x: origin.x, y: origin.y }]
+    : []
+
+  outerGroups.forEach((group, index) => {
+    const ringRadius = targetRadius * Math.sqrt((index + 1) / Math.max(outerGroups.length, 1))
+    const angle = index * goldenAngle
+    arranged.push({
+      ...createGroupRenderNode(group),
+      x: origin.x + Math.cos(angle) * ringRadius,
+      y: origin.y + Math.sin(angle) * ringRadius
+    })
+  })
+
+  return arranged
+}
+
 const interpolateNodeFromGroup = (node, origin, progress) => {
   return {
     ...node,
@@ -1330,20 +1371,39 @@ const interpolateNodeFromGroup = (node, origin, progress) => {
 const parentHierarchyGroups = () =>
   state.groups.filter(group => group.parentId === null)
 
+const activeHierarchyParentGroup = () => {
+  for (let index = state.hierarchyFocusStack.length - 1; index >= 0; index -= 1) {
+    const group = state.groupById.get(state.hierarchyFocusStack[index])
+    if (group && group.childGroupIds.length > 0) {
+      return group
+    }
+  }
+  return null
+}
+
+const groupsBelongToParent = (groups, parentGroup) =>
+  Boolean(parentGroup) && groups.some(group =>
+    group.parentId === parentGroup.id || parentGroup.childGroupIds.includes(group.id)
+  )
+
 const hierarchyGroupsForScale = () => {
   if (state.groups.length === 0) {
     return []
   }
-  if (state.transform.scale < hierarchyExpansionStartScale) {
-    return arrangeGraphLevelNodes(parentHierarchyGroups(), groupRenderRadius)
+  const parentGroup = activeHierarchyParentGroup()
+  if (parentGroup) {
+    const childGroups = parentGroup.childGroupIds
+      .map(groupId => state.groupById.get(groupId))
+      .filter(Boolean)
+    return arrangeGraphLevelNodes(childGroups, groupRenderRadius)
   }
-  return arrangeGraphLevelNodes(state.leafGroups, groupRenderRadius)
+  return arrangeGraphLevelNodes(parentHierarchyGroups(), groupRenderRadius)
 }
 
 const groupViewportCoverage = (group, viewport) => {
   const viewportWidth = Math.max(viewport.maxX - viewport.minX, 1)
   const viewportHeight = Math.max(viewport.maxY - viewport.minY, 1)
-  const viewportRadius = Math.max(viewportWidth, viewportHeight) / 2
+  const viewportRadius = Math.min(viewportWidth, viewportHeight) / 2
   const centerX = (viewport.minX + viewport.maxX) / 2
   const centerY = (viewport.minY + viewport.maxY) / 2
   const centerDistance = Math.hypot(group.x - centerX, group.y - centerY)
@@ -1386,6 +1446,17 @@ const selectViewportItemsWithFill = (items, viewport, limit = renderNodeBudget)
 }
 
 const updateHierarchyFocusGroup = (groups, viewport) => {
+  const activeGroupIds = new Set(groups.map(group => group.id))
+  state.hierarchyFocusStack = state.hierarchyFocusStack.filter(groupId => state.groupById.has(groupId))
+  const parentGroup = activeHierarchyParentGroup()
+  if (!groupsBelongToParent(groups, parentGroup)) {
+    while (
+      state.hierarchyFocusStack.length > 0 &&
+      !activeGroupIds.has(state.hierarchyFocusStack[state.hierarchyFocusStack.length - 1])
+    ) {
+      state.hierarchyFocusStack.pop()
+    }
+  }
   const current = state.hierarchyFocusGroupId
     ? groups.find(group => group.id === state.hierarchyFocusGroupId) ?? null
     : null
@@ -1396,6 +1467,9 @@ const updateHierarchyFocusGroup = (groups, viewport) => {
     state.transform.scale >= hierarchyMicroExitScale &&
     currentCoverage >= hierarchyMicroExitCoverage
   ) {
+    if (current.childGroupIds.length > 0 && state.hierarchyFocusStack.at(-1) !== current.id) {
+      state.hierarchyFocusStack = [...state.hierarchyFocusStack, current.id]
+    }
     return current
   }
 
@@ -1405,13 +1479,19 @@ const updateHierarchyFocusGroup = (groups, viewport) => {
 
   if (
     candidate &&
-    state.transform.scale >= hierarchyMicroEnterScale &&
-    candidate.coverage >= hierarchyMicroEnterCoverage
+    state.transform.scale >= hierarchyMicroExitScale &&
+    candidate.coverage >= hierarchyMicroExitCoverage
   ) {
     state.hierarchyFocusGroupId = candidate.group.id
+    if (candidate.group.childGroupIds.length > 0 && state.hierarchyFocusStack.at(-1) !== candidate.group.id) {
+      state.hierarchyFocusStack = [...state.hierarchyFocusStack, candidate.group.id]
+    }
     return candidate.group
   }
 
+  if (state.hierarchyFocusStack.length > 0 && state.transform.scale < hierarchyMicroExitScale) {
+    state.hierarchyFocusStack = state.hierarchyFocusStack.slice(0, -1)
+  }
   state.hierarchyFocusGroupId = null
   return null
 }
@@ -1467,25 +1547,15 @@ const groupEdgesForRenderedGroups = (groupNodes) => {
     })
   }
 
-  const degreeCounts = new Map()
   return Array.from(selected.values())
     .sort((left, right) => edgeWeight(right) - edgeWeight(left) || left.source.localeCompare(right.source) || left.target.localeCompare(right.target))
-    .filter((edge) => {
-      const sourceCount = degreeCounts.get(edge.source) ?? 0
-      const targetCount = degreeCounts.get(edge.target) ?? 0
-      if (sourceCount >= 3 || targetCount >= 3) {
-        return false
-      }
-      degreeCounts.set(edge.source, sourceCount + 1)
-      degreeCounts.set(edge.target, targetCount + 1)
-      return true
-    })
     .slice(0, Math.min(hierarchyGroupEdgeLimit, edgeBudgetForCurrentFrame()))
 }
 
 const computeHierarchyRenderVisibility = (viewport) => {
   if (state.groups.length === 0 || state.visibleNodes.length <= 1000) {
     state.hierarchyFocusGroupId = null
+    state.hierarchyFocusStack = []
     return false
   }
 
@@ -1502,25 +1572,33 @@ const computeHierarchyRenderVisibility = (viewport) => {
 
   const focusIds = new Set(focus.nodeIds)
   const rawChildNodes = state.visibleNodes.filter(node => focusIds.has(node.id))
-  const childLimit = Math.max(90, Math.min(renderNodeBudget, Math.floor(renderNodeBudget * progress)))
+  const focusChildGroups = focus.childGroupIds
+    .map(groupId => state.groupById.get(groupId))
+    .filter(Boolean)
+  const childLimit = Math.min(renderNodeBudget, Math.max(1, Math.floor(renderNodeBudget * progress)))
   const focusRenderNode = groupNodes.find(node => node.groupId === focus.id) ?? createGroupRenderNode(focus)
-  const childNodes = selectStableSampleNodes(
-    arrangeChildGraphNodes(rawChildNodes, focus, focusRenderNode),
-    childLimit
-  ).map(node => interpolateNodeFromGroup(node, focusRenderNode, progress))
+  const arrangedChildren = focusChildGroups.length > 0
+    ? arrangeChildGroupNodes(focusChildGroups, focus, focusRenderNode)
+    : arrangeChildGraphNodes(rawChildNodes, focus, focusRenderNode)
+  const childNodes = selectStableSampleNodes(arrangedChildren, childLimit)
+    .map(node => interpolateNodeFromGroup(node, focusRenderNode, progress))
   const childIds = new Set(childNodes.map(node => node.id))
   const childById = new Map(childNodes.map(node => [node.id, node]))
-  const isMicroView = progress >= 0.72
+  const isMicroView =
+    progress >= hierarchyFocusedOnlyProgress ||
+    groupViewportCoverage(focus, viewport) >= hierarchyFocusedOnlyCoverage
   const visibleGroupNodes = isMicroView
     ? []
     : groupNodes.filter(node => node.groupId !== focus.id || progress < 0.92)
   const groupEdges = isMicroView ? [] : 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
-    }))
+  const childEdges = (isMicroView || progress > 0.02)
+    ? focusChildGroups.length > 0
+      ? groupEdgesForRenderedGroups(childNodes)
+      : collectVisibleEdgesForNodes(childIds).map(edge => ({
+        ...edge,
+        sourceNode: childById.get(edge.source) ?? edge.sourceNode,
+        targetNode: childById.get(edge.target) ?? edge.targetNode
+      }))
     : []
 
   state.renderNodes = mergeUniqueNodes(childNodes, visibleGroupNodes, Math.max(renderNodeBudget, childLimit + visibleGroupNodes.length))
@@ -1996,6 +2074,11 @@ const fitView = (options = { useFiltered: true, preferHubCenter: true }) => {
 
 const resetView = () => fitView({ useFiltered: false, preferHubCenter: false })
 
+const resetHierarchyFocus = () => {
+  state.hierarchyFocusGroupId = null
+  state.hierarchyFocusStack = []
+}
+
 const focusPrimaryHub = () => {
   const hub = state.primaryHub
   if (!hub) {
@@ -2018,6 +2101,30 @@ const focusPrimaryHub = () => {
   markRenderDirty()
 }
 
+const childGraphFitScaleForGroup = (group, viewportWidth, viewportHeight) => {
+  const graphDiameter = Math.max(childGraphRenderRadius(group) * 2 * hierarchyChildGraphFitMargin, 1)
+  const available = Math.max(Math.min(viewportWidth, viewportHeight) - 96, 240)
+  return clampScale(available / graphDiameter)
+}
+
+const childGraphFitTransition = (node, group) => {
+  const rect = canvas.getBoundingClientRect()
+  const width = Math.max(rect.width, 320)
+  const height = Math.max(rect.height, 320)
+  const fitScale = childGraphFitScaleForGroup(group, width, height)
+  const nextScale = clampScale(Math.max(fitScale, state.transform.scale * 1.08, hierarchyMicroExitScale * 1.02))
+
+  return {
+    active: true,
+    source: 'group',
+    screenX: width / 2,
+    screenY: height / 2,
+    worldX: node.x,
+    worldY: node.y,
+    targetScale: nextScale
+  }
+}
+
 const layoutDensityScaleForNodeCount = (nodeCount) => {
   if (nodeCount > 50000) return 0.26
   if (nodeCount > 20000) return 0.3
@@ -2857,19 +2964,21 @@ 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 = {
+    const group = state.groupById.get(node.groupId)
+    state.zoomTransition = group ? childGraphFitTransition(node, group) : {
       active: true,
       source: 'group',
-      screenX: Math.max(rect.width, 320) / 2,
-      screenY: Math.max(rect.height, 320) / 2,
+      screenX: state.viewport.width / 2,
+      screenY: state.viewport.height / 2,
       worldX: node.x,
       worldY: node.y,
-      targetScale
+      targetScale: clampScale(Math.max(state.transform.scale * 1.08, hierarchyMicroExitScale * 1.02))
     }
     state.lastZoomFocus = { x: node.x, y: node.y, at: performance.now() }
     state.hierarchyFocusGroupId = node.groupId
+    if (group?.childGroupIds.length && state.hierarchyFocusStack.at(-1) !== group.id) {
+      state.hierarchyFocusStack = [...state.hierarchyFocusStack, group.id]
+    }
     markRenderDirty()
     return
   }
@@ -3003,10 +3112,12 @@ const bindEvents = () => {
   })
   if (elements.fit) {
     elements.fit.addEventListener('click', () => {
+      resetHierarchyFocus()
       focusPrimaryHub()
     })
   }
   elements.reset.addEventListener('click', () => {
+    resetHierarchyFocus()
     resetView()
   })
   elements.contentClose.addEventListener('click', () => elements.contentDialog.close())
@@ -3175,6 +3286,7 @@ const loadGraph = async (options = { reset: false }) => {
   state.nodes = layout.nodes
   state.groups = layout.groups
   state.hierarchyFocusGroupId = null
+  state.hierarchyFocusStack = []
   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])))

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 that fill each visible graph level toward 1000 nodes while keeping every group capped at 1000 child nodes; zoom-out renders the macro level as a sparse strongest-link graph of group nodes, zoom-in expands a group from the focused node's current viewport position only after it is framed, and micro view renders only the focused radial child graph with dense-node label suppression in a local frame anchored to the rendered group node until zoom-out restores sibling groups.
+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 that fill each visible graph level toward 1000 nodes while keeping every group capped at 1000 child nodes; zoom-out renders the macro level with every aggregated link between visible group nodes, zoom-in grows the focused node into a local child graph anchored at the same point, once the child graph is framed the sibling groups stop rendering, and groups with child groups open another graph level instead of jumping directly to leaf notes.
 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.130",
+  "version": "0.1.0-beta.132",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",