2026-04-07 v1.7.0

NoteConnection Knowledge Graph

Legacy Navigation Row (from shared bilingual table)

| English | Key Features | Hardware | Architecture | Quick Start | CLI | Changelog | | :---------: | :------------------------------: | :----------------------: | :------------------------------: | :----------------------------: | :------------: | :------------------------: | | 中文 | 核心特性 | 硬件配置 | 系统架构 | 快速开始 | CLI | 更新日志 |

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.

Current Mainline Architecture Status (2026-07-03)

English

• The Mermaid fallback failure class reported through the Node-side renderer is now closed at the correct owners: src/notemd/MermaidProcessor.ts and src/reader_renderer.ts both normalize malformed quoted bracketed-node labels per line before parse/render. PathBridge remains transport-only.
• Guided Learning no longer pays repeated full hosted Graph / PathEngine reconstruction for the same graph snapshot. src/frontend/workspace_panes.js now reuses the hosted Future Path runtime by source-graph signature while keeping the pending-pane behavior in src/frontend/agent_workspace.js.
• Hosted Future Path runtime reuse now has a narrower owner: src/frontend/hosted_future_path_runtime.js holds signature-based cache identity plus cold/hot-path diagnostics, and workspace_panes.js now consumes that owner instead of holding the cache logic inline.
• Guided Learning first-open behavior is now two-stage: when local graph state is already available, the pending pane can render an immediate hosted Future Path projection before /api/knowledge/path returns, and identical in-flight Learning Path requests are deduped by normalized payload.
• Knowledge Workspace public answers now consume bounded DAG context on the main answer path instead of collapsing to only the first top-hit sentence. src/learning/graphContextAssembler.ts now emits anchorGraphProfile, and conversationComposer.ts plus answerReleaseReview.ts use bounded path and degree context while keeping the public answer contracted.
• The local design references under ref/enterprise_agent_platform and ref/codex now reinforce the current owner split: runtime/retrieval/memory/release-review stay local, and model-visible context stays bounded and additive.
• Compared with the 2026-05-25 through 2026-06-18 plan chain, the missing gap is no longer whether DAG context reaches the public answer path. The remaining gap is calibration and architecture concentration inside a few oversized owners.
• Current architecture pressure is still concentrated in src/server.ts (~15850 lines), src/learning/KnowledgeLearningPlatform.ts (~11200), src/frontend/workspace_panes.js (~9289), src/frontend/agent_workspace.js (~4882), and src/learning/answerReleaseReview.ts (~4261). The next step is narrower extraction around real invariants, not another framework import pass.
• Current code-vs-plan details are tracked in Agent Knowledge Workspace Graph Preview and Review Closure (2026-06-20) and the Development Progress Dashboard.

中文

• 通过 Node 侧 renderer 暴露出来的 Mermaid 回退失败类现在已经在正确 owner 处关闭：src/notemd/MermaidProcessor.ts 与 src/reader_renderer.ts 现在都会在解析/渲染前按行归一化畸形带引号 bracketed-node label；PathBridge 继续只做 transport。
• Guided Learning 对同一图快照不再重复支付完整托管 Graph / PathEngine 重建成本。src/frontend/workspace_panes.js 现在会按 source-graph signature 复用 hosted Future Path runtime，同时保留 src/frontend/agent_workspace.js 中已有的 pending-pane 行为。
• Hosted Future Path runtime 复用现在也有了更窄的 owner：src/frontend/hosted_future_path_runtime.js 持有按签名复用的 cache identity 与冷/热路径诊断，workspace_panes.js 不再内联持有整套 cache 逻辑。
• Guided Learning 首开现在也变成了两阶段行为：只要本地图状态已可用，pending pane 就能在 /api/knowledge/path 返回前先渲染 hosted Future Path 投影，而且相同的在途 Learning Path 请求会按归一化 payload 去重。
• Knowledge Workspace 的公开回答现在已经在主回答路径消费有界 DAG context，而不再只退化成首条 top-hit 句子。src/learning/graphContextAssembler.ts 现在会发射 anchorGraphProfile，conversationComposer.ts 与 answerReleaseReview.ts 会在保持回答收缩的前提下使用 bounded path / degree context。
• 本地 ref/enterprise_agent_platform 与 ref/codex 设计参考现在进一步支撑当前 owner 切分：runtime / retrieval / memory / release-review 继续留在本地运行时，model-visible context 继续保持 bounded + additive。
• 相对 2026-05-25 到 2026-06-18 的方案链，当前缺口已经不再是“DAG context 有没有真正进入公开回答路径”。剩余缺口主要是回答校准，以及少数大 owner 内的架构集中度。
• 当前架构压力仍集中在 src/server.ts（约 15850 行）、src/learning/KnowledgeLearningPlatform.ts（约 11200 行）、src/frontend/workspace_panes.js（约 9289 行）、src/frontend/agent_workspace.js（约 4882 行）与 src/learning/answerReleaseReview.ts（约 4261 行）。下一步应该围绕真实不变量做窄提取，而不是再做一轮框架导入。
• 当前代码 / 方案对齐详情见 Agent 知识工作区图预览与回答审核收口（2026-06-20） 与 开发进度看板。

