@andespindola/brainlink 0.1.0-beta.123 → 0.1.0-beta.125

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 rendering keeps the flat node scene and adds stable hierarchical mesh groups for vaults above 1000 notes, with every visible graph level capped at 1000 nodes and recursive parent groups when a level itself exceeds 1000 groups.
+- Graph rendering keeps the flat node scene and adds stable hierarchical mesh groups for vaults above 1000 notes, with every visible graph level capped at 1000 nodes, the macro level projected as its own graph, and recursive parent groups when a level itself exceeds 1000 groups.
 - 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.
@@ -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 mesh model: zoom-out shows one level capped at 1000 group nodes, zoom-in expands the framed node into its child graph capped at 1000 nodes, micro view renders only that focused subgraph, and zoom-out restores sibling groups
+- large graph LOD keeps a recursive graph-of-graphs mesh model: zoom-out shows one projected graph level capped at 1000 group nodes, zoom-in expands the framed node into its child graph capped at 1000 nodes, micro view renders only that focused subgraph in a local frame anchored to the group node, 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

@@ -11,7 +11,6 @@ const massiveOverviewScaleThreshold = 0.065
 const massiveSegmentedScaleThreshold = 0.45
 const massiveSegmentRepresentativeBudget = 760
 const massiveAutoFitMacroScale = 0.018
-const hierarchyGroupScaleThreshold = 0.62
 const hierarchyExpansionStartScale = 0.18
 const hierarchyMicroEnterCoverage = 0.72
 const hierarchyMicroExitCoverage = 0.52
@@ -1213,6 +1212,11 @@ const groupRenderRadius = group => {
   return 10 + Math.min(Math.log2(childCount + 1) * 4.2, 22)
 }
 
