Merge pull request #56 from VariableThe/feat/v0.5.3

feat: graph view overhaul, Windows focus-loss fix, Cmd+/ shortcuts, welcome revamp (v0.5.3)

Author: VariableThe

.gitignore

@@ -32,3 +32,5 @@ target/
 src-tauri/target/
 src-tauri/gen/
 window-state.json
+*.tar.gz
+*.tar.xz

AUDIT_LOG.md

@@ -2,6 +2,52 @@
 
 This log tracks all significant changes, updates, and versions in the PaperCache project.
 
+## 2026-06-24 - (Uncommitted)
+**Change:** feat: graph view rebuilt, Windows focus-loss fix, Cmd+/ shortcuts, welcome revamp (v0.5.3)
+
+**Details/Why:**
+Major graph view overhaul and cross-platform fixes:
+
+1. **Flat Circle Nodes with Occlusion**: Replaced default 3D spheres with `CircleGeometry` meshes. Circles render in the transparent pass at `renderOrder: 1` (after edges), with `depthWrite: true` — edges passing through nodes are now cleanly occluded.
+
+2. **Always-Visible Labels**: Each node returns a `THREE.Group` containing the circle mesh plus a canvas-based `THREE.Sprite` label. Labels are positioned below each circle and always visible (never fade on zoom).
+
+3. **Cmd+F Fuzzy Search in Graph**: Search bar with character-order fuzzy matching, arrow-key navigation, and Enter to fly the camera to the matched node.
+
+4. **Folder Clustering**: `d3-force` `forceX`/`forceY` at 0.008 strength weakly attract same-folder nodes toward shared centroids on a 60-unit radius, creating subtle visual groupings.
+
+5. **Cmd+Shift+N No Longer Hides Open App**: Changed the Rust global shortcut handler in `shortcuts.rs` — for `new-note` action, window only shows if hidden; never hides when already visible. All other shortcuts (toggle, etc.) retain `toggle_window` behavior.
+
+6. **Windows Focus-Loss Debounce**: `lib.rs` focus-loss handler now uses a 200ms debounce via `AtomicBool` + `std::thread::spawn`. Clicking the title bar on Windows 10 briefly triggers `Focused(false)` — the debounce waits 200ms for a matching `Focused(true)` before hiding. On macOS, hide remains immediate.
+
+7. **Cmd+/ Shortcuts Reference**: New shortcut opens or auto-creates `Shortcuts.md` with all keyboard shortcuts and slash commands listed.
+
+8. **Fresh Install Welcome**: Version check in `App.tsx` detects `null` last-seen-version (fresh install) and opens `Welcome.md` instead of looking for a new-features note. The Rust onboarding template (`fs.rs`) was revamped with a bullet-list feature overview.
+
+9. **Lazy-Loaded Graph**: `GraphView` dynamically imported via `React.lazy()` — Three.js bundle (~1.3 MB) loads only on first graph open.
+
+10. **Doc Updates**: Version bumped to 0.5.3 across all manifest files. `CHANGELOG.md`, `features.md`, `README.md`, `notes/New Features in v0.5.3.md` all updated.
+
+---
+
+## 2026-06-24 - Native Notifications, Timers, DSL Engine, WebGL Graph
+**Change:** feat: native notifications, timers, DSL regex engine, WebGL graph with folder attraction
+
+**Details/Why:**
+Implemented four major platform features as requested:
+
+1. **Native Reminder Notifications (Rust Backend):** Removed the old Web Notification API + `setTimeout` polling loop from the JS renderer. All reminder scheduling is now delegated to a new `commands/notifications.rs` Rust module. Uses `tokio::spawn` + `tokio::time::sleep` to wait for exact due times and fires native OS notifications via `tauri_plugin_notification`. This ensures reminders are reliable when the app is minimized, handles OS notification permission gracefully, and eliminates renderer-side timer drift. A `reminder-fired` Tauri event is emitted to the frontend to show an in-app toast and update localStorage.
+
+2. **Timers:** Added a new `useTimerStore.ts` Zustand store and `TimersPage.tsx` component with a glassmorphic panel UI. Countdowns use a chained `setTimeout` pattern (no `setInterval`) for drift-corrected display. The Rust backend (`schedule_timer` / `cancel_timer` commands) fires the native OS notification and emits `timer-complete` on completion — ensuring timers complete even when minimized. A "Timers" button was added to `MainActionMenu`, and the `/timer` slash command was added to the editor.
+
+3. **DSL Regex Parsing Engine:** Created `src/lib/editor/dslPlugin.ts` — a factory `createRegexPlugin(rules: DSLRule[])` that generates CodeMirror ViewPlugins. Scans only `view.visibleRanges` per update tick (O(visible lines)), guaranteeing lag-free typing at any document size. Supports `className` mark decorations, `widget` factories, and `onMatch` callbacks per rule.
+
+4. **WebGL Graph with Folder Attraction:** Replaced `react-force-graph-2d` (Canvas 2D) with `react-force-graph-3d` (Three.js / WebGL) lazy-loaded via `React.Suspense`. The graph is configured in 2D mode (z-axis locked). Added custom `d3-force` `forceX` and `forceY` forces that pull nodes toward per-folder centroid positions, creating organic cluster layouts where notes from the same folder attract each other.
+
+**Files changed:** `src-tauri/src/commands/notifications.rs` [NEW], `src-tauri/src/commands/mod.rs`, `src-tauri/src/lib.rs`, `src-tauri/Cargo.toml`, `src-tauri/capabilities/default.json`, `package.json`, `src/types.d.ts`, `src/api.ts`, `src/hooks/useReminders.ts`, `src/hooks/useReminders.test.ts`, `src/store/useAppStore.ts`, `src/store/useTimerStore.ts` [NEW], `src/components/TimersPage.tsx` [NEW], `src/components/MainActionMenu.tsx`, `src/lib/editor/slashCommands.ts`, `src/lib/editor/dslPlugin.ts` [NEW], `src/GraphView.tsx`, `src/App.tsx`, `src/App.css`.
+
+---
+
 ## 2026-06-24 - (Uncommitted)
 **Change:** feat: add slash command autosuggest, auto-open new features note, and tag action menu for v0.5.2
 