Current Mainline Architecture Status (2026-06-24)

English

• The Agent Knowledge Workspace closure now combines three mainline owners: bounded DAG context assembly, deterministic final-answer release review, and right-pane graph/source projections.
• Public answers remain contracted to the reviewed answer path; citations, graph context, reviewer details, provenance diagnostics, and developer traces belong to secondary panes, artifacts, traces, or exports.
• Matched-file discoverability is now intentionally compact: users get a question-mark help affordance for "left-click opens source and highlights the basis" instead of permanent instructional text in the workspace.
• The matched-file/source-focus path is now right-pane-first: source clicks resolve candidate paths, render Markdown, highlight matched evidence, and expose close controls for the affected right-pane surfaces.
• Related Focus is implemented as a side-pane Focus-mode host backed by the main graph projection contract and the shared double-click decision contract; it switches anchors and opens Markdown inside the pane without moving the main graph DOM or calling the global reader, and the hosted view intentionally omits the main toolbar frame, visible edge layer, and dense background context dots. Learning Path hosts the Godot Future Path diffusion/core/treeLayout contract, inherits matching Path-mode expansion/collapse/completion state when the live target matches, and routes DOM input through TreeRenderer-style spine-only signals, including right-click prerequisite collapse for the selected node.
• The hosted Related Focus viewport now has pane-local wheel zoom, icon reset, and icon focus-history controls; these controls are intentionally scoped to the right-side Knowledge Focus pane and do not mutate the Tauri main graph runtime.
• The hosted Learning Path Future Path surface now routes node double-click to the same pane-local Markdown reader used by Knowledge Focus, so opening concrete node text stays inside the Guided Learning pane instead of delegating to the global reader.
• The current implementation uses resolved graph labels such as water glass, not internal atom IDs, for the knowledge graph preview surface. This behavior is pinned by strict browser verification.
• Current code-vs-plan details are tracked in Agent Knowledge Workspace Graph Preview and Review Closure (2026-06-20) and the Development Progress Dashboard.

中文

• Agent Knowledge Workspace 本轮收口现在合并了三类主线 owner：有界 DAG context assembly、确定性最终回答 release review，以及右侧 graph/source projection。
• 公开回答继续收缩到经过审核的回答路径；citation、graph context、reviewer detail、provenance diagnostics 与 developer trace 进入次级 pane、artifact、trace 或 export。
• 命中文件可发现性现在刻意保持克制：用户通过问号帮助入口了解“左键打开源文档并高亮依据”，而不是在 workspace 中常驻说明文案。
• 命中文件 / source-focus 路径现在以右侧 pane 为权威阅读面：单击后解析候选路径、渲染 Markdown、高亮命中依据，并在受影响的右侧 pane surface 上提供关闭控件。
• 关联聚焦 已实现为右侧 pane 内托管的 Focus-mode：复用主图投影契约与共享双击决策契约，在 pane 内切换 anchor 或打开 Markdown，不移动主图 DOM，也不调用全局 reader；托管视图刻意不显示主界面的工具框、可见边线与密集灰色背景 context 点。学习路径 托管 Godot Future Path 的 diffusion/core/treeLayout 契约；当主 Path mode 当前 target 匹配时，会继承其 expansion/collapse/completion 状态包，并将 DOM 输入路由为 TreeRenderer 风格的 spine-only 信号，包括对选中主干节点的右键 prerequisite 收起。
• 托管 关联聚焦 viewport 现在具备 pane-local 滚轮缩放、图标式 reset 与图标式 focus history 控件；这些控制只作用于右侧知识聚焦 pane，不会修改 Tauri 主图运行时。
• 托管 学习路径 Future Path surface 现在把节点双击路由到与知识聚焦相同的 pane-local Markdown reader，因此打开具体节点文本会留在引导式学习 pane 内，而不是委托给全局 reader。
• 当前实现使用 water glass 这类解析后的图标签，而不是内部 atom ID，作为知识图预览展示名称；该行为已由 strict browser verification 固定。
• 当前代码 / 方案对齐详情见 Agent 知识工作区图预览与回答审核收口（2026-06-20） 与 开发进度看板。

Current Mainline Architecture Status (2026-06-17)

English

