@andespindola/brainlink 0.1.0-beta.33 → 0.1.0-beta.35

package/CHANGELOG.md

@@ -24,6 +24,9 @@
 - Added `docs/QUICKSTART.md` and aligned README/agent docs with the latest CLI/MCP flows.
 - Added middle-out context assembly so chunk selection expands around the strongest note chunk.
 - Added compressed-space pack prefiltering (token bloom index) before `.blpk` decryption and scan.
+- Improved graph UI auto-fit and viewport recovery so loaded nodes are re-centered when zoom/pan drifts to empty canvas.
+- Added cross-platform native desktop GUI auto-open for `blink server` (macOS Swift/WebKit, Windows PowerShell WinForms, Linux Python GTK/WebKit2), with app-window/browser fallback.
+- Changed Linux default UI launch to app-window/browser for lighter startup; Linux native GUI is now opt-in via `BRAINLINK_LINUX_NATIVE_GUI=1`.
 
 ## 0.1.0-beta.3
 

package/README.md

@@ -553,8 +553,14 @@ blink server --host 127.0.0.1 --port 4321 --watch
 ```
 
 By default, the server uses `$HOME/.brainlink/vault`. Pass `--vault ./vault` only when you want to inspect a custom vault.
-By default, `blink server` tries to open the graph in a dedicated app window (`--app=<url>` on compatible browsers).  
-If app-window launch is unavailable, it falls back to the default browser. Use `--no-open` to keep it headless.
+By default, `blink server` tries to open the graph in a native desktop GUI window:
+- macOS: Swift + WebKit
+- Windows: PowerShell WinForms WebBrowser
+- Linux: optional Python GTK + WebKit2 (requires `python3` + `gi` + `WebKit2`)
+
+On Linux, native GUI is disabled by default for better startup performance. Enable it with `BRAINLINK_LINUX_NATIVE_GUI=1`.
+If native GUI launch is unavailable on your system, it falls back to dedicated app-window mode and then to the default browser.
+Use `--no-open` to keep it headless.
 
 The graph UI shows:
 
@@ -844,7 +850,9 @@ blink server --vault ./vault --watch --no-open
 ```
 
 Starts the local read-only graph UI and HTTP API.
-By default, it tries to open a dedicated app window for the graph URL and falls back to browser open when app-window mode is unavailable.
+By default, it tries to open a native desktop GUI window for the graph URL.
+On Linux, native GUI is disabled by default; enable it with `BRAINLINK_LINUX_NATIVE_GUI=1`.
+If native GUI launch is unavailable, it falls back to dedicated app-window mode and then browser open.
 Use `--no-open` to skip that behavior.
 
 The HTTP server only binds to loopback hosts such as `127.0.0.1`, `localhost` or `::1`.

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

