2026-01-24 v1.3.0

NoteConnection Knowledge Graph

NoteConnection: Hierarchical Knowledge Graph Visualization System

> Unlock the Structure of Your Knowledge.


NoteConnection is a high-performance, standalone visualization system engineered to transform unstructured Markdown knowledge bases into Directed Acyclic Graphs (DAGs).

Unlike traditional "network" views that show a messy web of links, NoteConnection reveals the hierarchy, learning paths, and dependency structures hidden within your notes. It is built for scalability, capable of handling tens of thousands of nodes with ease, and operates completely independently of any specific note-taking app.

---

🚀 Key Features

$3

- Structure Over Chaos: Switch between Force-Directed (Physics) and DAG (Hierarchical) layouts. The DAG layout automatically identifies "Prerequisites" and "Next Steps" to arrange concepts in logical layers.
- Dual Rendering Engine (v0.8.7): Seamlessly toggle between SVG (for interactivity) and Canvas (for high-performance rendering of 10,000+ nodes).
- Interactive Focus Mode: Click any node to isolate it and its context. Features Freeze on Select (v0.8.9) to prevent drift, adjustable Vertical/Horizontal Spacing (v0.8.8), and absolute visual consistency upon exit. Use the Random Focus (dice icon) to discover new connections (v1.0.0).
- Absolute Offline Support (v1.0.0): All library dependencies (D3, KaTeX, Marked, Mermaid, JSZip) are migrated to local assets, ensuring 100% functionality without internet.

$3

- Hybrid Inference Engine: Combines Statistical Probability ($P(A|B)$) and Vector Similarity (TF-IDF) to infer hidden dependencies (e.g., "Fluorescence" implies "Photon") without external AI APIs.
- Scalable Clustering: Aggregates thousands of nodes into high-level "Concept Bubbles" based on folder structure or tags for a cleaner overview.

$3