• The current DAG clarification is now explicit: "graph structure" means this project's existing DAG-shaped KnowledgeAtom / RelationEdge / TemporalEdge substrate, not a generic graph database integration target.
• The 2026-06-17 agent-knowledge slice now includes a first-class graph-conditioned context assembly step: src/learning/graphContextAssembler.ts selects the anchor, reorders support nodes, attaches explicit store-backed connectionPaths, builds bounded predecessor/successor windows, records evidence refs/diagnostics, and still preserves legacy assistantMessage compatibility.
• Persistence is guarded for this slice: before auto-saving a rebuilt learning snapshot, KnowledgeLearningPlatform merges still-valid store-side relation/temporal edges into the new snapshot so read-side query/conversation flows do not erase externally enriched DAG edges before path enrichment can inspect them.
• The next architecture move is no longer extracting the assembler itself; it is expanding graph-aware ranking features beyond relation-degree bonuses, hardening right-pane diagnostics, and adding graph-specific quality gates on top of the new bounded context pack.
• The public answer contract is now enforced in the current composer path: answer / directAnswer stays to the targeted response, while citations, connection paths, temporal details, durable artifacts, and developer traces belong in the evidence pane or export payload unless the user explicitly asks to inspect them.
• The prior DSPy / Guidance / Semantic Kernel / LangChain Core / LiteLLM review is retained as design input only. The main runtime should stay TypeScript-native and use local graph store operations instead of importing Python prompt frameworks into the Tauri/Node path.
• Current code-vs-plan details are tracked in Agent Knowledge DAG Answer Contract Plan (2026-06-17), Knowledge Workspace and DAG Alignment Plan (2026-06-10), and the Development Progress Dashboard.

中文

• 当前已明确：这里的“图结构”指本项目现有 DAG 形态的 KnowledgeAtom / RelationEdge / TemporalEdge 底座，不是泛化的图数据库接入目标。
• 2026-06-17 agent knowledge 切片现在已经包含一等 graph-conditioned context assembly 步骤：src/learning/graphContextAssembler.ts 会在回答合成前选择 anchor、重排 support node、挂接 store 支撑的显式 connectionPaths、构建有界 predecessor/successor window，并记录 evidence ref / diagnostics，同时保持 legacy assistantMessage 兼容。
• 当前切片也补了持久化保护：KnowledgeLearningPlatform 在自动保存重建后的 learning snapshot 前，会把仍然有效的 store 侧 relation/temporal edges 合并回新快照，避免 read-side query/conversation 流程在路径增强读取前抹掉外部增强的 DAG 边。
• 下一步正确的架构动作已经不再是“把 assembler 抽出来”，而是基于新的 bounded context pack 继续扩展 graph-aware ranking feature、右侧原文诊断以及图专项质量门禁。
• 公开回答契约已在当前 composer 路径中强制收缩：answer / directAnswer 只保留 targeted response；citation、connection path、temporal detail、durable artifact 与 developer trace 默认进入 evidence pane 或 export payload，除非用户显式要求查看。
• 先前对 DSPy / Guidance / Semantic Kernel / LangChain Core / LiteLLM 的研究继续作为设计输入，不作为运行时依赖引入。主运行时应保持 TypeScript-native，并优先使用本地图 store operations。
• 当前代码 / 方案对齐详情见 Agent Knowledge DAG Answer Contract Plan (2026-06-17)、Knowledge Workspace and DAG Alignment Plan (2026-06-10) 与 Development Progress Dashboard。

Current Mainline Architecture Status (2026-06-10)

• The current main branch has code-backed scoped retrieval, grounded conversation, durable resource/index/workspace/session/memory/export substrate, explicit export profiles, and PNG-first Godot/mobile render materialization.
• The Knowledge Workspace now includes an in-pane scope switcher, a compact /api/knowledge/conversation status strip, grouped file-first knowledge hits, source-markdown rendering with matched-span highlighting in the focus pane, and durable workflow artifacts for flashcard_batch and knowledge_run.
• Agent conversation runtime is no longer limited to one flat string: answer, assistantBlocks, knowledgeRun, grouped knowledge points, citations, memory actions, and trace are all present while legacy assistantMessage remains valid.
• The current DAG-backed learning substrate is real: KnowledgeAtom, RelationEdge, TemporalEdge, path queries, mastery-path/session logic, and KnowledgeQueryItem.relationPath already exist. The remaining gap is not “having a graph,” but letting answer planning consume it through a dedicated graph-conditioned context layer.
• graphdb/sqlite and ANN/external connector paths remain operational baselines, not production-closed claims. Release closure still depends on repeated soak evidence, workload thresholds, recall/latency calibration, strict rollout proof, and multi-host evidence.
• npm run verify:foundation:release-evidence audits the latest sqlite soak and ANN release-gate reports for freshness and passing gates before host evidence is used as release context; npm run verify:foundation:release-evidence:strict requires repeated fresh valid history and is exposed in foundation readiness as foundation_release_evidence_history; npm run verify:foundation:release-evidence:multi-host is available for release windows that require host diversity.
• The current architecture pressure remains ownership reduction: src/server.ts, src/learning/KnowledgeLearningPlatform.ts, src/frontend/agent_workspace.js, and src/frontend/workspace_panes.js remain the main simplification targets.
• Current code-vs-plan details are tracked in Knowledge Workspace and DAG Alignment Plan (2026-06-10), Architecture Progress Alignment and Mainline Plan (2026-06-06), and the Development Progress Dashboard.