CHANGELOG.md

@@ -5,6 +5,36 @@ All notable, user-facing changes to PaperCache will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [v0.5.3] - 2026-06-24
+
+### Added
+- **Redesigned Graph View**: Nodes are now flat `CircleGeometry` with `depthWrite: true` and `renderOrder: 1` in the transparent pass, cleanly occluding edges behind them. Always-visible canvas-based text labels positioned below each node.
+- **Cmd+F Fuzzy Search in Graph**: Press `Cmd+F` in graph view to search note names by fuzzy character matching. Navigate with arrow keys, confirm with Enter to fly the camera to the matching node.
+- **Folder Clustering**: Notes sharing a folder are weakly attracted to a shared centroid via forceX/forceY at 0.008 strength, producing subtle visual grouping without breaking the unified cluster.
+- **Cmd+/ Shortcuts Reference**: Press `Cmd+/` (or `Cmd+?`) to open or create a `Shortcuts.md` note listing all keyboard shortcuts and slash commands.
+- **Fresh Install Welcome**: First-time launch now opens `Welcome.md` instead of looking for a new-features note. The welcome note has been revamped with a full feature overview.
+- **Lazy-Loaded Graph**: `GraphView` is dynamically imported with `React.lazy()` so the Three.js bundle (~1.3 MB) loads only when the graph is opened.
+- **Smooth Graph Fade-in**: The graph overlay animates in with a 250ms CSS keyframe fade.
+- **Persistent Node Positions**: After closing the graph view, node positions are cached and restored on next open, preserving manual arrangement.
+- **Native OS Reminder Notifications**: Task reminders (`/task`) now fire native OS notifications via the Rust backend using `tokio::time::sleep` + `tauri_plugin_notification`. Notifications fire reliably even when the app is minimized or out of focus, and gracefully handle OS-level permission denials.
+- **Countdown Timers**: New timer panel (accessible via the action menu or `/timer` command) lets you create, view, pause/resume, and cancel countdown timers. Timers display a live countdown using drift-corrected `setTimeout` chains and trigger both a native OS notification and an in-app alert on completion — even if you're viewing a different note.
+- **DSL Regex Parsing Engine**: New `createRegexPlugin()` factory in `dslPlugin.ts` enables flexible, regex-based Domain Specific Language parsing in the editor. Scans only visible ranges for O(visible lines) performance — lag-free at any document size. Supports custom mark decorations, widget injections, and match callbacks.
+- **WebGL Graph View**: The Graph View has been rewritten using Three.js WebGL via `react-force-graph-3d`. Notes in the same folder are attracted to shared centroid positions via custom `d3-force` simulation rules, causing them to cluster together naturally. The graph is lazy-loaded to avoid impacting editor startup time.
+
+### Changed
+- **Cmd+Shift+N Behavior**: The global new-note shortcut no longer hides the app if it's already visible. It only shows the window when hidden. The shortcut always creates a new note regardless.
+- **Node Circle Size**: Increased from radius 8 to 12, with labels shifted and scaled accordingly.
+- **Windows Focus-Loss Debounce**: Hiding on focus loss now uses a 200ms debounce to prevent accidental hide when clicking the title bar for drag or resize.
+- **Node Positions Cache**: Force simulation no longer pushes dragged nodes back — the strength accessor skips nodes in the dragged set.
+- **Graph Controls**: OrbitControls configured with `enableRotate = false`, `LEFT = PAN`, `MIDDLE = DOLLY` for a pure 2D navigation experience.
+
+### Fixed
+- Fixed edges/lines showing through circle nodes by making circle meshes render in the transparent pass after links.
+- Fixed graph view opening inside the shortcut handler (removed stale `showGraphView` setter call from version check effect).
+- Fixed blank graph issue on re-open by caching node positions at component unmount.
+
+---
+
 ## [v0.5.2] - 2026-06-24
 
 ### Added

