Semantic Graph View (#249)

* feat: Add a new interactive Semantic Galaxy View for visualising vault relationships and integrating Visual RAG.

* feat: Implement graph view auto-refresh on index updates, gracefully handle aborted graph layouts, and refine UI theming and camera centering.

* refactor: reorder object properties for consistency in styling and camera state updates.

* Refactor: enhance graph view stability by removing the visibility observer, adding width checks before refreshing, and improving theme colour resolution.

* feat: refactor graph view to initialise Sigma.js robustly within a dedicated wrapper element and add `edgeType` to graph edges.

* fix: Harden Semantic Galaxy rendering by addressing WebGL 0x0 death in hidden tabs, physics implosions, camera animation crashes, and improving theme color resilience.

* fix: Re-enable Sigma graph interaction events, including hover previews with Sigma v3 payload extraction, and reset view path on open.

* feat: improve graph label styling, add enhanced node hover effects, and implement smart camera behaviour for graph navigation.

* feat: Implement topic-based node colouring, add graph view context menu controls, and enhance subgraph generation with relational clustering.

* feat: implement custom node hover rendering with new interfaces and theme colours

* feat: enhance graph layout with edge weighting and scaling, broaden topic extraction, and improve label visibility by lowering the rendering threshold.

* refactor: simplify semantic graph camera logic to always fit view upon new cluster revelation.

* feat: implement interactive node and edge hovering in the semantic graph view, displaying semantic scores on hovered edges, and store semantic edge scores in the indexer.

* feat: enhance graph label visibility and theme integration, and implement a BM25 keyword search fallback for semantic injection.

* feat: Augment edge label size in the graph view and implement physics weights for structural and semantic edges.

* feat: Add an interactive attraction slider to the graph view for dynamic control over node clustering.

* feat: add graph reshuffle button and attraction slider label, improve physics stability with dynamic repulsion, and refine semantic edge styling.

* refactor: trigger semantic graph updates on slider input events instead of change events.

* feat: add configurable structural and semantic edge thickness and refactor graph view debouncing

* fix: Model selection dropdown in ResearchChatView now dynamically updates when new models are fetched.

* fix: Researcher UI model selection dropdown now dynamically updates to display newly available models.

Author: cybaea

CHANGELOG.md

@@ -9,18 +9,41 @@ New features are added in the "Unreleased" section.
 
 ## [Unreleased]
 
+### Fixed
+
+-   Deep hardening of Semantic Galaxy rendering:
+    -   Fixed WebGL "0x0 death" in background tabs using `allowInvalidContainer` and `IntersectionObserver`.
+    -   Fixed physics engine "implosions" (NaN coordinates) using symmetric coordinate seeding and strict self-loop protection.
+    -   Fixed camera animation crashes by implementing multi-layer NaN guards for WebGL matrices.
+    -   Improved theme color resilience with robust CSS variable resolution and Hex color support.
+    -   Fixed Sigma v3 event payload extraction for native Obsidian hover previews.
+-   **Researcher UI**: Fixed a bug where the model selection dropdown would fail to display newly available models (like Gemini 3.1 Pro) after a fresh API fetch. The dropdown now dynamically updates across all views in real-time.
+
 ### Breaking changes
 
 -   **Minimum Obsidian Version**: The minimum required version of Obsidian has been bumped to **v1.11.4** to support the native `SecretStorage` API. Users on older versions will not be able to install or update to this version.
 -   **API Key Synchronization**: To improve security, your Google Gemini API key is now stored in your device's secure OS keychain (e.g., macOS Keychain, Windows Credential Manager) rather than in plain text. Because of this, **API keys will no longer sync across devices via Obsidian Sync or iCloud**. You will need to manually enter your API key once on each device you use.
 
 ### User features
 
+-   **Semantic Galaxy View**: Replaced the static relationship list with a high-performance, interactive 3D-like graph view. The "Semantic Galaxy" visualises your vault's relationships in real-time, centering on your active note.
+    -   **Visual RAG**: The graph now reacts to the Researcher agent. When the AI mentions files in its response, those notes are automatically highlighted in the galaxy, providing instant spatial context for the agent's reasoning.
+    -   **Structural & Semantic Discovery**: The view blends structural Wikilinks (BFS) with semantic vector similarities, allowing you to discover both explicit and hidden connections in your knowledge base.
+    -   **Fluid Interaction**: Supports smart-panning, node-hover previews (native Obsidian hover), and click-to-navigate functionality.
+    -   **Interactive Layout Controls**: Added a real-time "Attraction" slider to the graph view. Note clustering is driven by mathematical semantic scores; highly-related concepts will physically pull together, and the slider lets you tune this gravity. Includes a "Reshuffle" button to instantly regenerate the layout from scratch if it gets tangled.
+    -   **Adaptive Rendering**: Edge labels dynamically scale and shift coloring to support high contrast modes like Obsidian Dark Mode natively.
+    -   **Physics Stability**: Resolved an issue where high attraction could collapse the graph into a 1D line by dynamically scaling repulsive forces to maintain 2D dispersion.
 -   **Improved Security**: Upgraded the plugin to use Obsidian's native Secure Storage. Your API keys are now encrypted and stored safely in your operating system's keychain rather than sitting in plain text in your vault folder. 
 -   **Linux Compatibility**: Added an intelligent fallback mechanism for Linux users. If your system (e.g., Flatpak or minimal distros) does not have a reachable keychain, the plugin will gracefully fall back to the legacy plain-text storage rather than crashing or nagging you.
 
 ### Developer features
 
+-   **High-performance WebGL Graphing**: Integrated Sigma.js and Graphology into the Obsidian UI. Implemented a Singleton-like Sigma managed instance with `IntersectionObserver` to ensure zero CPU/GPU overhead when the view is not visible.
+-   **Yielding Worker Layout**: Refactored the ForceAtlas2 layout engine to run in the background worker with a yielding strategy (via `setTimeout(0)`), ensuring the main thread stays 100% responsive during complex graph calculations.
+-   **BFS Subgraph Extraction**: Implemented a "Quota-limited BFS" algorithm in the indexer worker to extract local subgraphs (max 250 nodes) centered on active files, ensuring consistent performance regardless of vault size.
+-   **Semantic Injection**: Added logic to inject top-K semantic neighbors into the structural graph, bridging the gap between vector search and graph theory.
+-   **Smart Layout Seeding**: Implemented positional seeding to prevent graph "jumping" during updates by reusing previous node coordinates where available.
+-   **Internal Event Bus**: Leveraged `GraphService` as a centralized, type-safe internal event bus for Visual RAG orchestration, eliminating `any` casts and collisions on `app.workspace`.
 -   **Secure API key storage**: Migrated Google Gemini API keys from plain text `data.json` to Obsidian's native `SecretStorage` API (v1.11.4+).
     -   **JIT initialization**: Refactored `GeminiService` to use asynchronous just-in-time client instantiation, preventing "Async Constructor" race conditions during plugin load.
     -   **Stable secret IDs**: Mandated a persistent secret ID (`vault-intelligence-api-key`) to prevent sync-induced "ping-pong" conflicts between multiple devices.

docs/reference/configuration.md

@@ -39,6 +39,9 @@ Configure how connections and similar notes are discovered.
 | Embedding provider | `gemini` | Google Gemini: Cloud-based. Requires API key. <br>Local: Offline. Runs on your CPU. |
 | Embedding model | `gemini-embedding-001` | The vector engine. Choose from Gemini presets or various local ONNX models. |
 | Minimum similarity score | `0.5` | Relevance threshold (0.0 to 1.0). Matches below this are ignored. |
+| Semantic graph node limit | `250` | Maximum number of nodes to render in the Semantic Galaxy view. Controls the scale of the visualised universe. **How to set:** Keep at `250` for standard performance. Increase to `500+` on powerful desktops for massive overviews, or lower to `100` if the physics simulation stutters on older devices. |
+| Structural edge thickness | `1.0` | Visual weight of explicit wikilinks. Controls how thick the lines representing your actual markdown links are. **How to set:** The default `1.0` balances visibility. Increase to `2.0+` if you want your manual structure to clearly dominate the graph, or reduce to `0.5` to blend them evenly with AI suggestions. |
+| Semantic edge thickness | `0.5` | Visual weight of implied AI relationships. Controls how thick the lines representing vector similarity are. **How to set:** The default `0.5` keeps AI suggestions as a subtle background web. Increase to `1.0+` if you are actively using the galaxy to discover new connections and want them visually prioritised. |
 | Similar notes limit | `20` | Max number of related notes displayed in the sidebar. |
 | Primary context threshold | `0.9` | Similarity threshold for primary (direct match) context notes. |
 | Supporting context threshold | `0.7` | Similarity threshold for supporting (neighbor) context notes. |

package-lock.json

@@ -74,6 +74,8 @@
 		"@xenova/transformers": "2.17.2",
 		"comlink": "^4.4.2",
 		"graphology": "^0.26.0",
+		"graphology-layout-forceatlas2": "^0.10.1",
+		"sigma": "^3.0.2",
 		"zod": "^4.3.5"
 	},
 	"overrides": {

package.json

@@ -272,6 +272,7 @@ export const UI_CONSTANTS = {
 
 export const VIEW_TYPES = {
     RESEARCH_CHAT: "research-chat-view",
+    SEMANTIC_GRAPH: "semantic-graph-view",
     SIMILAR_NOTES: "similar-notes-view"
 };
 
@@ -362,7 +363,8 @@ export const UI_STRINGS = {
     RESEARCHER_SYSTEM_NOTE_PREFIX: "*System Note:* ",
     RESEARCHER_TITLE: "Researcher: chat with vault",
     RIBBON_ICON: "brain-circuit",
-    RIBBON_TOOLTIP: "Vault intelligence"
+    RIBBON_TOOLTIP: "Vault intelligence",
+    SEMANTIC_GRAPH_TITLE: "Semantic Galaxy"
 };
 
 const DOCS_BASE = "https://cybaea.github.io/obsidian-vault-intelligence/";

src/constants.ts

@@ -19,6 +19,7 @@ import { DEFAULT_SETTINGS, VaultIntelligenceSettings, VaultIntelligenceSettingTa
 import { GardenerPlanRenderer } from "./ui/GardenerPlanRenderer";
 import { logger } from "./utils/logger";
 import { ResearchChatView } from "./views/ResearchChatView";
+import { SemanticGraphView } from "./views/SemanticGraphView";
 import { SimilarNotesView } from "./views/SimilarNotesView";
 
 interface InternalSecretStorage {
@@ -216,6 +217,14 @@ export default class VaultIntelligencePlugin extends Plugin implements IVaultInt
 		// Ribbon Icon
 		this.addRibbonIcon(UI_STRINGS.RIBBON_ICON, UI_STRINGS.RIBBON_TOOLTIP, (evt: MouseEvent) => {
 			const menu = new Menu();
+			menu.addItem((item) =>
+				item
+					.setTitle(UI_STRINGS.EXPLORER_TITLE)
+					.setIcon('layout-grid')
+					.onClick(() => {
+						void this.activateView(VIEW_TYPES.SIMILAR_NOTES);
+					})
+			);
 			menu.addItem((item) =>
 				item
 					.setTitle(UI_STRINGS.RESEARCHER_TITLE)
@@ -226,41 +235,62 @@ export default class VaultIntelligencePlugin extends Plugin implements IVaultInt
 			);
 			menu.addItem((item) =>
 				item
-					.setTitle(UI_STRINGS.EXPLORER_TITLE)
-					.setIcon('layout-grid')
+					.setTitle(UI_STRINGS.SEMANTIC_GRAPH_TITLE)
+					.setIcon('network')
 					.onClick(() => {
-						void this.activateView(VIEW_TYPES.SIMILAR_NOTES);
+						void this.activateView(VIEW_TYPES.SEMANTIC_GRAPH);
 					})
 			);
 			menu.showAtMouseEvent(evt);
 		});
 
 		// Register Views
+		this.registerView(
+			VIEW_TYPES.RESEARCH_CHAT,
+			(leaf) => new ResearchChatView(leaf, this, this.geminiService, this.graphService, this.embeddingService)
+		);
+		this.registerView(
+			VIEW_TYPES.SEMANTIC_GRAPH,
+			(leaf) => new SemanticGraphView(leaf, this, this.graphService)
+		);
 		this.registerView(
 			VIEW_TYPES.SIMILAR_NOTES,
 			(leaf) => new SimilarNotesView(leaf, this, this.graphService)
 		);
 
-		this.registerView(
-			VIEW_TYPES.RESEARCH_CHAT,
-			(leaf) => new ResearchChatView(leaf, this, this.geminiService, this.graphService, this.embeddingService)
+		// Event listeners for UI updates
+		this.registerEvent(
+			this.app.workspace.on('active-leaf-change', () => {
+				const leaves = this.app.workspace.getLeavesOfType(VIEW_TYPES.SIMILAR_NOTES);
+				leaves.forEach(leaf => {
+					if (leaf.view instanceof SimilarNotesView) {
+						void leaf.view.updateView();
+					}
+				});
+
+				// FIX: Hook up the Semantic Graph to active-leaf-change
+				const graphLeaves = this.app.workspace.getLeavesOfType(VIEW_TYPES.SEMANTIC_GRAPH);
+				graphLeaves.forEach(leaf => {
+					if (leaf.view instanceof SemanticGraphView) {
+						const file = this.app.workspace.getActiveFile();
+						void leaf.view.updateForFile(file);
+					}
+				});
+			})
 		);
 
 		// Commands
 		this.addCommand({
-			callback: () => {
-				void this.activateView(VIEW_TYPES.SIMILAR_NOTES);
-			},
-			id: 'open-similar-notes-view',
-			name: 'Explorer: view similar notes'
-		});
-
-		this.addCommand({
-			callback: () => {
-				void this.activateView(VIEW_TYPES.RESEARCH_CHAT);
+			callback: async () => {
+				try {
+					await this.gardenerService.purgeOldPlans();
+					new Notice(UI_STRINGS.NOTICE_GARDENER_PURGED);
+				} catch (error: unknown) {
+					new Notice(`${UI_STRINGS.NOTICE_PURGE_FAILED}${error instanceof Error ? error.message : String(error)}`);
+				}
 			},
-			id: 'open-research-chat-view',
-			name: 'Researcher: chat with vault'
+			id: 'gardener-purge-plans',
+			name: UI_STRINGS.GARDENER_TITLE_PURGE
 		});
 
 		this.addCommand({
@@ -281,16 +311,27 @@ export default class VaultIntelligencePlugin extends Plugin implements IVaultInt
 		});
 
 		this.addCommand({
-			callback: async () => {
-				try {
-					await this.gardenerService.purgeOldPlans();
-					new Notice(UI_STRINGS.NOTICE_GARDENER_PURGED);
-				} catch (error: unknown) {
-					new Notice(`${UI_STRINGS.NOTICE_PURGE_FAILED}${error instanceof Error ? error.message : String(error)}`);
-				}
+			callback: () => {
+				void this.activateView(VIEW_TYPES.RESEARCH_CHAT);
 			},
-			id: 'gardener-purge-plans',
-			name: UI_STRINGS.GARDENER_TITLE_PURGE
+			id: 'open-research-chat-view',
+			name: 'Researcher: chat with vault'
+		});
+
+		this.addCommand({
+			callback: () => {
+				void this.activateView(VIEW_TYPES.SEMANTIC_GRAPH);
+			},
+			id: 'open-semantic-graph-view',
+			name: 'Explorer: view semantic galaxy'
+		});
+
+		this.addCommand({
+			callback: () => {
+				void this.activateView(VIEW_TYPES.SIMILAR_NOTES);
+			},
+			id: 'open-similar-notes-view',
+			name: 'Explorer: view similar notes'
 		});
 
 		this.addCommand({
@@ -333,6 +374,15 @@ export default class VaultIntelligencePlugin extends Plugin implements IVaultInt
 						void leaf.view.updateView();
 					}
 				});
+
+				// Notify Semantic Galaxy to update on file change
+				const graphLeaves = this.app.workspace.getLeavesOfType(VIEW_TYPES.SEMANTIC_GRAPH);
+				graphLeaves.forEach(leaf => {
+					if (leaf.view instanceof SemanticGraphView) {
+						const file = this.app.workspace.getActiveFile();
+						void leaf.view.updateForFile(file);
+					}
+				});
 			})
 		);
 

src/main.ts

@@ -1,3 +1,4 @@
+import Graph from "graphology";
 import { Events, App } from "obsidian";
 
 import { GRAPH_CONSTANTS } from "../constants";
@@ -173,6 +174,26 @@ export class GraphService extends Events {
         }
     }
 
+    /**
+     * Gets a subgraph centered around a file with pre-calculated layout.
+     */
+    public async getSemanticSubgraph(path: string, updateId: number, existingPositions?: Record<string, { x: number, y: number }>, attractionMultiplier: number = 1.0): Promise<Graph | null> {
+        try {
+            const raw = await this.workerManager.executeQuery(api => api.getSubgraph(path, updateId, existingPositions, attractionMultiplier));
+
+            // FIX: Gracefully handle null from aborted layout
+            if (!raw) return null;
+
+            const sub = new Graph({ type: 'undirected' });
+            sub.import(raw as Parameters<typeof sub.import>[0]);
+
+            return sub;
+        } catch (e) {
+            console.error(`[GraphService] Failed to get semantic subgraph for ${path}`, e);
+            return null;
+        }
+    }
+
     /**
      * Gets structural importance metrics for a node.
      */

src/services/GraphService.ts

@@ -97,7 +97,10 @@ export class GraphSyncOrchestrator {
             indexingDelayMs: this.settings.indexingDelayMs || GRAPH_CONSTANTS.DEFAULT_INDEXING_DELAY_MS,
             minSimilarityScore: this.settings.minSimilarityScore ?? 0.5,
             ontologyPath: this.settings.ontologyPath,
-            sanitizedModelId: this.persistenceManager.getSanitizedModelId(activeModelId, activeDimension)
+            sanitizedModelId: this.persistenceManager.getSanitizedModelId(activeModelId, activeDimension),
+            semanticEdgeThickness: this.settings.semanticEdgeThickness || 0.5,
+            semanticGraphNodeLimit: this.settings.semanticGraphNodeLimit || 250,
+            structuralEdgeThickness: this.settings.structuralEdgeThickness || 1.0
         };
     }
 
@@ -372,6 +375,9 @@ export class GraphSyncOrchestrator {
                 indexingDelayMs: settings.indexingDelayMs,
                 minSimilarityScore: settings.minSimilarityScore,
                 ontologyPath: settings.ontologyPath,
+                semanticEdgeThickness: settings.semanticEdgeThickness,
+                semanticGraphNodeLimit: settings.semanticGraphNodeLimit,
+                structuralEdgeThickness: settings.structuralEdgeThickness
             });
         }
     }

src/services/GraphSyncOrchestrator.ts

@@ -207,6 +207,7 @@ export class ModelRegistry {
                 };
                 (app as unknown as InternalApp).saveLocalStorage?.(this.CACHE_KEY, JSON.stringify(cacheData));
             }
+            app.workspace.trigger('vault-intelligence:models-updated');
         } catch (error) {
             logger.error("Error fetching Gemini models", error);
             if (throwOnError) throw error;