🚀 Key Features

1. Visualization & Layout

• 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.

2. Intelligence & Inference

• 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. Path Mode: Structured Learning (v1.2.0)

• 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.

4. Performance & Control

• 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

Supported AMDGPU Architectures

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.

Driver Configuration

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.

Backend (src/backend)

• 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.

Frontend (src/frontend)

• 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.

Desktop Bridge (src/core)

• 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

Desktop System Dependencies

| Platform | Required Dependencies | |---|---| | Linux | libwebkit2gtk-4.1-dev, libgtk-3-dev, libsoup3.0, libjavascriptcoregtk-4.1-0 (Ubuntu/Debian: sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libsoup-3.0-dev patchelf) | | macOS | No additional dependencies (system WebKit included) | | Windows | Edge WebView2 Runtime (pre-installed on Windows 11; Windows 10 may need manual install) |

Linux Wayland users: Godot Path Mode requires GDK_BACKEND=x11 on pure Wayland compositors. The launcher sets this automatically when XDG_SESSION_TYPE=wayland is detected.

Option 1: Windows Installer (Recommended)

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

Option 2: Run with npx

No installation required.

npx noteconnection

Option 3: Global Installation

npm install -g noteconnection
noteconnection

Option 4: Local Development

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

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

Option 5: Mobile Support (Android)

NoteConnection supports Android via Tauri Android (native shell pipeline). The Capacitor APK path is deprecated and retained for historical reference only.

Prerequisites

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

Recommended: Tauri Android Build (Native Shell)

# First-time setup
npm run tauri:android:init

# Development build
npm run tauri:android:dev

# Release APK/AAB
npm run tauri:android:build

For universal APK (armeabi-v7a + arm64-v8a + x86_64):

npm run tauri:android:build:universal

Deprecated: Capacitor Build

The Capacitor APK path (build_apk.bat, npm run mobile:build:capacitor) is deprecated as of 2026-05. The android/ Capacitor project directory is retained for historical reference. All active Android development targets the Tauri Android pipeline.

First-time setup on the machine

npm run tauri:android:init

Build APK/AAB through Tauri Android pipeline

npm run tauri:android:build

#### Method C: Capacitor 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`

#### Mobile Capability Boundary

- Capacitor packaging path does not embed the desktop Node sidecar workflow, but native Capacitor runtime can still build graph payloads locally when Filesystem APIs are available and the dataset stays within mobile limits.
- Tauri Android path provides the native-shell runtime route and uses Android-native `build_graph_runtime` when mobile-side parity with the Tauri architecture is required.

### 3. Usage Guide

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.

<a id="cli-en"></a>

## 🖥️ 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.

### Usage

```bash
npm start -- --path "<path_to_knowledge_base>" [options]

Options

| 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 |

Example

# 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 (app_config.toml): Your KB path, language, and multi-window preferences are saved in %LOCALAPPDATA%/NoteConnection/app_config.toml (Windows default) and remembered across restarts.
• Legacy Auto-Migration: If a legacy kb_config.json exists in the same config directory, NoteConnection automatically migrates it to app_config.toml.
• 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.
• Config Path Overrides: Set NOTE_CONNECTION_CONFIG_PATH (full file path) or NOTE_CONNECTION_CONFIG_DIR (directory) to customize where app_config.toml is stored.
• Window Behavior Tuning: Edit [multi_window] in app_config.toml (single_window_mode, hide_tauri_when_pathmode_opens, restore_tauri_when_pathmode_exits, confirm_before_full_shutdown_from_godot, sync_language).
• Reader Protocol Tuning: Edit [frontend_settings.reading] to control markdown rendering runtime (markdown_engine, chunk_block_size, prefetch_blocks, index_cache_ttl_sec, max_doc_bytes).
• Detailed Config Guide: See docs/en/app_config.toml_guide.md and template docs/examples/app_config.template.toml.

# Minimal recommended app_config.toml
knowledge_base_path = "E:/Knowledge_project/NoteConnection_app/Knowledge_Base"
user_language = "en"

[multi_window]
single_window_mode = true
hide_tauri_when_pathmode_opens = true
restore_tauri_when_pathmode_exits = true
confirm_before_full_shutdown_from_godot = true
sync_language = true

[frontend_settings.reading]
mode = "window"
markdown_engine = "auto" # "legacy" | "pulldown" | "auto"
chunk_block_size = 36
prefetch_blocks = 8
index_cache_ttl_sec = 1800
max_doc_bytes = 100663296

Markdown Reader Protocol (v1.6.8)

• Dual-engine gray release:
  • markdown_engine = "auto": prefer pulldown-cmark, fallback to legacy on failure.
  • markdown_engine = "pulldown": keep automatic fallback to legacy to avoid blank readers.
  • markdown_engine = "legacy": force original parser path.
• Unified cross-window behavior: Tauri reader and Godot reader now both consume the same sidecar markdown protocol (index/chunk/resolve-node/resolve-wiki).
• Large file stability: reader no longer requires single-shot full markdown payloads and supports block-based incremental loading.
• Mermaid reliability hardening:
  • Godot reader Mermaid rendering now uses renderer = "auto" so it can prefer frontend bridge and automatically fallback to local resvg when bridge render is unavailable.
  • Mermaid fences must start on a new line; inline $$```mermaid patterns can break block classification.
  • Use npm run verify:markdown:mermaid:fence -- Knowledge_Base/testconcept to catch malformed inline Mermaid fences before release.