+const childGraphRenderRadius = group => {
+  const childCount = Math.max(group.nodeIds.length, group.childGroupIds.length, 1)
+  return Math.max(420, Math.min(1800, Math.sqrt(childCount) * 24))
+}
+
 const createGroupRenderNode = group => ({
   id: groupRenderNodeId(group),
   groupId: group.id,
@@ -1229,13 +1233,89 @@ const createGroupRenderNode = group => ({
   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 arrangeGraphLevelNodes = (nodes, radiusForNode = () => 1) => {
+  if (nodes.length <= 1) {
+    return nodes
+  }
+
+  const centerNode = nodes
+    .map(node => ({
+      node,
+      score: Math.max(node.nodeIds?.length ?? 0, node.childGroupIds?.length ?? 0, 1) + (node.externalEdges?.length ?? 0)
+    }))
+    .sort((left, right) => right.score - left.score || left.node.title.localeCompare(right.node.title))[0]?.node
+  const outerNodes = nodes
+    .filter(node => node.id !== centerNode?.id)
+    .sort((left, right) => left.segment.localeCompare(right.segment) || left.title.localeCompare(right.title))
+  const baseRadius = Math.max(520, Math.min(2200, Math.sqrt(nodes.length) * 135))
+  const goldenAngle = Math.PI * (3 - Math.sqrt(5))
+  const arranged = centerNode
+    ? [{ ...centerNode, x: 0, y: 0, radius: radiusForNode(centerNode) }]
+    : []
+
+  outerNodes.forEach((node, index) => {
+    const ringRadius = baseRadius * Math.sqrt((index + 1) / Math.max(outerNodes.length, 1))
+    const angle = index * goldenAngle
+    arranged.push({
+      ...node,
+      x: Math.cos(angle) * ringRadius,
+      y: Math.sin(angle) * ringRadius,
+      radius: radiusForNode(node)
+    })
+  })
+
+  return arranged
+}
+
+const localGraphBounds = nodes => {
+  if (nodes.length === 0) {
+    return { centerX: 0, centerY: 0, radius: 1 }
+  }
+
+  const bounds = nodes.reduce(
+    (current, node) => ({
+      minX: Math.min(current.minX, node.x),
+      maxX: Math.max(current.maxX, node.x),
+      minY: Math.min(current.minY, node.y),
+      maxY: Math.max(current.maxY, node.y)
+    }),
+    {
+      minX: Number.POSITIVE_INFINITY,
+      maxX: Number.NEGATIVE_INFINITY,
+      minY: Number.POSITIVE_INFINITY,
+      maxY: Number.NEGATIVE_INFINITY
+    }
+  )
+  const centerX = (bounds.minX + bounds.maxX) / 2
+  const centerY = (bounds.minY + bounds.maxY) / 2
+  const radius = nodes.reduce(
+    (largest, node) => Math.max(largest, Math.hypot(node.x - centerX, node.y - centerY)),
+    1
+  )
+
+  return { centerX, centerY, radius }
+}
+
+const projectNodeIntoGroupGraph = (node, group, bounds) => {
+  const targetRadius = childGraphRenderRadius(group)
+  const scale = targetRadius / Math.max(bounds.radius, 1)
+
+  return {
+    x: group.x + (node.x - bounds.centerX) * scale,
+    y: group.y + (node.y - bounds.centerY) * scale
+  }
+}
+
+const interpolateNodeFromGroup = (node, group, bounds, progress) => {
+  const projected = projectNodeIntoGroupGraph(node, group, bounds)
+  return {
+    ...node,
+    x: group.x + (projected.x - group.x) * progress,
+    y: group.y + (projected.y - group.y) * progress,
+    vx: 0,
+    vy: 0
+  }
+}
 
 const parentHierarchyGroups = () =>
   state.groups.filter(group => group.parentId === null)
@@ -1245,9 +1325,9 @@ const hierarchyGroupsForScale = () => {
     return []
   }
   if (state.transform.scale < hierarchyExpansionStartScale) {
-    return parentHierarchyGroups()
+    return arrangeGraphLevelNodes(parentHierarchyGroups(), groupRenderRadius)
   }
-  return state.leafGroups
+  return arrangeGraphLevelNodes(state.leafGroups, groupRenderRadius)
 }
 
 const groupViewportCoverage = (group, viewport) => {
@@ -1257,7 +1337,7 @@ const groupViewportCoverage = (group, viewport) => {
   const centerX = (viewport.minX + viewport.maxX) / 2
   const centerY = (viewport.minY + viewport.maxY) / 2
   const centerDistance = Math.hypot(group.x - centerX, group.y - centerY)
-  const fitCoverage = Math.min(1, group.radius / Math.max(viewportRadius, 1))
+  const fitCoverage = Math.min(1, childGraphRenderRadius(group) / Math.max(viewportRadius, 1))
   const centerCoverage = 1 - Math.min(1, centerDistance / Math.max(viewportRadius, 1))
 
   return fitCoverage * 0.72 + centerCoverage * 0.28
@@ -1269,7 +1349,9 @@ const groupWithCoverage = (group, viewport) => ({
 })
 
 const updateHierarchyFocusGroup = (groups, viewport) => {
-  const current = state.hierarchyFocusGroupId ? state.groupById.get(state.hierarchyFocusGroupId) : null
+  const current = state.hierarchyFocusGroupId
+    ? groups.find(group => group.id === state.hierarchyFocusGroupId) ?? null
+    : null
   const currentCoverage = current ? groupViewportCoverage(current, viewport) : 0
 
   if (
@@ -1352,7 +1434,7 @@ const groupEdgesForRenderedGroups = (groupNodes) => {
 }
 
 const computeHierarchyRenderVisibility = (viewport) => {
-  if (state.groups.length === 0 || state.visibleNodes.length <= 1000 || state.transform.scale >= hierarchyGroupScaleThreshold) {
+  if (state.groups.length === 0 || state.visibleNodes.length <= 1000) {
     state.hierarchyFocusGroupId = null
     return false
   }
@@ -1376,11 +1458,13 @@ const computeHierarchyRenderVisibility = (viewport) => {
   }
 
   const focusIds = new Set(focus.nodeIds)
+  const rawChildNodes = state.visibleNodes.filter(node => focusIds.has(node.id))
+  const childBounds = localGraphBounds(rawChildNodes)
   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)),
+    rawChildNodes,
     childLimit
-  ).map(node => interpolateNodeFromGroup(node, focus, progress))
+  ).map(node => interpolateNodeFromGroup(node, focus, childBounds, 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
@@ -1925,7 +2009,11 @@ const fitView = (options = { useFiltered: true, preferHubCenter: true }) => {
   const width = Math.max(rect.width, 320)
   const height = Math.max(rect.height, 320)
   const nodes = options.useFiltered ? filteredNodes() : state.nodes
-  const bounds = graphBounds(nodes)
+  const hierarchyFitNodes = state.groups.length > 0 && nodes.length > 1000
+    ? arrangeGraphLevelNodes(parentHierarchyGroups(), groupRenderRadius).map(createGroupRenderNode)
+    : null
+  const fitNodes = hierarchyFitNodes ?? nodes
+  const bounds = graphBounds(fitNodes)
 
   if (!bounds) {
     state.transform = { x: width / 2, y: height / 2, scale: 1 }
@@ -1945,17 +2033,20 @@ const fitView = (options = { useFiltered: true, preferHubCenter: true }) => {
     if (nodeCount <= 2000) return 140
     return 180
   }
-  const padding = paddingByNodeCount(nodes.length)
+  const padding = paddingByNodeCount(fitNodes.length)
   const scaleX = width / (bounds.width + padding * 2)
   const scaleY = height / (bounds.height + padding * 2)
   const fitScale = Math.min(scaleX, scaleY)
-  const biasedScale = clampScale(fitScale * fitScaleBiasByNodeCount(nodes.length))
-  const scaleRange = autoFitScaleRangeByNodeCount(nodes.length)
+  const biasedScale = clampScale(fitScale * fitScaleBiasByNodeCount(fitNodes.length))
+  const scaleRange = autoFitScaleRangeByNodeCount(fitNodes.length)
   const baselineScale = clampScale(Math.min(scaleRange.max, Math.max(scaleRange.min, biasedScale)))
-  const resolvedScale = nodes.length > massiveGraphNodeThreshold
+  const resolvedScale = nodes.length > massiveGraphNodeThreshold && !hierarchyFitNodes
     ? clampScale(Math.min(baselineScale, massiveAutoFitMacroScale))
     : baselineScale
   const hubCenter =
+    hierarchyFitNodes
+      ? null
+      :
     options.preferHubCenter && isDominantHub(state.primaryHub, nodes.length) && nodes.some((node) => node.id === state.primaryHub.id)
       ? state.primaryHub
       : null

package/dist/application/get-graph-view.js

@@ -16,10 +16,48 @@ const groupCoverage = (group, input) => {
     const centerX = input.x + input.width / 2;
     const centerY = input.y + input.height / 2;
     const centerDistance = Math.hypot(group.x - centerX, group.y - centerY);
-    const fitCoverage = Math.min(1, group.radius / Math.max(viewportRadius, 1));
+    const fitCoverage = Math.min(1, childGraphRenderRadius(group) / Math.max(viewportRadius, 1));
     const centerCoverage = 1 - Math.min(1, centerDistance / Math.max(viewportRadius, 1));
     return fitCoverage * 0.72 + centerCoverage * 0.28;
 };
+const childGraphRenderRadius = (group) => {
+    const childCount = Math.max(group.nodeIds.length, group.childGroupIds.length, 1);
+    return Math.max(420, Math.min(1800, Math.sqrt(childCount) * 24));
+};
+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 arrangeGraphLevelGroups = (groups) => {
+    if (groups.length <= 1) {
+        return groups.map((group) => ({ ...group, radius: groupRenderRadius(group) }));
+    }
+    const centerGroup = groups
+        .map((group) => ({
+        group,
+        score: Math.max(group.nodeIds.length, group.childGroupIds.length, 1) + group.externalEdges.length
+    }))
+        .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 baseRadius = Math.max(520, Math.min(2200, Math.sqrt(groups.length) * 135));
+    const goldenAngle = Math.PI * (3 - Math.sqrt(5));
+    const arranged = centerGroup
+        ? [{ ...centerGroup, x: 0, y: 0, radius: groupRenderRadius(centerGroup) }]
+        : [];
+    outerGroups.forEach((group, index) => {
+        const ringRadius = baseRadius * Math.sqrt((index + 1) / Math.max(outerGroups.length, 1));
+        const angle = index * goldenAngle;
+        arranged.push({
+            ...group,
+            x: Math.cos(angle) * ringRadius,
+            y: Math.sin(angle) * ringRadius,
+            radius: groupRenderRadius(group)
+        });
+    });
+    return arranged;
+};
 const groupNode = (group) => [
     `group:${group.id}`,
     group.title,
@@ -38,6 +76,34 @@ const realNode = (node) => [
     node.segment,
     'node'
 ];
+const graphBounds = (nodes) => {
+    if (nodes.length === 0) {
+        return { centerX: 0, centerY: 0, radius: 1 };
+    }
+    const bounds = nodes.reduce((current, node) => ({
+        minX: Math.min(current.minX, node.x),
+        maxX: Math.max(current.maxX, node.x),
+        minY: Math.min(current.minY, node.y),
+        maxY: Math.max(current.maxY, node.y)
+    }), {
+        minX: Number.POSITIVE_INFINITY,
+        maxX: Number.NEGATIVE_INFINITY,
+        minY: Number.POSITIVE_INFINITY,
+        maxY: Number.NEGATIVE_INFINITY
+    });
+    const centerX = (bounds.minX + bounds.maxX) / 2;
+    const centerY = (bounds.minY + bounds.maxY) / 2;
+    const radius = nodes.reduce((largest, node) => Math.max(largest, Math.hypot(node.x - centerX, node.y - centerY)), 1);
+    return { centerX, centerY, radius };
+};
+const projectNodeIntoGroupGraph = (node, group, bounds) => {
+    const scale = childGraphRenderRadius(group) / Math.max(bounds.radius, 1);
+    return {
+        ...node,
+        x: group.x + (node.x - bounds.centerX) * scale,
+        y: group.y + (node.y - bounds.centerY) * scale
+    };
+};
 const descendants = (group, groupById) => group.nodeIds.length > 0
     ? group.nodeIds
     : group.childGroupIds.flatMap((childId) => {
@@ -113,16 +179,27 @@ export const getGraphView = async (vaultPath, input) => {
             }
         };
     }
-    const visibleGroups = groups.filter((group) => group.parentId === null && inViewport(group, input));
-    const focused = groups
+    const rootGroups = arrangeGraphLevelGroups(groups.filter((group) => group.parentId === null));
+    const leafGroups = arrangeGraphLevelGroups(groups.filter((group) => group.nodeIds.length > 0));
+    const visibleGroups = rootGroups.filter((group) => inViewport(group, input));
+    const focused = leafGroups
         .filter((group) => group.nodeIds.length > 0 && inViewport(group, input))
         .map((group) => ({ group, coverage: groupCoverage(group, input) }))
         .sort((left, right) => right.coverage - left.coverage)[0];
     if (focused && input.scale >= macroScale && focused.coverage >= microCoverage) {
         const nodeIds = new Set(focused.group.nodeIds);
-        const nodes = layout.nodes
-            .filter((node) => nodeIds.has(node.id) && inViewport(node, input))
+        const projectedNodes = layout.nodes
+            .filter((node) => nodeIds.has(node.id));
+        const bounds = graphBounds(projectedNodes);
+        const nodesInViewport = projectedNodes
+            .map((node) => projectNodeIntoGroupGraph(node, focused.group, bounds))
+            .filter((node) => inViewport(node, input))
             .slice(0, nodeLimit);
+        const nodes = nodesInViewport.length > 0
+            ? nodesInViewport
+            : projectedNodes
+                .slice(0, nodeLimit)
+                .map((node) => projectNodeIntoGroupGraph(node, focused.group, bounds));
         const visibleNodeIds = new Set(nodes.map((node) => node.id));
         const viewNodes = nodes.map(realNode);
         return {
@@ -136,7 +213,7 @@ export const getGraphView = async (vaultPath, input) => {
             }
         };
     }
-    const groupsToRender = (visibleGroups.length > 0 ? visibleGroups : groups.filter((group) => group.parentId === null)).slice(0, nodeLimit);
+    const groupsToRender = (visibleGroups.length > 0 ? visibleGroups : rootGroups).slice(0, nodeLimit);
     const viewNodes = groupsToRender.map(groupNode);
     return {
         signature,

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 mesh groups of up to 1000 direct nodes, with recursive parent groups when a level exceeds 1000 groups; zoom-out renders those groups as normal mesh graph nodes, zoom-in expands a group only after it is framed in the viewport, and micro view renders only the focused subgraph 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 mesh groups of up to 1000 direct nodes, with recursive parent groups when a level exceeds 1000 groups; zoom-out renders the macro level as a projected mesh graph of group nodes, zoom-in expands a group only after it is framed in the viewport, and micro view renders only the focused subgraph in a local frame anchored to the group node until zoom-out restores sibling groups.
 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.123",
+  "version": "0.1.0-beta.125",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",