README.md

@@ -20,7 +20,7 @@ Summon it with a hotkey. Jot. Dismiss. It stays out of your way until you need i
 - **Interactive Checkboxes & Slash Commands** — Type `/` to see inline autosuggestions (like `/check`, `/task`, or `/ai`). Press `Tab` to instantly complete them. Checkboxes strike through text when clicked.
 - **Tasks & Reminders** — Type `/task` followed by `@ 1d2h` to set a due date. Press `Cmd+T` to open a unified Tasks view that tracks all your pending items and due times.
 - **Tags & folders** — `!tagname` for tags, `/` in note titles for folders. Right-click any tag pill to export or delete all tagged notes at once.
-- **Graph view** — see how your notes connect (`Cmd+G`).
+- **Graph view** — press `Cmd+G` to open a 2D knowledge graph with flat circle nodes, always-visible labels, and folder-based clustering. Press `Cmd+F` to fuzzy-search nodes and fly directly to the match.
 
 > **Deep Dive:** For a comprehensive list of every single feature in PaperCache, check out [features.md](features.md).
 > **Performance:** We take speed and battery life seriously. Check out our [Performance Audit](PERFORMANCE_AUDIT.md).
@@ -81,14 +81,16 @@ Built with Tauri, Rust, React, TypeScript, and Vite.
 | `Cmd+Shift+N` | New note (global, configurable)          |
 | `Cmd+Shift+S` | Open settings panel                      |
 | `Cmd+N`       | New note (in-app)                        |
+| `Cmd+/`       | Open shortcuts reference                 |
 | `Cmd+T`       | Open Tasks page                          |
 | `Cmd+K`       | Main action menu                         |
 | `Cmd+P`       | Search notes                             |
 | `Cmd+G`       | Graph view                               |
+| `Cmd+F`       | Search in graph (while graph is open)    |
 | `Cmd+H`       | Highlight selected text                  |
 | `Cmd+E`       | Export note                              |
 | `Cmd+Click`   | Follow internal link                     |
-| `Esc`         | Close menus or modals                    |
+| `Esc`         | Close menus / modals                     |
 
 ---
 

features.md

@@ -25,10 +25,16 @@ This document outlines every feature available in the PaperCache codebase, organ
 
 - **Note Folders**: Implicitly organize notes into folders by adding a `/` in the title (e.g., `projects/PaperCache.md`). Folders are auto-detected, color-coded, and cleanly removed from disk if they become empty.
 - **Internal Note Linking**: Link to other notes using markdown links like `[link text](/file Note.md)` or simply `/file Note.md`. Click the link with `Cmd+Click` or `Ctrl+Click` to instantly navigate to it. URL links also open in the system browser.
-- **Interactive Graph View**: An interactive, visual 2D node graph (`Cmd+G`) showing all connected notes, color-coded automatically based on their implicit folder. Click a node to open it.
+- **Interactive Graph View** (`Cmd+G`): An interactive 2D knowledge graph rendered with Three.js WebGL. Nodes are clean flat circles with always-visible labels, edges are colored by opacity. Features:
+  - **Folder Clustering**: Notes in the same folder are gently attracted toward a shared centroid, creating subtle visual groupings.
+  - **Cmd+F Fuzzy Search**: Press `Cmd+F` inside graph view to fuzzy-search note names. Navigate with arrow keys, press Enter to fly the camera directly to the matched node.
+  - **Drag to Rearrange**: Nodes can be dragged freely; positions are cached and restored across graph sessions.
+  - **Smooth Fade-in**: The graph overlay animates in with a 250ms fade.
+  - **Lazy-Loaded**: The Three.js bundle (~1.3 MB) loads only when the graph is first opened, keeping startup fast.
 - **Global Note Search**: Open an omnibar search (`Cmd+P`) to quickly fuzzy-search note contents and file names across the entire workspace.
 - **Tagging System & Context Menu**: Add inline tags using `!tagname`. The global search bar aggregates all unique tags as clickable filters to quickly isolate notes. Right-click any tag pill to open an inline action menu, allowing you to bulk-delete or export all notes containing that tag into a single Markdown file.
 - **Auto-Renaming**: Notes are auto-created with a timestamp ID. The title is intelligently inferred from the first line of the file (e.g., `# Header`), but can also be manually renamed by clicking the title bar.