• Local MCP web-debug baseline (Runbrowser):
  • Build locally from source: pnpm --filter @jiweiyuan/runbrowser-server build, pnpm --filter @jiweiyuan/runbrowser-core build, pnpm --filter @jiweiyuan/runbrowser-mcp build.
  • Run local MCP entrypoint: node E:\Knowledge_project\tools\runbrowser\packages\mcp\bin.js.

🏗️ Build & Deployment

For developers building from source, NoteConnection now defaults to the runtime-first path:

• Electron desktop pipeline was removed on 2026-03-01 (deprecated and decommissioned).

• Tauri Build (npm run tauri:build): Default desktop package path. Uses runtime-first assets and excludes pre-generated graph payloads.

• Tauri Mini Build (npm run tauri:build:mini): Legacy-compatible alias of the same runtime-first packaging path.

• Tauri Full Graph Build (npm run tauri:build:full): Explicit opt-in path for including generated graph assets when real files are present locally.

• Build (npm run build): Default runtime-first frontend build.

• Build Full Graph Assets (npm run build:full): Explicit opt-in frontend build for local/demo scenarios that need pre-generated graph assets.

• Godot Bootstrap (npm run prepare:godot:bin): materializes the host Godot sidecar from local overrides/search paths, cache, or a pinned download URL.

• Desktop Release Godot Mirror: release CI now seeds a project-controlled GitHub Releases mirror tag for Godot archives, then downloads mirror-first with upstream fallback.

• LFS Policy Guard (npm run verify:lfs:policy): blocks new Git LFS drift under src/frontend/ and src-tauri/bin/ while migration still carries legacy exemptions. Future strict mode is available via npm run verify:lfs:policy:strict.

• Sidecar Supply Readiness (npm run verify:sidecar:supply): reports whether the current desktop host is offline-ready or still network-dependent before shrinking the remaining sidecar LFS bridge.

• GPU Dev Start (npm run tauri:dev:mini:gpu): Recommended GPU-enabled Tauri development command.

• Do not use npm run tauri:dev:mini --gpu because npm treats --gpu as config and prints warnings.

📚 Documentation Architecture (Diataxis + MkDocs)