- Curriculum Generation: Instantly transforms your graph into linear learning paths.
- Domain Learning: Master an entire concept cluster (Topological Sort).
- Diffusion Learning: Find the most efficient path to a specific goal (Shortest Path + Prerequisites).
- Hybrid Architecture: Connects to a high-fidelity Godot 4.3 Desktop Renderer via WebSocket (ws://localhost:9876) for AAA-quality visualization, while maintaining full web compatibility.
- Smart Strategies: Choose "Foundational" (Base-first) or "Core" (Importance-first) sorting to suit your learning style.

$3

- High-Capacity Parallel Processing: Utilizes Node.js worker_threads (up to 12 cores) to distribute computationally intensive keyword matching.
- Simulation Controls (v0.9.0): Fine-tune the physics with a Speed/Damping Slider or use the Freeze Layout switch to stop the simulation for stable manual arrangement.
- Hover Lock: Hovering over a node temporarily locks its position, allowing for stable inspection of connections.

---

💻 Hardware & Driver Requirements

$3

NoteConnection utilizes gpu.js for WebGL-based acceleration and plans to support local AI inference via ROCm.

- RDNA 3 (Recommended): Radeon RX 7000 Series (e.g., RX 7900 XT/XTX).
- _Status_: Best performance for both WebGL and Compute.
- RDNA 2: Radeon RX 6000 Series.
- _Status_: Stable and mature support.

$3

#### Windows (Development Environment)

- Driver: AMD Software: Adrenalin Edition (23.12.1+).
- Required for DirectX 12/Vulkan/OpenGL support which underpins WebGL.
- Build Tools: To compile headless-gl for Node.js:
- Python 3.x installed and in PATH.
- Visual Studio Build Tools (C++ workload).

#### Linux (Recommended for AI)

- Mesa (RADV/Radeonsi): Default open-source driver. Best for general WebGL and gpu.js.
- ROCm (Radeon Open Compute): Install only if planning to develop the AI inference features (future roadmap). NoteConnection's core visualization runs fine on standard Mesa drivers.

---

🏢 System Architecture

NoteConnection is built on a modular architecture designed for performance and extensibility.

$3

- GraphBuilder: The core orchestrator. It manages the pipeline from file reading to graph construction.
- Worker Threads: Heavy lifting (keyword matching, text analysis) is offloaded to a pool of worker threads (src/backend/workers), ensuring the main thread remains responsive.
- Inference Engines:
- StatisticalAnalyzer: Calculates co-occurrence matrices.
- VectorSpace: Handles TF-IDF embedding and cosine similarity.
- HybridEngine: Combines signals to suggest directed edges.

$3

- Dual-Engine Renderer:
- D3.js (SVG): Used for high-fidelity, interactive graphs with detailed tooltips and CSS styling.
- HTML5 Canvas: Optimized for rendering massive datasets where DOM manipulation overhead is too high.
- State Management: SettingsManager persists user preferences (Physics, Visuals) to localStorage.
- Layout Logic: Custom algorithms for Sugiyama-style layering and Force-directed physics.

$3

- PathBridge: standard WebSocket server (Port 9876) that exposes the internal graph state to external applications (e.g., Godot Engine), enabling hybrid web/native visualization pipelines.

---

📦 Quick Start

$3

1. Download NoteConnection.Setup.exe from the Latest Releases.
2. Run the installer.
3. Launch NoteConnection from your desktop or start menu.

$3

No installation required.

``bash
npx noteconnection
`

$3

`bash
npm install -g noteconnection
noteconnection
`

$3

`bash
git clone https://github.com/Jacobinwwey/NoteConnection.git
cd NoteConnection
npm install
npm start
`

- Server runs at: http://localhost:3000

$3

NoteConnection uses Capacitor to build native mobile apps.

#### Prerequisites

- Node.js (LTS)
- Java JDK (17 or higher)
- Android SDK (Configured in ANDROID_HOME or via Android Studio)

#### Method A: One-Click Build (Recommended)

Simply run the included batch script on Windows:

`cmd
build_apk.bat
`

This script automatically:

1. Checks your environment (Node, Java, Android SDK).
2. Installs dependencies.
3. Builds web assets.
4. Syncs with Capacitor.
5. Compiles the APK using Gradle.

#### Method B: Manual Build Steps

1. Build Web Assets:
`bash
npm run build
`
2. Sync to Android Platform:
`bash
npx cap sync
`
3. Build APK:
Open the android directory in Android Studio and build, or use the command line:
`bash
cd android
./gradlew assembleDebug
`
APK will be located at: android/app/build/outputs/apk/debug/app-debug.apk

$3

1. Select Source: Use the dropdown in the top-left to choose a folder from Knowledge_Base.
2. Load: Click "Load". For large datasets (>200 files), parallel processing engages automatically.
3. Explore:
- Layout: Toggle DAG for hierarchy or Force for clusters.
- Renderer: Switch to Canvas if the graph feels sluggish.
- Focus: Click a node to enter Focus Mode. Use the sliders to adjust spacing.
- Control: Use the Simulation panel to freeze the layout or adjust speed.

🖥️ CLI Usage (v0.9.71)

You can load a knowledge base and build the graph directly from the command line without using the UI. This is useful for automated builds or headless environments.

$3

`bash
npm start -- --path "" [options]
`

$3

| Option | Description | Default |
| ----------- | -------------------------------------------------------------------- | ------------------------------ |
| --path | Absolute path to the folder containing your Markdown files. | Knowledge_Base |
| --gpu | Enable AMDGPU/WebGL acceleration for layout and vector calculations. | true (if hardware supported) |
| --no-gpu | Disable GPU acceleration (Force CPU). | false |
| --static | Enable Static Mode (Backend calculation only, frozen frontend). | false |
| --workers | Number of worker threads to use. | numCPUs - 1 |

$3

`bash


Basic Load

npm start -- --path "C:/Users/MyName/Documents/MyNotes"

GPU Accelerated Build

npm start -- --path "E:/Knowledge/ObsidianVault" --gpu

Force CPU (if GPU has issues)

npm start -- --path "E:/Knowledge/ObsidianVault" --no-gpu
`

Note: CLI runs generate unique data files (data_cli_{kb_name}_{time}.js) to preserve the original data.js. When the server starts, it will automatically serve these specific files to the frontend.

📂 User-Defined Knowledge Base (v1.0.0)

Managing your knowledge base source is now easier than ever.

- First Run Setup: On first launch, you will be prompted to select your Knowledge_Base folder.
- Persistent Config: Your selection is saved in kb_config.json and remembered across restarts.
- Change Anytime: Use the File > Change Knowledge Base... menu option to switch folders instantly.
- Reset: Use File > Reset to Default to return to the bundled demo notes.

🏗️ Build & Deployment

For developers building from source, NoteConnection offers two build modes:

- Full Mode (npm run electron:build): Includes demo data (~600MB). Best for testing/demos.
- Mini Mode (npm run electron:build:mini): Excludes large pre-generated files (~70MB installer). Best for distribution.

🛠️ Hardware & Driver Requirements (AMDGPU)

For optimal performance with "GPU Optimised Rendering", especially on AMD RDNA cards (like RX 7900XT):

1. Drivers: Ensure you have the latest AMD Adrenalin Edition drivers installed.
2. Node.js: The project uses gpu.js which relies on headless-gl for Node.js context.
- On Windows, this usually works out of the box with standard build tools (windows-build-tools).
- If you encounter gl errors, ensure Python and C++ compilers are available.

📅 Changelog

$3

- Reader Integration:
- Seamless Access: Double-clicking the central node in "Orbital Layout" now instantly opens the Reader, displaying full node content.
- Data Fetching: Fixed a critical issue where the reader would open empty; now correctly retrieves full metadata from the global graph state.
- Visual Polish:
- Orbital Layout: Significantly improved node dispersion (Radius 350-950px) to reduce label overlap.
- Edge Clarity: In Orbital mode, strictly hides edges not connected to the central node, reducing visual clutter by 90%.
- Label Visibility: Peripheral nodes now always display labels, sized proportionally to their distance (max 16px).
- Depth of Field: Adjusted opacity falloff to ensure distant nodes remain visible (min 0.4 opacity).
- UX Improvements:
- Target Selection: Increased the "Target Node" search limit from 20 to 300, ensuring users can find any node in the graph.
- Interactive Layers: Fixed z-index layering issues where the Reader window was previously hidden behind the Path visualization.

$3

- Path Mode: Introduced a major new feature set for converting graphs into linear learning paths.
- Learning Modes: 'Domain Learning' (Topological) and 'Diffusion Learning' (Goal-oriented).
- Visualization: New Radial and Tree layouts powered by D3/Canvas.
- Strategies: 'Foundational' and 'Core' sorting algorithms.
- Hybrid Architecture:
- Godot Bridge: Implemented PathBridge.ts to sync graph state with external renderers via WebSocket (Port 9876).
- Native Rendering: Added support for Godot 4.3 to render the graph with high-fidelity Vulkan graphics (Source in path_mode/).
- DevOps:
- NPM Scripts: Added pathmode:dev and pathmode:test workflows.
- UI Stability: Fixed critical bugs in Radial Layout visibility (centerView) and Exit Mode logic.

$3

- Backend Protocol Fix:
- Improved src/server.ts to correctly handle URL query parameters (e.g., ?v=timestamp) for static files.
- Resolves issues where cache-busting URLs would return 404 on Windows.
- UI Interaction Fix:
- Welcome Modal: Fixed a bug in welcome.js where skipping the tutorial would cause the folder selection menu to become unresponsive due to z-index clobbering.
- Guaranteed z-index: 1000 preservation for #source-control across all modal dismissal paths.

$3

- Mobile DevOps:
- Introduced build_apk.bat for one-click Android APK generation on Windows.
- Automated environment checks (Node, JDK, Android SDK) and project scaffolding.
- Documentation: Added comprehensive guides for mobile building in README and User Manual.

$3

- GitHub Actions Integration:
- Added automated npm publishing workflow triggered on releases and version tags.
- Added version consistency check to prevent mismatched releases.
- DevOps: Streamlined release process with git tag v1.1.0 && git push --tags.

$3

- Multilingual Consolidation:
- Removed redundant hardcoded translation logic in app.js.
- Centralized all UI strings into I18nManager for consistent language switching.
- Fixed "Mixed Language" issue in Welcome Modal where some labels remained in English.
- Onboarding UX Fixes:
- Tutorial Stability: Fixed a crash in Focus Mode tutorial by exposing enterFocusMode correctly.
- Welcome Modal Timing: Resolved race conditions in source_manager.js to ensure the modal displays accurately after data is loaded.
- Protocol & Caching:
- Cache-Busting Handler: Implemented a dynamic script loader in source_manager.js using timestamps to prevent browsers from serving stale data.js or app.js.
- Refined Protocol Handler: Optimized app:// protocol in main.ts using net.fetch for more robust local file serving in production.

$3

- Stability & Mini Build Reliability: Major fixes for the "Mini" build mode.
- First-Run Fix: Resolved critical crashes when no data is present on first launch (Added typeof safety checks).
- Artifact Cleanup: Build process now automatically cleans up previous data artifacts to ensure minimum installer size (~70MB).
- Worker Path Fix: Corrected path resolution for backend workers in production builds (Resolved double-dist folder issue).
- Absolute Offline Strategy: All external CDN dependencies migrated to local assets. The system is now 100% functional without an internet connection.
- Focus Mode Refinement:
- Visual Restoration: Fixed a bug where nodes retained Focus Mode sizes after exit. Now perfectly restores pre-focus radius and font-size.
- Stability: Fixed D3 sibling selection (getAttribute) errors during Focus entry.
- Physics & Spacing Overhaul:
- New Defaults: Standard link distance increased to 250px and collision radius to 25px.
- Expanded Customization: Slider ranges increased significantly (up to 600px distance / 100px collision).
- Quality of Life: Knowledge Base "All Folders" is now automatically selected in Electron mode for a smoother start.
- Performance & Focus Overhaul:
- O(1) Neighbor Lookup: Adjacency caching reduces transition time from O(N\*M) to O(1).
- Batched Rendering: UI updates synchronized via requestAnimationFrame.
- User-Defined Knowledge Base: New First-Run Setup, persistent configuration, and menu controls.
- Security & CSP: Enhanced CSP for extreme offline security and removed deprecated flags.

$3

- GPU Worker Integration: Fully enabled GPU acceleration in the frontend Simulation Worker. The worker now dynamically imports gpu-browser.min.js and layout_gpu.js and respects the gpuRendering setting.
- Performance Fix: Resolved an issue where "GPU Optimised Rendering" was ignored during the initialization phase, forcing CPU calculation. Large graphs now load significantly faster.
- Robustness: Fixed a critical bug in updateParams where existing GPU force instances were accidentally overwritten by CPU forces when changing physics settings.

$3

- Worker Sync & Stability: Introduced the Worker Handshake Protocol (isLayoutSwitching) to eliminate layout "bounce" and race conditions during transitions.
- Focus Mode Interaction: Decoupled manual dragging from physics in Focus Mode, ensuring nodes stay exactly where positioned without simulation interference.
- Layout Persistence: Added a 50% restoration safety threshold to the layout cache; automatically falls back to simulation relaxation if data is inconsistent.
- Analysis Stability: Optimized layout logic to prevent redundant resets during panel resizing while "Freeze Layout" is active.

$3

- GPU Link Force: Implemented high-performance GPU-accelerated spring forces using gpu.js. Supports "Gather" algorithm for efficient neighbor processing.
- Physics Robustness: Introduced velocity clamping (MAX_VELOCITY=100) and NaN/Infinity safety guards in GPU kernels to prevent node "explosions" and disappearing nodes.
- Layout Switching Fix: Implemented robust state preservation (layoutCache) for Force and DAG layouts, ensuring node positions are saved and restored without "teleportation". Fixed a critical crash in updateLayout and added Focus Mode support for GPU forces.
- GPU Resource Management: Refactored layout_gpu.js to use a Singleton pattern for the GPU context, preventing WebGL context leaks (limit 16) when toggling settings.

$3

- Backend Parallel Layout: Accelerated front-end loading by pre-calculating node positions on the backend using worker threads or GPU.
- GPU Optimised Rendering: In the backend layout, added support for AMDGPU acceleration.
- Static Mode: Implemented strict simulation freezing for massive graphs (>5000 nodes) to save resources.
- CLI Support: Added full CLI argument support for automated building and loading.
- Extreme Scale Optimization: Disabled edge rendering entirely for graphs with >10,000 nodes to prevent browser crashes.

$3

- [x] Critical Fix: Fixed a race condition where the rendering loop started before UI controls were fully initialized, causing blank screens and unresponsive buttons on large datasets.

$3

- [x] Critical Fix: Resolved a "Maximum call stack size exceeded" crash in the frontend when loading graphs with over 100,000 edges. This fixes the "Nodes: 0" issue for massive datasets.

$3

- [x] Compact Mode: Added a new mode that hides edges by default to improve performance for massive graphs (>5k nodes). This mode is automatically enabled for large datasets but can be toggled in settings.
- [x] Canvas Fix: Resolved an issue where large graphs would display a blank screen on load by forcing an initial canvas render frame.
- [x] Optimization: Rendering loop now completely skips edge iteration in Compact Mode, significantly reducing CPU usage during idle or pan/zoom.

$3

- [x] Smart Rendering: Automatically switches to Canvas mode by default when the graph contains more than 3000 nodes.
- [x] Performance: Reduces browser memory footprint and improves frame rates for large datasets on initial load.

$3

- [x] Performance: Parallelized the "Graph Metrics" calculation (Betweenness Centrality) using worker threads.
- [x] Scalability: Distributed heavy Brandes Algorithm computations across multiple CPU cores, ensuring faster graph construction for large datasets.

2026-01-07 v0.9.59 - Vector Space Memory Fix (Sparse Matrix)

Goal: Resolve the "Heap out of memory" crash on Windows 10/11 (128GB RAM) when processing 13k+ files by replacing the dense TF-IDF matrix with a Sparse Vector implementation.

- [x] Memory Optimization
- [x] Sparse Vectors: Refactored VectorSpace to use Uint32Array (indices) and Float32Array (values) instead of standard Javascript Arrays.
- [x] Efficiency: Reduced memory footprint for 13k files from ~10GB+ (dense) to <500MB (sparse).
- [x] Algorithm: Optimized Cosine Similarity calculation to use sparse dot product ($O(min(N, M))$).
- [x] Config: Increased default Node.js heap limit to 12GB (--max-old-space-size=12288) in package.json to utilize available system RAM.

2026-01-07 v0.9.58 - Hybrid Inference Resource Reuse (Optimization)

- [x] Memory Optimization: Implemented resource reuse logic for "Statistical Matrix" and "Vector Space" in GraphBuilder.
- [x] Efficiency: Prevents redundant recalculation of heavy data structures during Hybrid Inference, eliminating memory spikes and resolving OOM crashes on large datasets.
- [x] Cleanup: Added strict memory cleanup steps after inference tasks complete.

$3

- [x] Stability Fix: Resolved "Heap out of memory" crashes when processing large datasets (>13k files) by optimizing the data transfer strategy for Worker Threads.
- [x] Efficiency: Workers now receive file paths and read content on-demand, eliminating the memory overhead of cloning large file content strings across threads.

$3

- [x] Memory Analysis: Added granular performance logging to the Hybrid Inference engine, tracking heap usage every 1000 nodes to identify memory spikes on Windows.
- [x] Optimization: Implemented aggressive memory cleanup (clearing matrices and nullifying vector space) immediately after inference completion to prevent Heap OOM.

$3

- [x] Stability Fix: Resolved "Heap out of memory" crashes on Windows 10/11 by implementing explicit memory clearing for file content before the algorithmic phase.
- [x] Robustness: Refactored CycleDetector to use an Iterative DFS (stack-based) approach, eliminating stack overflow risks on deep graphs.
- [x] Observability: Split performance logging for "Algorithmic Core" into distinct "Cycle Detection" and "Topological Sort" phases for precise debugging.

$3

- [x] Onboarding: Added a "Welcome" modal that appears when the graph is empty, guiding new users to select a source and load data.
- [x] UX: Highlights the "Source Select" controls during the welcome state.

$3

- [x] Architecture Refactor: Extracted the core graph building logic into a standalone NoteConnection class (src/core/NoteConnection.ts).
- [x] Plugin Prep: Decoupled the core API from CLI/Server-specific file operations, enabling direct integration with future Joplin/Obsidian plugins.
- [x] Documentation: Updated User Manual with missing "Max Workers" performance setting.

$3

- [x] Stability Fix: Resolved a critical "Heap out of memory" crash on Windows 10/11 when building large graphs with many cycles.
- [x] Algorithm Optimization: Updated CycleDetector to limit the number of detected cycles, preventing excessive memory consumption during recursion.

$3

- [x] System Monitoring: Implemented comprehensive performance logging for backend processes (CPU, Memory, Time).
- [x] GPU Diagnostics: Added execution timing and memory tracking for GPU acceleration steps.
- [x] Crash Reporting: Implemented CrashLogger to automatically record unhandled exceptions and worker failures to crash.log for debugging stability issues on Windows 11.
- [x] Optimization: Integrated PerformanceLogger across the entire Graph Construction pipeline (Node Init, Edge Matching, Inference).

$3

- [x] Verification: Confirmed feasibility of using AMD Radeon 7900XT for graph construction acceleration via gpu.js.
- [x] Strategy: Validated that Mathematical Inference (Vector Similarity) can be offloaded to GPU, while Text Processing remains optimized on CPU.
- [x] Implementation: Added amdgpu module with VectorSpaceGPU class. Integrated into GraphBuilder to automatically use GPU for Cosine Similarity matrix calculations when enabled.

$3

- [x] Performance: Fixed a critical "Heap out of memory" crash when processing large datasets (>10,000 files) by optimizing the Statistical Analyzer algorithm.
- [x] Efficiency: Reduced the complexity of co-occurrence matrix calculation by ~30x using a sparse, file-centric approach.

$3

- [x] Settings UI: In the Settings Modal, added a "Performance" section with a slider and number input to control "Max Workers".
- [x] API Integration: The "Load" button now sends the user-defined worker limit to the backend build process.
- [x] Persistence: The worker setting is saved in localStorage alongside other preferences.

$3

- [x] Configurable Workers: Added 'maxWorkers' configuration to allow utilizing more CPU cores for graph building and statistical inference. Removed the hardcoded limit of 12 workers.

$3

- [x] Interaction Logic: Fixed an issue where double-clicking a node to enter Focus Mode would accidentally trigger a zoom-in event. Added event propagation control to prevent this (SVG & Canvas).
- [x] Vertical Layout Spacing: Increased the horizontal offset of node labels in Vertical Focus Mode to prevent text from overlapping with nodes, improving readability (SVG & Canvas).

$3

- [x] Immersive Focus: The main control panel and source selection bar are now completely hidden during Focus Mode for a distraction-free experience.
- [x] Canvas Polish: Removed edge rendering in Canvas Focus Mode to reduce visual noise.

$3

- [x] Canvas Interactive: Canvas mode now supports Hover (Highlight), Single Click (Stats), and Double Click (Focus Mode) interactions, bringing it to feature parity with SVG.
- [x] Visual Fixes: Fixed an issue where nodes in Canvas mode were rendered too large; they now respect "Size By" settings.
- [x] Cleanup: Removed the deprecated "View Mode" (Clusters) feature.

$3

- [x] Smart Spacing: "Layer-Space" and "Node-Space" settings are now saved independently for "Horizontal" and "Vertical" focus layouts.
- [x] Optimized Defaults: Reduced default Horizontal Layer-Space by 50% and Vertical Node-Space by 75% for tighter, more readable layouts.

$3

- [x] Dynamic Labels: The "Repulsion Strength" label in the settings now dynamically changes between "Repulsion (Force)" and "Repulsion (DAG)" to clearly indicate which layout configuration is being modified.

$3

- [x] Mode-Specific Physics: "Repulsion Strength" is now configured independently for "Force" and "DAG" modes.
- [x] Smart Defaults: Set default repulsion to -550 for Force layout (clusters) and -850 for DAG layout (hierarchy) to optimize initial visual separation.
- [x] Context-Aware Settings: The Settings Modal automatically shows the repulsion value for the current layout.

$3

- [x] Resource Saving: The simulation now automatically pauses when the "Visualization Settings" modal is opened, reducing CPU usage during configuration. It resumes upon closing unless "Freeze Layout" is globally enabled.

$3

- [x] Settings Isolation: Adjusting parameters in the "Visualization Settings" modal (e.g., Repulsion, Opacity) no longer triggers a simulation restart if the layout is frozen. Visual changes apply immediately, while physics updates await unfreezing.

$3

- [x] Consistent Transition: Switching layouts now triggers the same "Rapid Relaxation" (0.2 damping for 2s) as the initial load, ensuring nodes arrange themselves quickly.
- [x] Smart Freeze: If "Freeze Layout" is active during a switch, the simulation runs for the 2-second relaxation period to establish the new structure before automatically freezing.

$3

- [x] Rich Text Support: Fixed an issue where HTML tags (e.g., bold text, line breaks) in the localized UI were displayed as raw text. The system now correctly renders HTML formatting in translations.

$3

- [x] Smart Damping: The simulation now starts with low friction (0.2) for 2 seconds to allow rapid untangling of nodes ("relaxation"), then automatically increases to high friction (0.95) for stability.

$3

- [x] Strict Freeze: If "Freeze Layout" is active, changing "Degree Basis" or "Size By" settings no longer wakes up the simulation. Visuals update (node sizes change) while positions remain strictly locked.

$3

- [x] Smoother Culling: Increased the off-screen "active" buffer to 800px (visual), preventing nodes near the edge from freezing abruptly during panning.
- [x] Extended Zoom: Lowered the global simulation freeze threshold from 0.4x to 0.1x, allowing physics to continue running even when significantly zoomed out.

$3

- [x] Layout Transition Logic: Implemented a global unfreeze mechanism during layout switching.
- [x] Override Culling: Switching layouts (e.g., Force to DAG) now forcefully clears viewport culling locks (isCulled, fx, fy), ensuring all nodes, including off-screen ones, correctly participate in the new layout arrangement.

$3

- [x] Template States: Implemented independent state caching for "Force" and "DAG" layouts.
- [x] Instant Switch: Switching layouts now saves the current state and restores the target state instantly without recalculation or visual movement, preserving the exact arrangement of each view.

$3

- [x] Damping: Increased default friction to 0.92 for faster settling.
- [x] Render Culling: DOM updates are skipped for off-screen frozen nodes.

$3

- [x] Performance: Implemented smart viewport culling to reduce simulation load.
- [x] Full View Freeze: Automatically freezes the simulation when zoomed out (< 0.4x) to view the entire graph.
- [x] Off-screen Freezing: When zoomed in, only nodes within the visible viewport (plus a buffer) are simulated; off-screen nodes are frozen.

$3

- [x] Position Consistency: Implemented coordinate backup/restore logic (x, y, fx, fy) for Focus Mode.
- [x] Behavior: Exiting Focus Mode now reverts the graph layout to its _exact_ state prior to entry, discarding any temporary arrangements or drags made during the focused session.
- [x] UX: Fulfills the requirement that Focus Mode should have zero impact on the main interface's layout structure.

$3

- [x] Bug Fix: Resolved an issue where opening the Analysis Panel or resizing the window would override the "Freeze Layout" state, causing unwanted node movement.
- [x] Robustness: The physics simulation now strictly respects the frozen state during layout changes, ensuring nodes remain stationary as expected.

$3

- [x] Logic Correction: Resolved a conflict where "Exit Focus Mode" would unconditionally restart the physics simulation, overriding the "Freeze Layout" state.
- [x] Priority Enforcement: If "Freeze Layout" is checked, exiting Focus Mode now stops the simulation and forces a static render update, ensuring nodes remain strictly inactive as requested.

$3

- [x] Freeze Layout Quick Button: Added a dedicated freeze button (❄️) to the main interface for instant access, improving mobile usability.
- [x] Sync: State is synchronized with the simulation panel checkbox.
- [x] Visuals: Button turns red when frozen.
- [x] Quick Start Manual: Implemented a "Quick Start Guide" modal for new users.
- [x] Content: Covers Loading, Navigation, Focus Mode, and Controls.
- [x] Onboarding: Automatically shows on first visit (unless "Don't show again" is checked).
- [x] Access: Accessible anytime via the new "Help" (❓) button.
- [x] Localization: Fully localized new UI elements in English and Chinese.

$3

- [x] Resource Optimization: In the main interface (SVG Mode), enabling "Freeze Layout" now completely disables node dragging in addition to stopping the simulation.
- [x] Logic: Prevents the physics simulation from restarting (waking up) due to drag events, ensuring maximum CPU/Memory savings.
- [x] Focus Mode Preservation: Dragging and manual positioning capabilities remain fully active in Focus Mode, unaffected by the global freeze setting.

$3

- [x] Simulation Optimization: Restricted physics simulation during Focus Mode to only active nodes (focus center + neighbors).
- [x] Resource Saving: Background nodes are frozen (removed from simulation loop), significantly reducing CPU/Memory usage while maintaining their exact visual state.
- [x] Seamless Restoration: Background nodes are instantly restored to their original positions upon exiting Focus Mode.

$3

- [x] Reading Window: Set default font size (zoom level) to minimum (0.5x) for compact reading.
- [x] Simulation Physics: Increased default Damping (velocityDecay) from 0.4 to 0.6 for more stable graph movement.

$3

- [x] Touch Interaction: Added support for dragging the statistics popup on mobile devices by holding the title bar.
- [x] Pinch-to-Zoom: Implemented two-finger pinch gesture to resize/scale the popup content on touch screens.
- [x] UX Polish: Prevented page scrolling during popup interactions for a smoother experience.

$3

- [x] Strict Edge Visibility: Enforced rule where edges are completely hidden (opacity 0) by default in SVG mode, matching Canvas mode behavior.
- [x] Performance Optimization: Reduced rendering overhead by ensuring relationship lines are calculated and drawn _only_ during interaction (Hover/Click/Focus), complying with strict visibility requirements.

$3

- [x] Clean Focus Transition: When double-clicking a node to enter Focus Mode, any existing selection or highlight state is now automatically cleared, providing a clean and uncluttered focused view.
- [x] Auto-Hide Popup: The statistics popup is automatically hidden when entering Focus Mode, preventing visual conflicts.
- [x] Enhanced UX: Ensures users always start with a pristine focused context without residual artifacts from previous node selections.

$3

- [x] Focus Mode Re-entry: Fixed issue where double-clicking a related node while in focus mode wouldn't refresh properly. Now seamlessly switches focus between connected nodes.
- [x] Draggable Popup: Node statistics popup can now be dragged by its header to any screen position for better workspace organization.
- [x] Zoomable Popup: Added zoom controls (+/−/⟲) to scale popup content from 0.5x to 2.0x for improved readability.
- [x] Resizable Popup: Enabled browser-native resize handle for manual popup size adjustment.
- [x] State Management: Improved node visibility flag reset to prevent accumulation issues when switching focus contexts.

$3

- [x] Modular Architecture: Created dedicated NodeHighlightManager class for clean separation of highlighting logic.
- [x] Unified Interface: Single API for both PC (hover) and mobile (click) interactions.
- [x] State Management: Proper tracking of highlight/frozen states with focus mode awareness.
- [x] Enhanced Rendering: Consistent visual behavior across SVG and Canvas modes.
- [x] Bilingual Documentation: Comprehensive Chinese/English comments throughout the codebase.
- [x] Robust Integration: Full compatibility with existing focus mode, analysis panel, and statistics popup features.

$3

- [x] Colored Arrows: SVG edges now use Red and Blue arrowheads when highlighted, ensuring the entire connection is color-coded.

$3

- [x] Full Context: Clicking or hovering a node now reveals all connections (In & Out) regardless of the active filter mode.
- [x] Canvas Polish: Added bold styling for highlighted edges in the Canvas renderer.

$3

- [x] Edge Highlighting: Fixed an issue where edge colors (Red/Blue) and bold styling were not applying correctly in SVG mode.
- [x] Data Deduplication: Ensured neighbor lists in the Statistics Popup do not contain duplicate entries.

$3

- [x] Interaction Constraint: Ensured that the floating statistics popup and associated highlighting are strictly disabled when Focus Mode is active, preventing context conflict.

$3

- [x] Node Statistics: Implemented a separate floating window for node details (In/Out Degree) to decouple it from the main Degree Analysis panel.
- [x] Visualization: In-degree and Out-degree relationships are clearly distinguished with Red/Blue indicators in the popup.

$3

- [x] Inspection: Clicking a node now freezes the entire simulation for stable inspection of connections.
- [x] Resume: Clicking the background resumes the simulation (if not manually frozen).

$3

- [x] Mobile Adaptation: Implemented slide gestures (up/down) to resize the analysis panel, full-screen drag snap, and drag handle.
- [x] Interaction: Verified node click sync between analysis panel and graph.

$3

- [x] Graph Sync: Clicking table rows now highlights nodes in the graph.
- [x] Mobile UX: Fixed mobile scrolling in Analysis Panel.

$3

- [x] Focus Mode: Fixed a bug where changing the layout type did not trigger an immediate refresh.

$3

- [x] Analysis Panel: Added "Full Screen" toggle and "Pinch-to-Zoom" for better mobile readability.
- [x] Visuals: Fixed Mermaid Zoom text styling; Added background click to clear highlights.

$3

- [x] Focus Mode: Added "Hierarchical (Left-Right)" layout and semantic labels ("Helping to understand" / "Further exploration").
- [x] Analysis Panel: Optimized for mobile (scrollable) and added click-to-highlight interaction with the main graph.
- [x] Visuals: Enhanced Mermaid diagram text visibility for light backgrounds; Fixed Focus Mode centering.

$3

- [x] Responsive Controls: Main panel collapses on mobile; Focus UI moved to bottom.
- [x] Touch Zoom: Added pinch-to-zoom support in the Reading Window.

$3

- [x] Hover Lock: Hovering over a node locks its position to prevent inspection drift.
- [x] Simulation Controls: Added Freeze Layout checkbox and Speed/Damping slider.

$3

- [x] Freeze on Select: Nodes in Focus Mode retain their position after interaction.

$3

- [x] Clutter Reduction: Edges and orphans hidden by default.
- [x] Horizontal Spacing: New slider for horizontal node separation in Focus Mode.

$3

- [x] Canvas Renderer: Added HTML5 Canvas support for high performance.
- [x] Worker Scaling: Increased thread limit to 12.

---

---

NoteConnection: 层级知识图谱可视化系统

> 解锁你知识库的深层结构。

NoteConnection 是一个高性能的独立可视化系统，旨在将非结构化的 Markdown 知识库转化为有向无环图 (DAG)。

与展示杂乱链接网的传统“网络”视图不同，NoteConnection 揭示了隐藏在笔记中的层级关系、学习路径和依赖结构。它专为可扩展性而设计，能够轻松处理数万个节点，并且完全独立于任何特定的笔记应用程序运行。




---

🚀 核心特性

$3

- 结构优于混沌: 在 力导向 (Force-Directed) 和 DAG (层级) 布局之间切换。DAG 布局自动识别“先决条件”和“后续步骤”，将概念按逻辑分层排列。
- 双渲染引擎 (v0.8.7): 无缝切换 SVG (用于交互) 和 Canvas (用于 10,000+ 节点的高性能渲染)。
- 交互式专注模式: 点击任意节点以隔离它及其上下文。包含 选中冻结 (v0.8.9) 以防止漂移，可调节的 垂直/水平间距 (v0.8.8)，以及退出后完美的视觉状态恢复 (v1.0.0)。
- 完全离线化支持 (v1.0.0): 所有关键库依赖（D3, KaTeX, Marked, Mermaid 等）均已本地化，确保 100% 离线可用性。

$3

- 混合推断引擎: 结合 统计概率 ($P(A|B)$) 和 向量相似度 (TF-IDF) 推断隐藏的依赖关系（例如，“荧光”隐含“光子”），无需外部 AI API。
- 可扩展聚类: 基于文件夹结构或标签，将数千个节点聚合为高级“概念气泡”，提供清晰的概览。

$3

- 课程生成: 将复杂的网状图瞬间转化为线性的学习路径。
- 领域学习 (Domain Learning): 掌握整个概念集群（拓扑排序）。
- 扩散学习 (Diffusion Learning): 寻找通往特定目标的最优路径（最短路径 + 前置依赖）。
- 混合架构: 通过 WebSocket (ws://localhost:9876) 连接到高保真 Godot 4.3 桌面渲染器，实现 3A 级的可视化效果，同时保持完全的 Web 兼容性。
- 智能策略: 支持 "基础优先" (Foundational) 或 "核心优先" (Core) 排序，适应不同的学习风格。

$3

- 高容量并行处理: 利用 Node.js worker_threads (最多 12 核) 分发计算密集的关键词匹配任务。
- 模拟控制 (v0.9.0): 通过 速度/阻尼滑块 微调物理效果，或使用 冻结布局 开关停止模拟以进行稳定的手动排列。
- 悬停锁定: 悬停在节点上时暂时锁定其位置，以便稳定地检查连接。

---

💻 硬件与驱动要求 (Hardware & Driver Requirements)

$3

NoteConnection 利用 gpu.js 进行基于 WebGL 的加速，并计划通过 ROCm 支持本地 AI 推断。

- RDNA 3 (推荐): Radeon RX 7000 系列 (例如 RX 7900 XT/XTX)。
- _状态_: WebGL 和计算性能最佳。
- RDNA 2: Radeon RX 6000 系列。
- _状态_: 稳定且成熟的支持。

$3

#### Windows (开发环境)

- 驱动程序: AMD Software: Adrenalin Edition (23.12.1+)。
- 需要 DirectX 12/Vulkan/OpenGL 支持以底层支持 WebGL。
- 构建工具: 用于为 Node.js 编译 headless-gl：
- 安装 Python 3.x 并加入 PATH。
- Visual Studio Build Tools (C++ 工作负载)。

#### Linux (AI 推荐)

- Mesa (RADV/Radeonsi): 默认开源驱动。最适合通用 WebGL 和 gpu.js。
- ROCm (Radeon Open Compute): 仅在计划开发 AI 推断功能（未来路线图）时安装。NoteConnection 的核心可视化在标准 Mesa 驱动上运行良好。

---

🏗️ 系统架构

NoteConnection 基于模块化架构构建，旨在实现高性能和可扩展性。

$3

- GraphBuilder: 核心协调器。管理从文件读取到图构建的整个流程。
- Worker Threads: 繁重的任务（关键词匹配、文本分析）被卸载到工作线程池 (src/backend/workers)，确保主线程保持响应。
- 推断引擎:
- StatisticalAnalyzer: 计算共现矩阵。
- VectorSpace: 处理 TF-IDF 嵌入和余弦相似度。
- HybridEngine: 结合信号建议有向边。

$3

- 双引擎渲染器:
- D3.js (SVG): 用于高保真、交互式图表，具有详细的工具提示和 CSS 样式。
- HTML5 Canvas: 针对海量数据集进行了优化，消除了 DOM 操作的开销。
- 状态管理: SettingsManager 将用户偏好（物理、视觉）持久化到 localStorage。
- 布局逻辑: 自定义的 Sugiyama 风格分层算法和力导向物理算法。

$3

- PathBridge: 标准 WebSocket 服务器 (端口 9876)，将内部图谱状态暴露给外部应用程序（例如 Godot 引擎），实现混合 Web/原生可视化管线。

---

📦 快速开始

$3

1. 从 最新发布页面 下载 NoteConnection.Setup.exe。
2. 运行安装程序。
3. 从桌面或开始菜单启动 NoteConnection。

$3

无需安装。

`bash
npx noteconnection
`

$3

`bash
npm install -g noteconnection
noteconnection
`

$3

`bash
git clone https://github.com/Jacobinwwey/NoteConnection.git
cd NoteConnection
npm install
npm start
`

- 服务器运行于: http://localhost:3000

$3

NoteConnection 使用 Capacitor 构建原生移动应用。

#### 先决条件

- Node.js (LTS)
- Java JDK (17 或更高版本)
- Android SDK (配置在 ANDROID_HOME 或通过 Android Studio 安装)

#### 方法 A: 一键构建 (推荐)

在 Windows 上直接运行包含的批处理脚本：

`cmd
build_apk.bat
`

该脚本会自动：

1. 检查您的环境 (Node, Java, Android SDK)。
2. 安装依赖项。
3. 构建 Web 资源。
4. 同步 Capacitor。
5. 使用 Gradle 编译 APK。

#### 方法 B: 手动构建步骤

1. 构建 Web 资源:
`bash
npm run build
`
2. 同步到 Android 平台:
`bash
npx cap sync
`
3. 构建 APK:
在 Android Studio 中打开 android 目录并构建，或使用命令行:
`bash
cd android
./gradlew assembleDebug
`
APK 将位于: android/app/build/outputs/apk/debug/app-debug.apk

---

🖥️ CLI 命令行使用 (v0.9.71)

您可以直接从命令行加载知识库并构建图谱，而无需使用 UI。这对于自动构建或无头环境非常有用。

$3

`bash
npm start -- --path "<知识库路径>" [选项]
`

$3

| 选项 | 描述 | 默认值 |
| ----------- | ----------------------------------------- | --------------------- |
| --path | 包含 Markdown 文件的文件夹的绝对路径。 | Knowledge_Base |
| --gpu | 为布局和向量计算启用 AMDGPU/WebGL 加速。 | true (如果硬件支持) |
| --no-gpu | 禁用 GPU 加速 (强制使用 CPU)。 | false |
| --static | 启用静态模式 (仅后端计算，前端布局冻结)。 | false |
| --workers | 要使用的 Worker 线程数。 | numCPUs - 1 |

$3

`bash


基础加载

npm start -- --path "C:/Users/MyName/Documents/MyNotes"

GPU 加速构建

npm start -- --path "E:/Knowledge/ObsidianVault" --gpu

强制 CPU (如果 GPU 出现问题)

npm start -- --path "E:/Knowledge/ObsidianVault" --no-gpu
`

注意: CLI 运行会生成唯一的静态数据文件 (data_cli_{kb_name}_{time}.js) 以保护原始 data.js。服务器启动时，它会自动为前端提供这些特定的文件。

---

📂 用户定义知识库 (User-Defined Knowledge Base - v1.0.0)

管理知识库源现在变得更加简单。

- 首次运行设置: 首次启动时，系统会提示您选择 Knowledge_Base 文件夹。
- 持久化配置: 您的选择保存在 kb_config.json 中，并在重启后自动加载。
- 随时更改: 使用 文件 > 更改知识库... 菜单选项即时切换文件夹。
- 重置: 使用 文件 > 重置为默认 返回由捆绑的演示笔记。

🏗️ 构建与部署 (Build & Deployment)

对于从源码构建的开发者，NoteConnection 提供两种构建模式：

- 完整模式 (Full Mode) (npm run electron:build): 包含演示数据 (~600MB)。最适合测试/演示。
- 精简模式 (Mini Mode) (npm run electron:build:mini): 排除大型预生成文件 (~70MB 安装包)。最适合分发。

---

📅 更新日志 (Changelog)

$3

- 阅读器集成 (Reader Integration):
- 无缝访问: 在“轨道布局”中双击中心节点现在会立即打开阅读器，显示完整的节点内容。
- 数据获取: 修复了阅读器打开为空的关键问题；现在可以正确地从全局图状态检索完整的元数据。
- 视觉打磨 (Visual Polish):
- 轨道布局: 显著改进了节点分散度（半径 350-950px），减少了标签重叠。
- 边缘清晰度: 在轨道模式下，严格隐藏未连接到中心节点的边，将视觉混乱减少了 90%。
- 标签可见性: 周围节点现在总是显示标签，并根据距离按比例缩放（最大 16px）。
- 景深 (DoF): 调整了不透明度衰减，以确保远处的节点保持可见（最小 0.4 不透明度）。
- 用户体验改进 (UX Improvements):
- 目标选择: 将“目标节点”搜索限制从 20 增加到 300，确保用户可以找到图中的任何节点。
- 交互层级: 修复了 z-index 层级问题，之前的阅读器窗口被隐藏在路径可视化后面。

$3

- 路径模式 (Path Mode): 引入了一套主要的新功能，用于将图谱转化为线性的学习路径。
- 学习模式: '领域学习' (拓扑排序) 和 '扩散学习' (目标导向)。
- 可视化: 由 D3/Canvas 驱动的全新径向和树状布局。
- 策略: '基础优先' 和 '核心优先' 排序算法。
- 混合架构:
- Godot 桥接: 实现了 PathBridge.ts，通过 WebSocket (端口 9876) 与外部渲染器同步图谱状态。
- 原生渲染: 添加了对 Godot 4.3 的支持，以渲染高保真的 Vulkan 图形 (源码位于 path_mode/).
- 运维 (DevOps):
- NPM 脚本: 添加了 pathmode:dev 和 pathmode:test 工作流。
- UI 稳定性: 修复了径向布局可见性 (centerView) 和退出模式逻辑中的关键 Bug。

$3

- 后端协议修复:
- 改进了 src/server.ts，使其能够正确处理静态文件的 URL 查询参数（如 ?v=timestamp）。
- 解决了 Windows 环境下带缓存刷新参数的 URL 返回 404 的问题。
- UI 交互修复:
- 欢迎弹窗: 修复了 welcome.js 中的一个错误，即跳过教程会导致文件夹选择菜单因 z-index 被清除而无法响应的问题。
- 确保 #source-control 在所有弹窗关闭路径下都能保持 z-index: 1000。

$3

- 移动端运维:
- 引入了 build_apk.bat，用于在 Windows 上一键生成 Android APK。
- 自动化环境检查（Node, JDK, Android SDK）和项目脚手架搭建。
- 文档: 在 README 和用户手册中添加了移动端构建的详细指南。

$3

- GitHub Actions 集成:
- 新增自动 npm 发布工作流，支持发布事件和版本标签触发。
- 新增版本一致性检查，防止版本号不匹配的发布。
- DevOps: 简化发布流程，使用 git tag v1.1.0 && git push --tags 即可发布。

$3

- 多语言体系整合:
- 移除了 app.js 中冗余的硬编码翻译逻辑。
- 将所有 UI 字符串集成至 I18nManager，确保全应用语言切换的一致性。
- 修复了欢迎弹窗中部分标签显示为英文的“语种混合”问题。
- 新人引导体验修复:
- 教程稳定性: 通过正确暴露 enterFocusMode 接口，修复了专注模式教程引发的崩溃。
- 欢迎弹窗逻辑: 优化了 source_manager.js 中的加载时序，确保在数据状态确认后准确触发弹窗。
- 协议与缓存优化:
- 缓存刷新机制: 在 source_manager.js 中实现了带时间戳的动态脚本加载器，防止浏览器加载旧版的 data.js 或 app.js。
- 协议处理器精简: 优化了 main.ts 中的 app:// 协议处理器，采用 net.fetch 提供更稳健的本地文件访问支持。

$3

- 稳定性与精简版可靠性: 对“精简模式”进行了重大修复。
- 首次启动修复: 解决了应用在无数据状态下首次启动时的崩溃问题（增加了 typeof 安全检查）。
- 产物自动清理: 构建过程自动清理旧的数据残留，确保安装包体积最小化 (~70MB)。
- Worker 路径修复: 修正了生产构建中后端工作线程的双层 dist 路径解析错误。
- 完全离线化策略: 所有外部依赖均已迁移为本地资源。系统现在可在完全离线环境下运行。
- 专注模式细化:
- 视觉状态恢复: 修复了退出专注模式后节点大小错误的 Bug。现在能完美恢复原始半径和字体大小。
- 交互稳定性: 修复了进入专注模式时的 D3 事件关联错误。
- 物理与间距优化:
- 全新默认值: 默认链接距离增加至 250px，碰撞半径增加至 25px。
- 扩展自定义范围: 滑动条范围增加至 600px 距离 / 100px 碰撞。
- 性能与专注模式重构:
- O(1) 邻居查找: 在客户端实现邻接缓存，将切换耗时从 $O(N \times M)$ 降低至 $O(1)$。
- 批量渲染: 使用 requestAnimationFrame 同步渲染，确保平滑过渡。
- 用户定义知识库: 全新的知识库路径管理、持久化配置及菜单控制。
- 安全与 CSP: 增强了 CSP 以支持极端的离线安全，并移除了已弃用的 Electron 标志。

$3

- GPU 工作线程集成: 全面启用了前端模拟工作线程 (Simulation Worker) 中的 GPU 加速。工作线程现在可以动态导入 gpu-browser.min.js 和 layout_gpu.js，并遵循 gpuRendering 设置。
- 性能修复: 解决了在初始化阶段忽略“GPU 优化渲染”设置、导致强制使用 CPU 计算的问题。现在大型图谱的加载速度显著提升。
- 稳健性: 修复了 updateParams 中的一个关键错误，即在更改物理设置时，现有的 GPU 力实例会被意外地替换为 CPU 力。

$3

- GPU 链接力 (Link Force): 使用 gpu.js 实现了高性能的 GPU 加速弹簧力。支持 "Gather" 算法，用于高效的邻居处理。
- 物理稳健性: 在 GPU 核函数中引入了速度钳位 (MAX_VELOCITY=100) 和 NaN/无穷大安全防护，防止节点“爆炸”和消失。
- 布局切换修复: 实现了 Force 和 DAG 布局的稳健状态保存 (layoutCache)，确保节点位置在切换时被保存和恢复，消除了“瞬移”现象。修复了 updateLayout 中的关键崩溃，并增加了专注于模式对 GPU 力的支持。
- GPU 资源管理: 重构 layout_gpu.js 使用单例模式管理 GPU 上下文，防止在切换设置时发生 WebGL 上下文泄漏 (限制 16 个)。

$3

- 后端并行布局: 通过使用 Worker 线程或 GPU 在后端预计算节点位置，加速前端加载。
- GPU 优化渲染: 在后端布局中添加了对 AMDGPU 加速的支持。
- 静态模式: 为海量图谱 (>5000 节点) 实现了严格的模拟冻结以节省资源。
- CLI 支持: 添加了完整的 CLI 参数支持，用于自动化构建和加载。
- 极端规模优化: 对于超过 10,000 个节点的图谱，完全禁用了边渲染，以防止浏览器崩溃。

$3

- [x] 紧凑模式: 添加了一种新模式，默认隐藏边以提高海量图谱（>5k 节点）的性能。此模式在大数据集上自动启用，但可以在设置中切换。
- [x] Canvas 修复: 解决了大图在加载时因强制初始 Canvas 渲染帧而显示白屏的问题。
- [x] 优化: 渲染循环现在在紧凑模式下完全跳过边迭代，显著降低了空闲或平移/缩放期间的 CPU 使用率。

$3

- [x] 智能渲染: 当图谱包含超过 3000 个节点时，默认自动切换到 Canvas 模式。
- [x] 性能: 降低浏览器内存占用，并提高大数据集初始加载时的帧率。

$3

- [x] 性能: 使用 Worker 线程并行化了“图指标”计算（介数中心性）。
- [x] 可扩展性: 将繁重的 Brandes 算法计算分发到多个 CPU 核心，确保大数据集的图构建更快。

$3

- [x] 内存优化: 在 GraphBuilder 中为“统计矩阵”和“向量空间”实现了资源重用逻辑。
- [x] 效率: 防止在混合推断期间重复计算繁重的数据结构，消除了内存峰值并解决了大数据集上的 OOM 崩溃问题。
- [x] 清理: 在推断任务完成后添加了严格的内存清理步骤。

$3

- [x] 握手协议: 引入了 Worker 握手协议 (isLayoutSwitching)，有效解决了布局切换竞态，防止延迟消息导致 UI 跳变。
- [x] 专注模式隔离: 为专注模式实现了完全的手动坐标管理，拖动节点不再受物理引擎干扰，确保定位精准。
- [x] 布局缓存安全: 增加了 50% 的布局恢复安全阈值，缓存异常时自动执行物理松弛，防止图谱崩溃。
- [x] 分析面板稳定: 优化了面板缩放时的渲染逻辑，在“冻结布局”激活时严格禁止不必要的物理重启。

$3

- [x] 稳定性修复: 通过优化 Worker 线程的数据传输策略，解决了处理大数据集 (>13k 文件) 时的“堆内存溢出”崩溃问题。
- [x] 效率: Worker 现在接收文件路径并按需读取内容，消除了跨线程克隆大型文件内容字符串的内存开销。

$3

- [x] 内存分析: 为混合推断引擎添加了细粒度的性能日志，每 1000 个节点跟踪一次堆内存使用情况，以识别 Windows 上的内存峰值。
- [x] 优化: 在推断完成后立即实施激进的内存清理（清除矩阵和置空向量空间），以防止堆内存溢出。

$3

- [x] 稳定性修复: 通过在算法阶段之前显式清除文件内容内存，解决了 Windows 10/11 上的“堆内存溢出”崩溃问题。
- [x] 稳健性: 重构 CycleDetector 使用 迭代 DFS（基于栈）方法，消除了深度图上的堆栈溢出风险。
- [x] 可观测性: 将“算法核心”的性能日志拆分为“循环检测”和“拓扑排序”两个独立阶段，以便进行精确调试。

$3

- [x] 引导 (Onboarding): 添加了一个“欢迎”模态框，当图谱为空时出现，引导新用户选择数据源并加载数据。
- [x] 用户体验 (UX): 在欢迎状态下高亮显示“源选择”控件。

$3

- [x] 架构重构: 将核心图构建逻辑提取到独立的 NoteConnection 类 (src/core/NoteConnection.ts) 中。
- [x] 插件准备: 将核心 API 与 CLI/服务器特定的文件操作解耦，从而支持与未来的 Joplin/Obsidian 插件直接集成。
- [x] 文档: 更新了用户手册，补充了缺失的“最大 Worker”性能设置。

$3

- [x] 稳定性修复: 解决了在构建具有大量循环的大型图谱时，Windows 10/11 上发生的关键“堆内存溢出”崩溃问题。
- [x] 算法优化: 更新了 CycleDetector 以限制检测到的循环数量，防止递归期间过度的内存消耗。

$3

- [x] 系统监控: 为后端流程（CPU、内存、时间）实现了全面的性能日志记录。
- [x] GPU 诊断: 为 GPU 加速步骤添加了执行计时和内存跟踪。
- [x] 崩溃报告: 实现了 CrashLogger，自动将未处理的异常和 Worker 故障记录到 crash.log，以便调试 Windows 11 上的稳定性问题。
- [x] 优化: 将 PerformanceLogger 集成到整个图构建管道（节点初始化、边匹配、推断）中。

$3

- [x] 验证: 确认了使用 AMD Radeon 7900XT 通过 gpu.js 加速图构建的可行性。
- [x] 策略: 验证了数学推断（向量相似度）可以卸载到 GPU，而文本处理仍保留在 CPU 上进行优化。
- [x] 实现: 添加了 amdgpu 模块和 VectorSpaceGPU 类。集成到 GraphBuilder 中，在启用时自动使用 GPU 进行余弦相似度矩阵计算。

$3

- [x] 性能: 通过优化统计分析器算法，修复了处理大数据集 (>10,000 文件) 时关键的“堆内存溢出”崩溃问题。
- [x] 效率: 使用稀疏的、以文件为中心的方法，将共现矩阵计算的复杂度降低了约 30 倍。

$3

- [x] 设置界面: 在设置模态框中添加了“性能” (Performance) 部分，包含用于控制“最大 Worker”的滑块和数字输入框。
- [x] API 集成: “加载”按钮现在会将用户定义的 Worker 限制发送到后端构建流程。
- [x] 持久化: Worker 设置与其他偏好一起保存在 localStorage 中。

$3

- [x] 可配置 Worker: 添加了 'maxWorkers' 配置，允许利用更多 CPU 核心进行图构建和统计推断。移除了 12 个 Worker 的硬编码限制。

$3

- [x] 沉浸式专注: 专注模式期间，主控制面板和源选择栏现在完全隐藏，以提供无干扰的体验。
- [x] Canvas 打磨: 移除了 Canvas 专注模式下的边渲染，以减少视觉噪音。

$3

- [x] Canvas 交互: Canvas 模式现在支持悬停 (高亮)、单击 (统计) 和双击 (专注模式) 交互，与 SVG 功能对齐。
- [x] 视觉修复: 修复了 Canvas 模式下节点渲染过大的问题；现在它们遵循“大小依据”设置。
- [x] 清理: 移除了已弃用的“视图模式” (聚类) 功能。

$3

- [x] 智能间距: “层间距”和“节点间距”设置现在针对“水平”和“垂直”专注布局独立保存。
- [x] 优化默认值: 将默认水平层间距减少 50%，垂直节点间距减少 75%，以获得更紧凑、更易读的布局。

$3

- [x] 动态标签: 设置中的“排斥力强度”标签现在会在“排斥力 (力导向)”和“排斥力 (DAG)”之间动态变化，以清晰指示正在修改哪种布局配置。

$3

- [x] 特定模式物理: “排斥力强度”现在可以针对“力导向”和“DAG”模式独立配置。
- [x] 智能默认值: 将力导向布局（聚类）的默认排斥力设置为 -550，DAG 布局（层级）设置为 -850，以优化初始视觉分离。
- [x] 上下文感知设置: 设置模态框会自动显示当前布局的排斥力数值。

$3

- [x] 资源节省: 打开“可视化设置”模态框时，模拟现在会自动暂停，从而减少配置期间的 CPU 使用率。关闭时会自动恢复，除非全局启用了“冻结布局”。

$3

- [x] 设置隔离: 如果布局已冻结，在“可视化设置”模态框中调整参数（例如排斥力、透明度）不再触发模拟重启。视觉更改立即生效，而物理更新等待解冻。

$3

- [x] 一致过渡: 切换布局现在会触发与初始加载相同的“快速松弛”（0.2 阻尼持续 2 秒），确保节点快速排列。
- [x] 智能冻结: 如果在切换期间激活了“冻结布局”，模拟将运行 2 秒的松弛期以建立新结构，然后自动冻结。

$3

- [x] 富文本支持: 修复了本地化 UI 中的 HTML 标签（例如粗体文本、换行符）显示为原始文本的问题。系统现在可以正确渲染翻译中的 HTML 格式。

$3

- [x] 智能阻尼: 模拟现在以低摩擦 (0.2) 启动 2 秒，以允许节点快速解开（“松弛”），然后自动增加到高摩擦 (0.95) 以保持稳定。

$3

- [x] 严格冻结: 如果“冻结布局”处于激活状态，更改“度数基准”或“大小依据”设置不再唤醒模拟。视觉效果更新（节点大小改变），而位置严格锁定。

$3

- [x] 平滑剔除: 将屏幕外“活动”缓冲区增加到 800px (视觉)，防止边缘附近的节点在平移期间突然冻结。
- [x] 扩展缩放: 将全局模拟冻结阈值从 0.4x 降低到 0.1x，允许物理模拟在大幅缩小时继续运行。

$3

- [x] 布局转换逻辑: 实现了布局切换期间的全局解冻机制。
- [x] 覆盖剔除: 切换布局（例如从 Force 到 DAG）现在会强制清除视口剔除锁定（isCulled，fx，fy），确保所有节点（包括屏幕外的节点）都能正确参与新的布局排列。

$3

- [x] 模板状态: 为“Force”和“DAG”布局实现了独立的状态缓存。
- [x] 即时切换: 切换布局现在会保存当前状态并立即恢复目标状态，无需重新计算或视觉移动，从而保留每个视图的精确排列。

$3

- [x] 阻尼: 将默认摩擦力增加到 0.92 以加快稳定速度。
- [x] 渲染剔除: 跳过屏幕外冻结节点的 DOM 更新。

$3

- [x] 性能: 实现了智能视口剔除以减少模拟负载。
- [x] 全景冻结: 当缩小到查看整个图表 (< 0.4x) 时自动冻结模拟。
- [x] 屏幕外冻结: 放大时，仅模拟可见视口（加上缓冲区）内的节点；屏幕外的节点被冻结。

$3

- [x] 位置一致性: 为专注模式实现了坐标备份/恢复逻辑 (x, y, fx, fy)。
- [x] 行为: 退出专注模式现在会将图表布局恢复到进入前的精确状态，丢弃专注会话期间所做的任何临时排列或拖动。
- [x] UX: 满足了专注模式应对主界面布局结构零影响的要求。

$3

- [x] Bug 修复: 解决了打开分析面板或调整窗口大小时会覆盖“冻结布局”状态，导致节点意外移动的问题。
- [x] 稳健性: 物理模拟现在在布局变更期间严格遵守冻结状态，确保节点按预期保持静止。

$3

- [x] 逻辑修正: 解决了“退出专注模式”会无条件重启物理模拟，覆盖“冻结布局”状态的冲突。
- [x] 优先级执行: 如果选中了“冻结布局”，退出专注模式现在会停止模拟并强制进行静态渲染更新，确保节点按请求保持严格静止。

$3

- [x] 冻结布局快速按钮: 在主界面添加了专用的冻结按钮 (❄️) 以便即时访问，提高了移动端可用性。
- [x] 同步: 状态与模拟面板复选框同步。
- [x] 视觉: 冻结时按钮变红。
- [x] 快速开始指南: 为新用户实现了“快速开始指南”模态框。
- [x] 内容: 涵盖加载、导航、专注模式和控制。
- [x] 引导: 首次访问时自动显示（除非选中“不再显示”）。
- [x] 访问: 可通过新的“帮助” (❓) 按钮随时访问。
- [x] 本地化: 全面本地化了新的 UI 元素（中/英）。

$3

- [x] 资源优化: 在主界面（SVG 模式）中，启用“冻结布局”现在除了停止模拟外，还会完全禁用节点拖动。
- [x] 逻辑: 防止因拖动事件而重启（唤醒）物理模拟，从而确保最大限度地节省 CPU/内存。
- [x] 专注模式保留: 专注模式下的拖动和手动定位功能保持完全激活，不受全局冻结设置的影响。

$3

- [x] 专注模式重新进入: 修复了在专注模式下双击相关节点时无法正确刷新的问题。现在可以在连接的节点之间无缝切换专注。
- [x] 可拖动弹窗: 节点统计弹窗现在可以通过标题栏拖动到屏幕上的任何位置，以便更好地组织工作区。
- [x] 可缩放弹窗: 添加了缩放控制 (+/−/⟲)，可将弹窗内容从 0.5x 缩放到 2.0x，以提高可读性。
- [x] 可调整大小弹窗: 启用了浏览器原生调整大小手柄，用于手动调整弹窗大小。
- [x] 状态管理: 改进了节点可见性标志重置，以防止切换专注上下文时出现累积问题。

$3

- [x] 模块化架构: 创建了专用的 NodeHighlightManager` 类，实现高亮逻辑的清晰分离。
- [x] 统一接口: 为 PC（悬停）和移动端（点击）交互提供单一 API。
- [x] 状态管理: 正确跟踪高亮/冻结状态，并具备专注模式感知能力。
- [x] 增强渲染: SVG 和 Canvas 模式之间的一致视觉行为。
- [x] 双语文档: 整个代码库中全面的中英文注释。
- [x] 稳健集成: 与现有的专注模式、分析面板和统计弹窗功能完全兼容。

$3

- [x] 彩色箭头: SVG 边现在在高亮时使用红色和蓝色箭头，确保整个连接颜色编码一致。

$3

- [x] 完整上下文: 点击或悬停节点现在会显示所有连接 (入度和出度)，无论当前过滤器模式如何。
- [x] Canvas 打磨: 为 Canvas 渲染器中的高亮边添加了加粗样式。

$3

- [x] 边高亮: 修复了 SVG 模式下边颜色（红/蓝）和加粗样式未正确应用的问题。
- [x] 数据去重: 确保统计弹窗中的邻居列表不包含重复条目。

$3

- [x] 交互约束: 确保在专注模式处于激活状态时，严格禁用浮动统计弹窗和相关高亮显示，以防止上下文冲突。

$3

$3

- [x] 检查: 点击节点现在会冻结整个模拟，以便稳定地检查连接。
- [x] 恢复: 点击背景会恢复模拟（如果未手动冻结）。

$3

- [x] 移动端适配: 实现了滑动（上/下）手势以调整分析面板大小、全屏拖动吸附以及移动端拖动手柄。
- [x] 交互: 验证了分析面板与图表之间的节点点击同步。

$3

- [x] 图表同步: 点击表格行现在会高亮显示图表中的节点。
- [x] 移动端 UX: 修复了分析面板中的移动端滚动问题。

$3

- [x] 专注模式: 修复了切换布局类型不会触发立即刷新的 Bug。

$3

- [x] 分析面板: 添加了 "全屏" 切换和 "捏合缩放" 以提高移动端可读性。
- [x] 视觉效果: 修复了 Mermaid 缩放文本样式；添加了背景点击以清除高亮。

$3

- [x] 专注模式: 添加了 "层级 (从左到右)" 布局和语义标签 ("Helping to understand" / "Further exploration")。
- [x] 分析面板: 针对移动端优化（可滚动），并添加了与主图的点击高亮交互。
- [x] 视觉效果: 增强了 Mermaid 图表在浅色背景下的文本可见性；修复了专注模式居中问题。

$3

- [x] 响应式控件: 主面板在移动端折叠；专注 UI 移至底部。
- [x] 触摸缩放: 阅读窗口添加了捏合缩放支持。

$3

- [x] 悬停锁定: 悬停节点时锁定其位置，防止检查时漂移。
- [x] 模拟控制: 添加了 冻结布局 复选框和 速度/阻尼 滑块。

$3

- [x] 选中冻结: 专注模式下的节点在交互后保留其位置。

$3

- [x] 减少杂乱: 默认隐藏边和孤立节点。
- [x] 水平间距: 专注模式下新增水平节点分隔滑块。

$3

- [x] Canvas 渲染器: 添加 HTML5 Canvas 支持以实现高性能。
- [x] Worker 扩展: 将线程限制增加到 12。