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

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 graph nodes and expands the focused group into child nodes progressively as zoom increases.
+- Zoomed-out graph LOD renders hierarchy groups as normal graph nodes and expands a group only after it is framed in the viewport, 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.
@@ -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 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
+- large graph LOD keeps a recursive graph-of-graphs model: zoom-out shows one level of group nodes, zoom-in expands the framed node into its child graph, micro view renders only that focused subgraph, 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

@@ -13,7 +13,10 @@ const massiveSegmentRepresentativeBudget = 760
 const massiveAutoFitMacroScale = 0.018
 const hierarchyGroupScaleThreshold = 0.62
 const hierarchyExpansionStartScale = 0.18
-const hierarchyExpansionEndScale = 0.62
+const hierarchyMicroEnterCoverage = 0.72
+const hierarchyMicroExitCoverage = 0.52
+const hierarchyMicroEnterScale = 0.24
+const hierarchyMicroExitScale = 0.16
 const minNodePixelRadius = 2.3
 const viewportPaddingPx = 280
 const worldCoordinateLimit = 5_000_000
@@ -81,6 +84,7 @@ const state = {
   lastHoverHitAt: 0,
   lastManualZoomAt: 0,
   lastZoomFocus: { x: 0, y: 0, at: 0 },
+  hierarchyFocusGroupId: null,
   zoomTransition: {
     active: false,
     source: 'generic',
@@ -1199,12 +1203,9 @@ const focusedGroup = () => {
 
 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 smoothProgress = value => {
+  const bounded = Math.max(0, Math.min(1, value))
+  return bounded * bounded * (3 - 2 * bounded)
 }
 
 const groupRenderRadius = group => {
@@ -1249,6 +1250,60 @@ const hierarchyGroupsForScale = () => {
   return state.leafGroups
 }
 
+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 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 centerCoverage = 1 - Math.min(1, centerDistance / Math.max(viewportRadius, 1))
+
+  return fitCoverage * 0.72 + centerCoverage * 0.28
+}
+
+const groupWithCoverage = (group, viewport) => ({
+  group,
+  coverage: groupViewportCoverage(group, viewport)
+})
+
+const updateHierarchyFocusGroup = (groups, viewport) => {
+  const current = state.hierarchyFocusGroupId ? state.groupById.get(state.hierarchyFocusGroupId) : null
+  const currentCoverage = current ? groupViewportCoverage(current, viewport) : 0
+
+  if (
+    current &&
+    state.transform.scale >= hierarchyMicroExitScale &&
+    currentCoverage >= hierarchyMicroExitCoverage
+  ) {
+    return current
+  }
+
+  const candidate = groups
+    .map(group => groupWithCoverage(group, viewport))
+    .sort((left, right) => right.coverage - left.coverage)[0]
+
+  if (
+    candidate &&
+    state.transform.scale >= hierarchyMicroEnterScale &&
+    candidate.coverage >= hierarchyMicroEnterCoverage
+  ) {
+    state.hierarchyFocusGroupId = candidate.group.id
+    return candidate.group
+  }
+
+  state.hierarchyFocusGroupId = null
+  return null
+}
+
+const hierarchyViewportProgress = (group, viewport) => {
+  const coverage = groupViewportCoverage(group, viewport)
+  const coverageProgress = (coverage - hierarchyMicroExitCoverage) / (hierarchyMicroEnterCoverage - hierarchyMicroExitCoverage)
+  const scaleProgress = (state.transform.scale - hierarchyMicroExitScale) / (hierarchyMicroEnterScale - hierarchyMicroExitScale)
+  return smoothProgress(Math.min(coverageProgress, scaleProgress))
+}
+
 const groupEdgesForRenderedGroups = (groupNodes) => {
   if (groupNodes.length <= 1) {
     return []
@@ -1298,11 +1353,10 @@ const groupEdgesForRenderedGroups = (groupNodes) => {
 
 const computeHierarchyRenderVisibility = (viewport) => {
   if (state.groups.length === 0 || state.visibleNodes.length <= 1000 || state.transform.scale >= hierarchyGroupScaleThreshold) {
+    state.hierarchyFocusGroupId = null
     return false
   }
 
-  const progress = hierarchyExpansionProgress()
-  const focus = focusedGroup()
   const groups = hierarchyGroupsForScale()
     .filter(group =>
       group.x + group.radius >= viewport.minX &&
@@ -1311,9 +1365,11 @@ const computeHierarchyRenderVisibility = (viewport) => {
       group.y - group.radius <= viewport.maxY
     )
     .slice(0, renderNodeBudget)
+  const focus = updateHierarchyFocusGroup(groups, viewport)
+  const progress = focus ? hierarchyViewportProgress(focus, viewport) : 0
   const groupNodes = groups.map(createGroupRenderNode)
 
-  if (progress <= 0.02 || !focus) {
+  if (!focus || progress <= 0.02) {
     state.renderNodes = groupNodes
     state.renderEdges = groupEdgesForRenderedGroups(groupNodes)
     return true
@@ -1327,8 +1383,11 @@ const computeHierarchyRenderVisibility = (viewport) => {
   ).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 isMicroView = progress >= 0.72
+  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,
@@ -2785,6 +2844,7 @@ const selectNode = (node, options = { openContent: false }) => {
       targetScale
     }
     state.lastZoomFocus = { x: node.x, y: node.y, at: performance.now() }
+    state.hierarchyFocusGroupId = node.groupId
     markRenderDirty()
     return
   }
@@ -3089,6 +3149,7 @@ const loadGraph = async (options = { reset: false }) => {
   state.graph = graph
   state.nodes = layout.nodes
   state.groups = layout.groups
+  state.hierarchyFocusGroupId = null
   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 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.
+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, 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.
 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.120",
+  "version": "0.1.0-beta.121",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",