• Canonical long-form docs remain under docs/en/* and docs/zh/*.
• Diataxis navigation pages are maintained under docs/diataxis/<lang>/*.
• Mapping governance is versioned in docs/diataxis-map.json.
• Run mapping validation: npm run docs:diataxis:check.
• Run local docs site preview: npm run docs:site:serve.
• Build static docs site: npm run docs:site:build.
• GitHub Pages Docs Portal (project site): https://jacobinwwey.github.io/NoteConnection/.
• Host root (for routing baseline): https://jacobinwwey.github.io/.
• Recommended lookup entry points:
  • Users: /diataxis/zh/tutorials/first-run/ or /diataxis/en/tutorials/first-run/
  • Developers: /diataxis/en/reference/interfaces-and-runtime/ and /diataxis/en/reference/release-and-governance/
  • Maintainers assessing LFS / desktop bootstrap risk: /en/sidecar_supply_strategy/ or /zh/sidecar_supply_strategy/
  • Maintainers comparing mirror cost / user friction / maintenance burden: /diataxis/en/explanation/sidecar-supply-feasibility/ or /diataxis/zh/explanation/sidecar-supply-feasibility/
• CI auto publish workflow (GitHub Pages): .github/workflows/docs-github-pages-publish.yml.
• Manual rollback entry: run workflow dispatch and set git_ref to a stable tag/commit.
• MkDocs base/path can be overridden by environment variables: MKDOCS_SITE_URL, MKDOCS_BASE_PATH.
• CI policy gate for docs mapping and site build: .github/workflows/docs-diataxis-site.yml.
• Docs release + rollback runbook:
  • English: docs/en/docs_release_and_rollback.md
  • 中文: docs/zh/docs_release_and_rollback.md

🛠️ 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

v1.7.0 - Startup Acceleration Closure, Multi-Platform Validation, and Learning Roadmap Foundation (2026-03-31)

• Tag Compare Snapshot (v1.6.0..v1.7.0):
  • 47 commits, 160 files changed, +20,224 / -1,444 churn.
  • Engineering footprint concentrated in: src/frontend/, scripts/, docs/, src-tauri/, package*.json.
• Startup Runtime Optimization Closure (Phase 2/3/4 + v1.1 Hardening):
  • Added startup delta tick transport (tickMode: full|delta) with low-alpha adaptive controls (lowAlphaDeltaEpsilonMultiplier, lowAlphaFullSyncEveryTicks).
  • Added frame-coalesced startup tick application on main thread to reduce redundant repaint pressure near stable phase.
  • Hardened warm-start recovery with strict snapshot validation (fingerprint, age, node/edge consistency, position coverage threshold).
  • Expanded startup telemetry at T5 stable_layout with tickSummary (fullTicks, deltaTicks, deltaRatio, payload and frame metrics).
• Cross-Platform Startup Validation Toolchain:
  • Added/extended compare + matrix + watch + simulate + cohorts + signoff automation scripts for startup KPI governance.
  • Introduced no-hardware engineering signoff flow (Windows real logs + simulated cohorts) while preserving release-grade requirement for real multi-device cohorts.
• Runtime Contract and Documentation Alignment:
  • Synced Diataxis EN/ZH runtime references with the new startup profile fields and telemetry semantics.
  • Extended startup acceleration plan docs with v1.1 optimization and risk-guardrail closure details.
  • Added bilingual knowledge-mastery evolution roadmap docs and integrated them into Diataxis navigation and mapping.
• Version Metadata Alignment:
  • Unified release metadata to 1.7.0 in package.json, package-lock.json, and src-tauri/tauri.conf.json.

v1.6.7 - Docs Governance Cleanup & GitHub Pages Stabilization (2026-03-29)

• Removed unrelated external community UI documentation references from the repository documentation system.
• Replaced legacy external runbooks with project-owned docs operations runbooks:
  • docs/en/docs_release_and_rollback.md
  • docs/zh/docs_release_and_rollback.md
• Updated Diataxis governance mapping and cross-links to use the new canonical runbook paths.
• Added GitHub Pages preflight verification in docs publish workflow to surface clear warnings when Pages is not enabled.
• Resolved docs portal 404 condition by enabling repository Pages with gh-pages branch as publish source.
• Prepared formal release metadata and version alignment to 1.6.7 (npm + Tauri).

v1.6.6 - Unified Provider Runtime & TOML Settings Consolidation (2026-03-26)

• Upgraded NoteMD API calling flow to a definition-driven provider architecture inspired by recent obsidian-NotEMD and cline patterns.
• Added transport-based dispatch (openai-compatible, anthropic, google, azure-openai, ollama) and provider metadata (apiKeyMode, apiTestMode, category).
• Expanded built-in provider presets: Qwen, Doubao, Moonshot, GLM, MiniMax, Groq, Together, Fireworks, Requesty, OpenAI Compatible.
• Unified runtime settings persistence in app_config.toml across Tauri + Godot + NoteMD:
  • full NoteMD settings in [notemd] + [[notemd.providers]] (with legacy [notemd.api] compatibility mirror)
  • Godot Path Mode settings in [path_mode] with runtime API endpoint /api/path-mode/settings
  • Godot settings panel migrated to runtime TOML sync path.
• Hardened Rust-side TOML writes to preserve unknown sections, preventing accidental loss of [notemd] / [path_mode] when Tauri updates KB path or language.
• Updated bilingual documentation and templates for v1.6.6 schema and operations.

v1.6.5 - Documentation Portal Update (2026-03-26)

• Published MkDocs documentation to GitHub Pages project site.
• Added bilingual README guidance for docs lookup paths (user/tutorial and developer/reference entry points).
• Standardized docs publish flow for maintainers:
  • npm run docs:site:build
  • .github/workflows/docs-github-pages-publish.yml (workflow_dispatch supports git_ref rollback)

v1.6.0 - Unified Runtime, NoteMD Integration & Release Hardening (2026-03-23)

• Tag Compare Snapshot (v1.3.0..v1.6.0):

  • 107 commits, 301 files changed, +125,957 / -10,083 churn.
  • File-level status: 241 added, 56 modified, 3 deleted, 1 renamed.
  • Largest engineering footprint: src/, docs/, scripts/, path_mode/, src-tauri/.

• Single-Window Runtime Orchestration:

  • Implemented Tauri <-> Godot visibility handoff so only one primary window is shown at a time.
  • Added Godot close-confirm flow ("Return to main interface" vs "Close all windows") to prevent accidental full shutdown.
  • Stabilized Godot window visibility control and removed deprecated foreground APIs.

• NoteMD Embedded Experience:

  • Kept NoteMD as an embedded experience (not a standalone desktop window) aligned with both Tauri and Godot flows.
  • Fixed non-responsive Browse actions in Tauri NoteMD (file/folder/save pickers now complete the IPC flow).
  • Defaulted embedded NoteMD to a single One-Click Extract workflow that chains concept extraction, batch generation from titles, and batch Mermaid repair into a source-file-named KB folder.
  • Moved embedded NoteMD API configuration into app_config.toml under [notemd] and [notemd.api], with matching fields in the embedded NoteMD window.
  • Added noteconnection notemd ... CLI entrypoints for shared NoteMD actions.
  • Added user guidance that PDF files must be converted to Markdown via Mineru before import.

• Platform & Toolchain Release Readiness:

  • Standardized Java policy to JDK 21+ and verified support for JDK 23.0.1 in Android prerequisites/build tooling.
  • Added Android/Tauri patching and verification scripts for prerequisite checks, sidecar validation, and strict evidence gates.

• Reliability & Security Gates:

  • Expanded CI/workflow coverage for FixRisk operational readiness, mobile e2e contracts, wasm parity, SBOM, attestation, and signature/privacy checks.
  • Added broad contract-level regression coverage across mobile/runtime/pathbridge/storage layers.
  • Included pre-release CI compatibility fixes for runtime bridge invoke-contract assertions and unsigned SBOM transparency policy handling.

• Build Performance & Developer Experience:

  • Added low-memory Tauri build wrappers and release-profile safeguards for constrained environments.
  • Added sidecar readiness preflight to skip redundant rebuilds during dev startup, reducing warm tauri:dev:mini:gpu startup latency.

v1.5.58 - Godot Path UI Enhancements (2026-03-19)

• Visuals: Added Vertical/Horizontal main spine layout toggle and premium aesthetic color schemes (Nord, Tokyo Night, etc).
• Interactions: Upgraded hover info box with deep node interactivity (Left/Double/Right click).

v1.5.x Migration Runtime Logs (Canonical Archive)

• Full bilingual logs are centrally archived in export.md.
• This README keeps summary pointers in the changelog for readability.
• 2026-03-03 v1.5.10: Option A P0 Status Update (Tauri Android Native Folder/Build/Content Flow)
• 2026-03-03 v1.5.5: Migration Status Revalidation
• 2026-03-03 v1.5.3: Migration Gate Closure Update
• 2026-03-02 v1.5.1: Tauri Migration Progress Update (Desktop + Android)

v1.4.5 - Physically-Based Bubbles & Interactive Physics (2026-03-01)

• Godot Renderer Upgrade:
  • Spectral Bubble Shader: Introduced an advanced 81-wavelength Thin-Film Interference shader (sp_spectral_filter) combined with 3D noise for hyper-realistic iridescent soap bubbles.
  • Interactive Physics: Converted all static bubbles into physically simulated RigidBody3D entities. Bubbles now gently float, bump into each other, and orbit their targets naturally.
  • Environment Cleared: Removed the floor to allow 360-degree floating visualization without ground clipping.
• UI Enhancements:
  • Cancel Completion: The "Mark Complete" button dynamically turns into "Cancel Completion" for already learned nodes, making curriculum management much more forgiving and interactive.

v1.4.4 - Tauri Bridge Stabilization & Cache Workflow Hardening (2026-03-01)

• Electron -> Tauri Runtime Alignment:
  • Path Consistency: Unified runtime path resolution so sidecar graph artifacts are read from bundled frontend assets and written to a writable runtime data directory.
  • Knowledge Base Discovery: Standardized folder listing and loading flow for Knowledge_Base source roots in Bridge-first mode.
• Build/Load Safety:
  • Cache Decision Flow: Restored pre-build decision behavior (Load Existing vs Regenerate) when target cache already exists.
  • Duplicate Request Suppression: Added frontend + backend de-dup guards to prevent repeated restore/build execution on a single load action.
• PathBridge / WebSocket Stability:
  • Client Diagnostics: Added tagged client connect/close logging (id, tag, code, reason) for precise bridge RCA.
  • Godot URL Compatibility: Fixed Godot websocket URL parsing by switching to ws://127.0.0.1:9876/?client=godot.
  • Idle Reconnect Elimination (Tauri): Disabled frontend-early auto-connect in Tauri mode to stop background 1001 reconnect churn.
• Language/Menu Sync Robustness:
  • Idempotent Sync: Added language sync guards in both frontend i18n and Tauri Rust command handlers to avoid repeated no-op menu updates.

v1.4.3 - 9-Rule Tree Layout Engine (2026-02-26)

• Layout Engine Upgrade:
  • Spine & Tributaries Logic: Replaced basic geometric node placement with a robust 9-Rule Topological Layout engine (Expansion Order, Preceding Immunity, Following Migration, Single Appearance, Cross-Tributary Isolation, Spine Always Visible, Sticky Claim, Unit Migration, Tributary Hierarchy Immunity).
  • Node Ownership: Implemented a recursive claiming system where expanding nodes naturally claim their prerequisites (tributaries), arranging them in a visually structured hierarchy.
• Frontend Enhancements:
  • Expansion Tracking: The system now seamlessly tracks node expansion orders, ensuring precise deterministic rendering as complex prerequisite chains are unspooled.
  • Sticky Claims (Configurable): Node ownership persists across view updates, avoiding jarring layout reorganizations during consecutive clicks.
• Godot Renderer Adaptations:
  • Expansion Badges: Added intuitive [+]/[-] badges in the Godot desktop renderer to indicate combinable prerequisite branches visually.
  • Spine Highlighting: Core critical-path nodes ("Spine") receive an elegant glowing border to distinguish the primary learning flow from peripheral branches.

v1.4.1 - Tree View Interaction Fixes (2026-02-01)

• Interaction Polish:
  • Long Press Navigation: Fixed an issue where Long Press (0.6s) on a node would trigger the Context Menu instead of navigating to the node. Now correctly switches the Central Node.
  • Collapse All: Added a dedicated [-] button to the Learning Path header and enabled Middle Click to instantly collapse all expanded nodes.
  • Right-Click Toggle: Fixed a regression where Right-Click would not correctly toggle node expansion states.
  • Lazy Loading UI: Replaced separate (+)/(-) buttons with a unified, state-aware [Count] indicator that toggles visibility of prerequisite chains.

v1.4.0 - Path Mode Learning UX & Tree View (2026-01-30)

• Path Mode Bug Fixes:
  • Unmark Sync Fix: Added unmarkComplete and completionSync handlers to PathBridge.ts.
  • UI Sync on Unmark: Tree panel refresh + central bubble progress update after unmarking.
  • Shader Syntax Fix: Corrected depth_draw_alpha_prepass to depth_prepass_alpha.
• Path Mode Learning UI:
  • Navigation History: Return button with dropdown for learning history.
  • Edit Mode: Toggle to enable/disable unmarking nodes on PC.
  • Tree Panel: Collapsible dependency tree with visual states.
  • Progress Display: "X of N" progress indicator on central bubble.
• Planned: Enhanced Graphical Tree View:
  • SubViewport overlay with bezier curves (mind-map style).
  • 4 visual themes: Colorful (default), Dark, Glass, Minimal.

v1.3.0 - Path Mode Polish & UI Refinements (2026-01-24)

• 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.

v1.2.0 - Path Mode & Desktop Renderer (2026-01-23)

• 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.

v1.1.2 - Path Resolution & UI Stability (2026-01-23)

• 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.

v1.1.1 - Mobile Build Automation (2026-01-22)

• 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.

v1.1.0 - CI/CD Automation (2026-01-22)

• 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.

v1.0.1 - Maintenance & UX Refinement (2026-01-21)

• 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.

v1.0.0 - Production Release (2026-01-14)

• 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.

v0.9.83 (2026-01-13)

• 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.

v0.9.82 (2026-01-12)

• 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.

v0.9.74 (2026-01-12)

• 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.

v0.9.71 (2026-01-10)

• 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.

v0.9.70 - Frontend Initialization Fix (2026-01-09)

• [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.

v0.9.69 - Frontend Crash Fix (2026-01-09)

• [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.

v0.9.67 - Compact Mode & Canvas Fix (2026-01-08)

• [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.

v0.9.61 - Frontend Memory Optimization (2026-01-07)

• [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.

v0.9.60 - Parallel Graph Metrics (2026-01-07)

• [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.

v0.9.57 - Worker Memory Optimization (2026-01-07)

• [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.

v0.9.56 - Hybrid Inference Memory Optimization (2026-01-05)

• [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.

v0.9.55 - Heap OOM Fix & Iterative DFS (2026-01-05)

• [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.

v0.9.54 - Welcome Experience (2026-01-05)

• [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.

v0.9.53 - Core API Decoupling (2026-01-05)

• [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.

v0.9.52 - Cycle Detection Memory Optimization (2026-01-05)

• [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.

v0.9.51 - Performance Logging & Crash Reporting (2026-01-03)

• [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).

v0.9.50 - GPU Acceleration (2026-01-02)

• [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.

v0.9.49 - Statistical Analysis Memory Optimization (2026-01-02)

• [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.

v0.9.49 - UI Controls for Parallel Processing (2026-01-02)

• [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.

v0.9.48 - Parallel Processing Optimization (2026-01-02)

• [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.

v0.9.47 - Focus Mode Interaction & Layout Fixes (2026-01-02)

• [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).

v0.9.46 - Focus Mode UI Cleanup & Canvas Edge Fix (2025-12-26)

• [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.

v0.9.45 - Canvas Interactivity & Cleanup (2025-12-26)

• [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.

v0.9.44 - Independent Focus Mode Spacing (2025-12-26)

• [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.

v0.9.43 - Context-Aware Settings UI (2025-12-26)

• [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.

v0.9.42 - Distinct Repulsion Settings (2025-12-26)

• [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.

v0.9.41 - Settings Modal Simulation Freeze (2025-12-26)

• [x] Resource Saving: The simulation now automatically pauses w