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

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 renders hierarchy groups as normal mesh graph nodes and expands a group only after it is framed in the viewport, progressively hiding sibling groups in micro view.
+- Zoomed-out graph LOD renders hierarchy groups as normal mesh graph nodes and expands a group from the focused node's current viewport position only after it is framed, progressively hiding sibling groups in micro view.
 - 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.
@@ -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 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
+- 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 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
 
 The server indexes before starting by default. Use `--no-index` to skip that step:
 

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

@@ -960,7 +960,7 @@ const drawGraphEdges = () => {
 const shouldDrawNodeLabels = (node, isSelected, isHovered) =>
   isSelected ||
   isHovered ||
-  (state.nodes.length > largeGraphNodeThreshold && state.transform.scale >= 0.62 && state.renderNodes.length <= 1200) ||
+  (state.nodes.length > largeGraphNodeThreshold && !state.renderNodes.some(item => !item.isGroupNode) && state.transform.scale >= 1.25 && state.renderNodes.length <= 420) ||
   (state.nodes.length <= largeGraphNodeThreshold && (state.transform.scale > 1.18 || state.nodes.length <= 25))
 
 const drawSingleNode = (node, options = { drawLabel: true }) => {
@@ -1048,7 +1048,14 @@ const drawGraphNodes = () => {
 
   drawNodeBatch(regularNodes)
 
-  if (state.transform.scale >= 0.62 && state.renderNodes.length <= 1200) {
+  const isRenderingHierarchyChildGraph = state.groups.length > 0 && state.renderNodes.some(node => !node.isGroupNode)
+  const shouldDrawBatchLabels = isRenderingHierarchyChildGraph
+    ? false
+    : state.nodes.length > largeGraphNodeThreshold
+    ? state.transform.scale >= 1.25 && state.renderNodes.length <= 420
+    : state.transform.scale >= 0.62 && state.renderNodes.length <= 1200
+
+  if (shouldDrawBatchLabels) {
     ctx.fillStyle = graphTheme.label
     ctx.font = '12px Inter, system-ui, sans-serif'
     ctx.textAlign = 'center'
@@ -1102,7 +1109,14 @@ const partitionGraphForAcceleratedRenderer = () => {
 }
 
 const drawGraphLabels = nodes => {
-  if (!(state.transform.scale >= 0.62 && state.renderNodes.length <= 1200)) {
+  const isRenderingHierarchyChildGraph = state.groups.length > 0 && state.renderNodes.some(node => !node.isGroupNode)
+  const shouldDrawLabels = isRenderingHierarchyChildGraph
+    ? false
+    : state.nodes.length > largeGraphNodeThreshold
+    ? state.transform.scale >= 1.25 && state.renderNodes.length <= 420
+    : state.transform.scale >= 0.62 && state.renderNodes.length <= 1200
+
+  if (!shouldDrawLabels) {
     return
   }
 
@@ -1267,51 +1281,49 @@ const arrangeGraphLevelNodes = (nodes, radiusForNode = () => 1) => {
   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 arrangeChildGraphNodes = (nodes, group, origin = group) => {
+  if (nodes.length <= 1) {
+    return nodes.map(node => ({ ...node, x: origin.x, y: origin.y }))
+  }
 
-const projectNodeIntoGroupGraph = (node, group, bounds) => {
   const targetRadius = childGraphRenderRadius(group)
-  const scale = targetRadius / Math.max(bounds.radius, 1)
+  const centerNode = nodes
+    .map(node => ({
+      node,
+      score: (state.nodeDegrees.get(node.id) ?? 0) + (node.tags?.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) => {
+      const leftDegree = state.nodeDegrees.get(left.id) ?? 0
+      const rightDegree = state.nodeDegrees.get(right.id) ?? 0
+      if (leftDegree !== rightDegree) return rightDegree - leftDegree
+      return left.title.localeCompare(right.title)
+    })
+  const goldenAngle = Math.PI * (3 - Math.sqrt(5))
+  const arranged = centerNode
+    ? [{ ...centerNode, x: origin.x, y: origin.y }]
+    : []
 
-  return {
-    x: group.x + (node.x - bounds.centerX) * scale,
-    y: group.y + (node.y - bounds.centerY) * scale
-  }
+  outerNodes.forEach((node, index) => {
+    const ringRadius = targetRadius * Math.sqrt((index + 1) / Math.max(outerNodes.length, 1))
+    const angle = index * goldenAngle
+    arranged.push({
+      ...node,
+      x: origin.x + Math.cos(angle) * ringRadius,
+      y: origin.y + Math.sin(angle) * ringRadius
+    })
+  })
+
+  return arranged
 }
 
-const interpolateNodeFromGroup = (node, group, bounds, progress) => {
-  const projected = projectNodeIntoGroupGraph(node, group, bounds)
+const interpolateNodeFromGroup = (node, origin, progress) => {
   return {
     ...node,
-    x: group.x + (projected.x - group.x) * progress,
-    y: group.y + (projected.y - group.y) * progress,
+    x: origin.x + (node.x - origin.x) * progress,
+    y: origin.y + (node.y - origin.y) * progress,
     vx: 0,
     vy: 0
   }
@@ -1459,12 +1471,12 @@ 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 childLimit = Math.max(90, Math.min(renderNodeBudget, Math.floor(renderNodeBudget * progress)))
+  const focusRenderNode = groupNodes.find(node => node.groupId === focus.id) ?? createGroupRenderNode(focus)
   const childNodes = selectStableSampleNodes(
-    rawChildNodes,
+    arrangeChildGraphNodes(rawChildNodes, focus, focusRenderNode),
     childLimit
-  ).map(node => interpolateNodeFromGroup(node, focus, childBounds, progress))
+  ).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
@@ -2499,6 +2511,9 @@ const baseNodeRadius = node => {
   if (node.isGroupNode && Number.isFinite(node.radius)) {
     return node.radius
   }
+  if (state.groups.length > 0 && !node.isGroupNode) {
+    return 4.8
+  }
   const degree = state.nodeDegrees.get(node.id) ?? 0
   return 9 + Math.min(degree, 8) * 1.6
 }

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

@@ -76,34 +76,6 @@ 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) => {
@@ -135,6 +107,47 @@ const realEdges = (edges, nodeIds) => edges
     .filter((edge) => Boolean(edge.target && nodeIds.has(edge.source) && nodeIds.has(edge.target)))
     .slice(0, edgeLimit)
     .map((edge) => [edge.source, edge.target, edge.weight, edge.priority]);
+const degreeMap = (edges) => edges.reduce((degrees, edge) => {
+    degrees.set(edge.source, (degrees.get(edge.source) ?? 0) + edge.weight);
+    if (edge.target) {
+        degrees.set(edge.target, (degrees.get(edge.target) ?? 0) + edge.weight);
+    }
+    return degrees;
+}, new Map());
+const arrangeChildGraphNodes = (nodes, group, degrees) => {
+    if (nodes.length <= 1) {
+        return nodes.map((node) => ({ ...node, x: group.x, y: group.y }));
+    }
+    const centerNode = nodes
+        .map((node) => ({
+        node,
+        score: (degrees.get(node.id) ?? 0) + node.tags.length
+    }))
+        .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) => {
+        const degreeDelta = (degrees.get(right.id) ?? 0) - (degrees.get(left.id) ?? 0);
+        if (degreeDelta !== 0)
+            return degreeDelta;
+        return left.title.localeCompare(right.title);
+    });
+    const targetRadius = childGraphRenderRadius(group);
+    const goldenAngle = Math.PI * (3 - Math.sqrt(5));
+    const arranged = centerNode
+        ? [{ ...centerNode, x: group.x, y: group.y }]
+        : [];
+    outerNodes.forEach((node, index) => {
+        const ringRadius = targetRadius * Math.sqrt((index + 1) / Math.max(outerNodes.length, 1));
+        const angle = index * goldenAngle;
+        arranged.push({
+            ...node,
+            x: group.x + Math.cos(angle) * ringRadius,
+            y: group.y + Math.sin(angle) * ringRadius
+        });
+    });
+    return arranged;
+};
 const edgePairKey = (left, right) => left < right ? `${left}|${right}` : `${right}|${left}`;
 const meshEdges = (nodes, existingEdges) => {
     if (nodes.length < 2) {
@@ -163,6 +176,7 @@ const withMeshEdges = (nodes, edges) => [...edges, ...meshEdges(nodes, edges)].s
 export const getGraphView = async (vaultPath, input) => {
     const { signature, layout } = await getGraphLayout(vaultPath, input.agentId);
     const groups = layout.groups ?? [];
+    const degrees = degreeMap(layout.edges);
     const groupById = new Map(groups.map((group) => [group.id, group]));
     if (groups.length === 0) {
         const nodes = layout.nodes.filter((node) => inViewport(node, input)).slice(0, nodeLimit);
@@ -188,18 +202,13 @@ export const getGraphView = async (vaultPath, 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 projectedNodes = layout.nodes
-            .filter((node) => nodeIds.has(node.id));
-        const bounds = graphBounds(projectedNodes);
-        const nodesInViewport = projectedNodes
-            .map((node) => projectNodeIntoGroupGraph(node, focused.group, bounds))
+        const arrangedNodes = arrangeChildGraphNodes(layout.nodes.filter((node) => nodeIds.has(node.id)), focused.group, degrees);
+        const nodesInViewport = arrangedNodes
             .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));
+            : arrangedNodes.slice(0, nodeLimit);
         const visibleNodeIds = new Set(nodes.map((node) => node.id));
         const viewNodes = nodes.map(realNode);
         return {

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 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.
+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 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.
 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.125",
+  "version": "0.1.0-beta.127",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",