Contour Graph Puddles

Contour Graph Puddles is a desktop-only Obsidian plugin that keeps the familiar force-directed link graph and adds soft, organic folder grouping around notes.

It is the separately packaged successor experiment to Contour Graph View. The plugin ID, settings, CSS scope, repository, and release line are independent, so both plugins can be installed at the same time.

Beta installation with BRAT

1. Install and enable BRAT in Obsidian.
2. Run BRAT: Add a beta plugin for testing.
3. Enter kn05/contour-graph-puddles.
4. Enable Contour Graph Puddles in Community plugins.

The plugin requires Obsidian 1.8.0 or newer, a desktop client, and WebGL2.

What beta.6 includes

• Local folder puddles instead of a whole-map Voronoi partition
• A distance-based force simulation with node repulsion, target-length real-link springs, weak global gravity, non-distorting centering, and node collision
• One live center of mass per direct folder, recalculated in O(n) time on every tick; members receive a weak pull toward their own folder center
• No hidden folder edges, all-pairs springs, folder anchors, hierarchy springs, or post-layout position correction
• Direct-note surfaces only, so a parent never stretches across distant child folders
• A distinct deterministic default color for every visible direct folder, based on its full path, with member nodes colored to match the puddle
• Tags, unresolved references, root notes, and excluded folders in neutral space
• Round and capsule puddles for tiny folders, smoother organic contours for larger folders, and readable folder names where space permits
• Stronger light-theme color, boundary, node, edge, and label contrast
• Graph-coordinate geometry that stays synchronized during pan and zoom
• Folder hover details, click selection, Escape/background clearing, note opening, pinning, search, color groups, and theme support

Imported Core Graph settings drive repulsion, global gravity, real-link spring strength, and target link distance. Folder gravity is deliberately weaker than a real link and acts inside the same simulation, so cross-folder links can still pull bridge notes away from their folder center.

Usage

Run Contour Graph Puddles: Open graph or use the ribbon icon. On first load, supported values from the core Global Graph settings become this plugin's defaults. Later changes are stored independently. Use Import from Graph settings to import them again.

Hover a puddle to see its folder path and visible note count. Click a puddle to keep it selected; click the background or press Escape to clear the selection. Click a note to open it, or drag it to pin its position.

Use Excluded folders to keep selected notes and regular links visible while removing their puddle and folder gravity. Adjust Folder gravity, Puddle padding, and Puddle opacity to tune the grouping.

Development

npm install
npm run dev

For a production build:

npm run check

Verify release assets and versions with:

node scripts/check-release.mjs 0.1.0-beta.6

The BRAT release assets are main.js, manifest.json, and styles.css.

Privacy

Contour Graph Puddles reads vault metadata and the core graph configuration. It does not modify notes or core graph settings, and it makes no network requests.

License

MIT