+- **Shortcuts Reference** (`Cmd+/` or `Cmd+?`): Press this anywhere in the app to open or create a `Shortcuts.md` note listing every keyboard shortcut and slash command.
 
 ## Artificial Intelligence
 
@@ -40,15 +46,17 @@ This document outlines every feature available in the PaperCache codebase, organ
 
 ## Desktop System Integration
 
-- **Stealth / Background Mode**: Click away or lose focus, and the app instantly hides itself. On macOS, it runs as an "accessory" and hides its dock icon completely, acting like a true floating utility.
+- **Stealth / Background Mode**: Click away or lose focus, and the app instantly hides itself (macOS) or after a brief debounce (Windows/Linux — prevents accidental hide when dragging the title bar). On macOS, it runs as an "accessory" and hides its dock icon completely, acting like a true floating utility.
 - **Intelligent Multi-Monitor Support**: When summoning the app via its global hotkey, it detects the active screen your mouse is currently on and brings the window instantly to that specific screen's workspace.
 - **System Tray Icon**: A minimal system tray icon for toggling visibility or quitting the app cleanly, adapting to the user's OS theme (light/dark).
 - **Global Hotkeys**:
-  - `Cmd+Shift+N` (configurable): Instantly spawn a new floating note from anywhere on your OS.
+  - `Cmd+Shift+N` (configurable): Spawn a new note from anywhere. If the app is already open, creates the note without hiding.
   - `Cmd+Shift+C` (configurable): Toggle PaperCache visibility from anywhere on your OS.
 - **State Memory**: Memorizes precise window coordinates, dimensions, and zoom levels across launches to persist workspace state.
 - **Fluid Settings**: Opening the Settings menu dynamically inherits the exact dimensions and on-screen coordinates of your current notepad for a native, seamless transition.
 - **Launch on Startup**: Optional setting to boot silently in the background when your computer starts.
 - **Exporting Options**: Export individual notes straight to a local `.md` file on your filesystem via the main menu or search list.
 - **Safe Tutorials**: Auto-generates fully functional Markdown tutorials in a `commands/` folder upon first launch. Prevents accidental deletion of these core tutorial files.
 - **Smart Version Updates**: Upon updating to a new release, PaperCache automatically opens a "New Features" summary note on your first launch and cleanly deletes older version notes behind the scenes to keep your workspace tidy.
+- **Fresh Install Welcome**: First-time users automatically open to a revamped `Welcome.md` note with a complete feature overview instead of an empty editor.
+- **Node Positions Persist**: After closing the graph view, node positions are cached and restored on next open, preserving manual arrangement.

notes/New Features in v0.5.3.md

@@ -0,0 +1,16 @@
+# New Features in v0.5.3
+
+Welcome to PaperCache v0.5.3!
+
+Here are the new features implemented in this version:
+- **Redesigned Graph View**: Nodes are now rendered as clean, flat circles that properly occlude edges passing through them. Labels are always visible below each node. Circle size increased for better readability.
+- **Cmd+F Fuzzy Search in Graph**: Press `Cmd+F` in graph view to fuzzy-search note names. Navigate results with arrow keys, press Enter to pan/zoom to the matched node.
+- **Folder Clustering**: Notes in the same folder are gently attracted toward a shared centroid, creating subtle visual groupings. The graph still forms a single connected cluster.
+- **Better Cmd+Shift+N Behavior**: When the app is already open, the global new-note shortcut now creates a new note without hiding the window. It only toggles visibility when the app is hidden.
+- **Windows Focus-Loss Fix**: Clicking the title bar to drag or resize on Windows no longer accidentally hides the app.
+- **Fresh Install Welcome**: First-time users now automatically open to the `Welcome.md` note with a feature overview.
+- **Shortcuts Reference**: Press `Cmd+/` to open a `Shortcuts.md` note listing all keyboard shortcuts and slash commands.
+- **Fade-in Animation**: The graph view now fades in smoothly when opened.
+- **Lazy-Loaded Graph**: The Three.js graph engine is lazy-loaded, keeping the main bundle lean and startup fast.
+
+*(If you have read this note, feel free to delete it)*