@@ -245,8 +245,8 @@ li small {
 }
 
 .content-dialog {
-  width: min(920px, calc(100vw - 32px));
-  max-height: calc(100svh - 32px);
+  width: min(1240px, calc(100vw - 24px));
+  max-height: calc(100svh - 20px);
   padding: 0;
   border: 1px solid var(--line);
   border-radius: 8px;
@@ -263,7 +263,7 @@ li small {
 .content-dialog article {
   display: grid;
   grid-template-rows: auto auto minmax(0, 1fr);
-  max-height: calc(100svh - 34px);
+  max-height: calc(100svh - 22px);
 }
 
 .content-dialog header {
@@ -339,7 +339,7 @@ li small {
 
 .content-meta-section ul,
 .content-meta-section .tags {
-  max-height: 140px;
+  max-height: 220px;
   overflow: auto;
   align-content: flex-start;
   padding-right: 4px;

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

@@ -5,6 +5,8 @@ const largeGraphEdgeRenderLimit = 16000
 const renderNodeBudget = 1800
 const minNodePixelRadius = 1.8
 const viewportPaddingPx = 280
+const worldCoordinateLimit = 5_000_000
+const transformCoordinateLimit = 20_000_000
 const state = {
   graph: { nodes: [], edges: [] },
   nodes: [],
@@ -26,7 +28,9 @@ const state = {
   cursor: { x: 0, y: 0, inCanvas: false },
   graphSignature: '',
   graphStatus: '',
-  last: performance.now()
+  last: performance.now(),
+  offscreenFrameCount: 0,
+  recoveringViewport: false
 }
 
 const byId = id => document.getElementById(id)
@@ -130,6 +134,8 @@ const recomputeVisibility = () => {
 const edgeWeight = edge => Number.isFinite(edge.weight) ? Math.max(1, edge.weight) : 1
 
 const clampScale = value => Math.max(zoomRange.min, Math.min(zoomRange.max, value))
+const isFiniteNumber = value => Number.isFinite(value)
+const isReasonableCoordinate = value => isFiniteNumber(value) && Math.abs(value) <= worldCoordinateLimit
 
 const graphBounds = nodes => {
   if (nodes.length === 0) return null
@@ -157,14 +163,25 @@ const graphBounds = nodes => {
 }
 
 const fitScaleBiasByNodeCount = nodeCount => {
-  if (nodeCount <= 6) return 2.8
-  if (nodeCount <= 20) return 2.2
-  if (nodeCount <= 60) return 1.72
-  if (nodeCount <= 180) return 1.34
-  if (nodeCount <= 600) return 1.08
-  if (nodeCount <= 2000) return 0.9
-  if (nodeCount <= 6000) return 0.72
-  return 0.58
+  if (nodeCount <= 6) return 1.22
+  if (nodeCount <= 20) return 1.12
+  if (nodeCount <= 60) return 1.04
+  if (nodeCount <= 180) return 1
+  if (nodeCount <= 600) return 0.94
+  if (nodeCount <= 2000) return 0.82
+  if (nodeCount <= 6000) return 0.68
+  return 0.56
+}
+
+const autoFitScaleRangeByNodeCount = nodeCount => {
+  if (nodeCount <= 6) return { min: 0.4, max: 2.2 }
+  if (nodeCount <= 20) return { min: 0.34, max: 1.65 }
+  if (nodeCount <= 60) return { min: 0.25, max: 1.22 }
+  if (nodeCount <= 180) return { min: 0.18, max: 0.92 }
+  if (nodeCount <= 600) return { min: 0.12, max: 0.72 }
+  if (nodeCount <= 2000) return { min: 0.08, max: 0.52 }
+  if (nodeCount <= 6000) return { min: 0.06, max: 0.32 }
+  return { min: zoomRange.min, max: 0.24 }
 }
 
 const fitView = (options = { useFiltered: true }) => {
@@ -188,25 +205,13 @@ const fitView = (options = { useFiltered: true }) => {
     if (nodeCount <= 2000) return 140
     return 180
   }
-  const minFitScaleByNodeCount = nodeCount => {
-    if (nodeCount <= 6) return 2.4
-    if (nodeCount <= 20) return 1.8
-    if (nodeCount <= 60) return 1.2
-    if (nodeCount <= 180) return 0.86
-    if (nodeCount <= 600) return 0.58
-    if (nodeCount <= 2000) return 0.34
-    if (nodeCount <= 6000) return 0.2
-    return 0.13
-  }
-
   const padding = paddingByNodeCount(nodes.length)
   const scaleX = width / (bounds.width + padding * 2)
   const scaleY = height / (bounds.height + padding * 2)
-  const fitScale = clampScale(Math.min(scaleX, scaleY))
+  const fitScale = Math.min(scaleX, scaleY)
   const biasedScale = clampScale(fitScale * fitScaleBiasByNodeCount(nodes.length))
-  const minimumScale = minFitScaleByNodeCount(nodes.length)
-  const minimumLargeGraphScale = nodes.length > largeGraphNodeThreshold ? 0.13 : zoomRange.min
-  const scale = Math.max(biasedScale, minimumScale, minimumLargeGraphScale)
+  const scaleRange = autoFitScaleRangeByNodeCount(nodes.length)
+  const scale = clampScale(Math.min(scaleRange.max, Math.max(scaleRange.min, biasedScale)))
   const centerX = (bounds.minX + bounds.maxX) / 2
   const centerY = (bounds.minY + bounds.maxY) / 2
 
@@ -328,8 +333,8 @@ const tick = delta => {
     const dy = target.y - source.y
     const distance = Math.max(Math.hypot(dx, dy), 1)
     const force = (distance - 150) * 0.002 * strength
-    const fx = dx * force
-    const fy = dy * force
+    const fx = (dx / distance) * force
+    const fy = (dy / distance) * force
     source.vx += fx
     source.vy += fy
     target.vx -= fx
@@ -502,6 +507,40 @@ const computeRenderVisibility = () => {
   state.renderEdges = edges
 }
 
+const isNodeVisibleOnScreen = (node, width, height) => {
+  const radius = nodeRadius(node) * state.transform.scale
+  const screenX = node.x * state.transform.scale + state.transform.x
+  const screenY = node.y * state.transform.scale + state.transform.y
+
+  return (
+    screenX + radius >= 0 &&
+    screenX - radius <= width &&
+    screenY + radius >= 0 &&
+    screenY - radius <= height
+  )
+}
+
+const hasValidTransform = () =>
+  isFiniteNumber(state.transform.x) &&
+  isFiniteNumber(state.transform.y) &&
+  isFiniteNumber(state.transform.scale) &&
+  Math.abs(state.transform.x) <= transformCoordinateLimit &&
+  Math.abs(state.transform.y) <= transformCoordinateLimit &&
+  state.transform.scale > 0
+
+const sanitizeNodePosition = node => {
+  if (!isReasonableCoordinate(node.x)) node.x = 0
+  if (!isReasonableCoordinate(node.y)) node.y = 0
+  if (!isFiniteNumber(node.vx) || Math.abs(node.vx) > worldCoordinateLimit) node.vx = 0
+  if (!isFiniteNumber(node.vy) || Math.abs(node.vy) > worldCoordinateLimit) node.vy = 0
+}
+
+const sanitizeGraphState = () => {
+  state.nodes.forEach(sanitizeNodePosition)
+  state.visibleNodes.forEach(sanitizeNodePosition)
+  state.renderNodes.forEach(sanitizeNodePosition)
+}
+
 const render = now => {
   const delta = now - state.last
   state.last = now
@@ -513,6 +552,10 @@ const render = now => {
   const rect = canvas.getBoundingClientRect()
   const width = Math.max(rect.width, 320)
   const height = Math.max(rect.height, 320)
+  sanitizeGraphState()
+  if (!hasValidTransform()) {
+    resetView()
+  }
   ctx.clearRect(0, 0, width, height)
   if (state.nodes.length === 0) {
     ctx.fillStyle = '#99a5b5'
@@ -528,6 +571,20 @@ const render = now => {
 
   computeRenderVisibility()
   tick(delta)
+  const hasVisibleNodeOnScreen = state.renderNodes.some((node) => isNodeVisibleOnScreen(node, width, height))
+  if (!hasVisibleNodeOnScreen && state.renderNodes.length > 0) {
+    state.offscreenFrameCount += 1
+    if (state.offscreenFrameCount >= 6 && !state.recoveringViewport) {
+      state.recoveringViewport = true
+      fitView({ useFiltered: true })
+      state.offscreenFrameCount = 0
+      requestAnimationFrame(() => {
+        state.recoveringViewport = false
+      })
+    }
+  } else {
+    state.offscreenFrameCount = 0
+  }
   const drawEdges = !(state.nodes.length > largeGraphNodeThreshold && state.transform.scale < 0.22)
   if (drawEdges) {
     state.renderEdges.forEach(edge => {
@@ -695,6 +752,10 @@ const isScreenPointInsideCanvas = (screenX, screenY) => {
 }
 
 const handleWheelZoom = event => {
+  if (elements.contentDialog?.open) {
+    return
+  }
+
   if (!isScreenPointInsideCanvas(event.clientX, event.clientY)) {
     return
   }

package/dist/cli/commands/write-commands.js

@@ -1,9 +1,8 @@
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { mkdir, writeFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { dirname, relative, resolve } from 'node:path';
-import { platform } from 'node:os';
-import { spawn } from 'node:child_process';
+import { dirname, join, relative, resolve } from 'node:path';
+import { platform, tmpdir } from 'node:os';
+import { spawn, spawnSync } from 'node:child_process';
 import { addNote } from '../../application/add-note.js';
 import { buildContextPackage } from '../../application/build-context.js';
 import { importLegacySqliteDatabase } from '../../application/import-legacy-sqlite.js';
@@ -37,6 +36,200 @@ const spawnDetached = (command, args) => {
         return false;
     }
 };
+const nativeGuiSwiftScriptPath = join(tmpdir(), 'brainlink-native-gui.swift');
+const nativeGuiPowershellScriptPath = join(tmpdir(), 'brainlink-native-gui.ps1');
+const nativeGuiLinuxScriptPath = join(tmpdir(), 'brainlink-native-gui-linux.py');
+const nativeGuiSwiftScript = `import Foundation
+import AppKit
+import WebKit
+
+final class BrainlinkAppDelegate: NSObject, NSApplicationDelegate, NSWindowDelegate {
+  private let targetUrl: URL
+  private var window: NSWindow?
+  private var webView: WKWebView?
+
+  init(targetUrl: URL) {
+    self.targetUrl = targetUrl
+  }
+
+  func applicationDidFinishLaunching(_ notification: Notification) {
+    let window = NSWindow(
+      contentRect: NSRect(x: 0, y: 0, width: 1320, height: 860),
+      styleMask: [.titled, .closable, .miniaturizable, .resizable],
+      backing: .buffered,
+      defer: false
+    )
+    window.title = "Brainlink Graph"
+    window.center()
+    window.isReleasedWhenClosed = false
+    window.delegate = self
+
+    let webView = WKWebView(frame: window.contentView?.bounds ?? .zero)
+    webView.autoresizingMask = [.width, .height]
+    webView.allowsBackForwardNavigationGestures = true
+    webView.load(URLRequest(url: targetUrl))
+    window.contentView?.addSubview(webView)
+
+    self.window = window
+    self.webView = webView
+
+    window.makeKeyAndOrderFront(nil)
+    NSApp.activate(ignoringOtherApps: true)
+  }
+
+  func windowWillClose(_ notification: Notification) {
+    NSApp.terminate(nil)
+  }
+}
+
+let rawTarget = CommandLine.arguments.dropFirst().first ?? "http://127.0.0.1:4321"
+
+guard let targetUrl = URL(string: rawTarget) else {
+  fputs("Invalid URL for Brainlink GUI: \\(rawTarget)\\n", stderr)
+  exit(1)
+}
+
+let app = NSApplication.shared
+app.setActivationPolicy(.regular)
+let delegate = BrainlinkAppDelegate(targetUrl: targetUrl)
+app.delegate = delegate
+app.run()
+`;
+const nativeGuiPowershellScript = `param(
+  [string]$TargetUrl = "http://127.0.0.1:4321"
+)
+
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+[System.Windows.Forms.Application]::EnableVisualStyles()
+
+$form = New-Object System.Windows.Forms.Form
+$form.Text = "Brainlink Graph"
+$form.Width = 1320
+$form.Height = 860
+$form.StartPosition = "CenterScreen"
+
+$browser = New-Object System.Windows.Forms.WebBrowser
+$browser.Dock = [System.Windows.Forms.DockStyle]::Fill
+$browser.ScriptErrorsSuppressed = $true
+$browser.Navigate($TargetUrl)
+
+$form.Controls.Add($browser)
+[void]$form.ShowDialog()
+`;
+const nativeGuiLinuxPythonScript = `#!/usr/bin/env python3
+import sys
+
+def run() -> int:
+    try:
+        import gi
+        gi.require_version("Gtk", "3.0")
+        try:
+            gi.require_version("WebKit2", "4.1")
+        except ValueError:
+            gi.require_version("WebKit2", "4.0")
+        from gi.repository import Gtk, WebKit2
+    except Exception:
+        return 1
+
+    target_url = sys.argv[1] if len(sys.argv) > 1 else "http://127.0.0.1:4321"
+
+    window = Gtk.Window(title="Brainlink Graph")
+    window.set_default_size(1320, 860)
+    window.connect("destroy", Gtk.main_quit)
+
+    webview = WebKit2.WebView()
+    webview.load_uri(target_url)
+    window.add(webview)
+    window.show_all()
+    Gtk.main()
+    return 0
+
+if __name__ == "__main__":
+    raise SystemExit(run())
+`;
+const commandExists = (command) => {
+    try {
+        const probe = platform() === 'win32'
+            ? spawnSync('where', [command], { stdio: 'ignore' })
+            : spawnSync('which', [command], { stdio: 'ignore' });
+        return probe.status === 0;
+    }
+    catch {
+        return false;
+    }
+};
+const envFlagEnabled = (name) => process.env[name] === '1' || process.env[name] === 'true';
+const resolveSwiftExecutable = () => {
+    const directSwift = '/usr/bin/swift';
+    if (existsSync(directSwift)) {
+        return directSwift;
+    }
+    try {
+        const probe = spawnSync('xcrun', ['--find', 'swift'], { encoding: 'utf8' });
+        const swiftPath = probe.status === 0 ? probe.stdout.trim() : '';
+        return swiftPath.length > 0 ? swiftPath : null;
+    }
+    catch {
+        return null;
+    }
+};
+const openGraphInMacNativeGui = (url) => {
+    const swiftBinary = resolveSwiftExecutable();
+    if (!swiftBinary) {
+        return false;
+    }
+    try {
+        writeFileSync(nativeGuiSwiftScriptPath, nativeGuiSwiftScript, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    return spawnDetached(swiftBinary, [nativeGuiSwiftScriptPath, url]);
+};
+const resolveWindowsPowershellExecutable = () => {
+    if (commandExists('powershell')) {
+        return 'powershell';
+    }
+    if (commandExists('pwsh')) {
+        return 'pwsh';
+    }
+    return null;
+};
+const openGraphInWindowsNativeGui = (url) => {
+    const powershell = resolveWindowsPowershellExecutable();
+    if (!powershell) {
+        return false;
+    }
+    try {
+        writeFileSync(nativeGuiPowershellScriptPath, nativeGuiPowershellScript, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    return spawnDetached(powershell, ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-STA', '-File', nativeGuiPowershellScriptPath, url]);
+};
+const openGraphInLinuxNativeGui = (url) => {
+    if (!commandExists('python3')) {
+        return false;
+    }
+    try {
+        writeFileSync(nativeGuiLinuxScriptPath, nativeGuiLinuxPythonScript, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    return spawnDetached('python3', [nativeGuiLinuxScriptPath, url]);
+};
+const openGraphInNativeGui = (url) => {
+    if (platform() === 'darwin') {
+        return openGraphInMacNativeGui(url);
+    }
+    if (platform() === 'win32') {
+        return openGraphInWindowsNativeGui(url);
+    }
+    return openGraphInLinuxNativeGui(url);
+};
 const openGraphInAppWindow = (url) => {
     if (platform() === 'darwin') {
         const macCandidates = [
@@ -66,13 +259,19 @@ const openGraphInAppWindow = (url) => {
         spawnDetached('microsoft-edge', [appArgument, '--new-window']) ||
         spawnDetached('microsoft-edge-stable', [appArgument, '--new-window']));
 };
-const openUrlInBrowser = (url) => {
+const openUrlInUi = (url) => {
     const openDisabled = process.env.BRAINLINK_NO_BROWSER === '1' ||
         process.env.BRAINLINK_NO_BROWSER === 'true' ||
         process.env.CI === 'true';
     if (openDisabled) {
         return { opened: false, mode: 'none' };
     }
+    const currentPlatform = platform();
+    const nativeGuiEnabled = !envFlagEnabled('BRAINLINK_NO_NATIVE_GUI') &&
+        (currentPlatform !== 'linux' || envFlagEnabled('BRAINLINK_LINUX_NATIVE_GUI') || envFlagEnabled('BRAINLINK_FORCE_NATIVE_GUI'));
+    if (nativeGuiEnabled && openGraphInNativeGui(url)) {
+        return { opened: true, mode: 'native-gui' };
+    }
     if (openGraphInAppWindow(url)) {
         return { opened: true, mode: 'app-window' };
     }
@@ -278,7 +477,7 @@ export const registerWriteCommands = (program) => {
         .option('-h, --host <host>', 'server host', '127.0.0.1')
         .option('-p, --port <port>', 'server port', '4321')
         .option('--no-index', 'skip indexing before starting the server')
-        .option('--no-open', 'do not open the graph UI in the default browser')
+        .option('--no-open', 'do not open the graph UI automatically')
         .option('-w, --watch', 'watch markdown files and reindex on changes')
         .option('--json', 'print machine-readable JSON')
         .description('start a local web UI for the knowledge graph')
@@ -291,7 +490,7 @@ export const registerWriteCommands = (program) => {
             shouldIndex: options.index,
             shouldWatch: Boolean(options.watch)
         });
-        const openResult = options.open !== false ? openUrlInBrowser(server.url) : { opened: false, mode: 'none' };
+        const openResult = options.open !== false ? openUrlInUi(server.url) : { opened: false, mode: 'none' };
         print(options.json, {
             url: server.url,
             watch: Boolean(options.watch),
@@ -299,9 +498,11 @@ export const registerWriteCommands = (program) => {
             openedUi: openResult.opened,
             openMode: openResult.mode
         }, () => `Brainlink graph server running at ${server.url}${openResult.opened
-            ? openResult.mode === 'app-window'
-                ? ' (opened in dedicated app window)'
-                : ' (opened in browser)'
+            ? openResult.mode === 'native-gui'
+                ? ' (opened in native desktop GUI)'
+                : openResult.mode === 'app-window'
+                    ? ' (opened in dedicated app window)'
+                    : ' (opened in browser)'
             : options.open === false
                 ? ' (auto-open disabled)'
                 : ''}`);

package/docs/AGENT_USAGE.md

@@ -540,7 +540,13 @@ blink server --vault ./vault --host 127.0.0.1 --port 4321 --no-open
 ```
 
 This starts a local frontend for inspecting the knowledge graph.
-By default it tries to open the graph in a dedicated app window and falls back to the default browser when app-window mode is unavailable.
+By default it tries to open the graph in a native desktop GUI window:
+- macOS: Swift + WebKit
+- Windows: PowerShell WinForms WebBrowser
+- Linux: optional Python GTK + WebKit2 (requires `python3` + `gi` + `WebKit2`)
+
+On Linux, native GUI is disabled by default for better startup performance. Enable it with `BRAINLINK_LINUX_NATIVE_GUI=1`.
+If native GUI launch is unavailable, it falls back to dedicated app-window mode and then to the default browser.
 Use `--no-open` to keep the server headless.
 
 Without `--vault`, the graph UI serves `$HOME/.brainlink/vault`.

package/package.json

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