codesynapt 0.0.0

package/plugin-api/docs/types/theme.md

@@ -0,0 +1,312 @@
+# Theme plugin
+
+A theme plugin is the simplest plugin type — just CSS. You override
+the app's CSS variables under a `body[data-theme="your-id"]` selector,
+and filegraph3d picks it up automatically.
+
+- [Minimal example](#minimal-example)
+- [Every variable you can override](#every-variable-you-can-override)
+- [Palette construction](#palette-construction)
+- [Decorations: corner brackets and accents](#decorations-corner-brackets-and-accents)
+- [Dark vs light themes](#dark-vs-light-themes)
+- [Studying built-in themes](#studying-built-in-themes)
+- [Common mistakes](#common-mistakes)
+
+## Minimal example
+
+```
+plugins/my-theme/
+├── manifest.json
+└── theme.css
+```
+
+**`manifest.json`:**
+
+```json
+{
+  "id": "my-theme",
+  "name": "My Theme",
+  "version": "1.0.0",
+  "type": "theme",
+  "main": "theme.css",
+  "minAppVersion": "0.10.0",
+  "license": "MIT"
+}
+```
+
+**`theme.css`:**
+
+```css
+body[data-theme="my-theme"] {
+  --bg:     #1A1A1A;
+  --fg:     #F0F0F0;
+  --accent: #FF8800;
+}
+```
+
+That's a working theme. It won't look great because you've only set 3
+of ~30 variables, but it'll load. Read on for the rest.
+
+## Every variable you can override
+
+filegraph3d's UI is parameterized by ~30 CSS custom properties. The
+full list:
+
+### Backgrounds
+
+| Variable | Used by | Notes |
+|---|---|---|
+| `--bg` | Body background | The main canvas background. Pure color, no alpha. |
+| `--bg-deep` | Very deep accents | Slightly darker than `--bg`. |
+| `--bg-elev` | Raised elements | Tooltips, dropdowns. Use `rgba(...)` for translucency. |
+| `--bg-glass` | All floating panels | The "frosted glass" panel background. Should be `rgba()` with ~0.85 alpha. |
+| `--bg-solid` | Where solid is required | Settings panel sections, etc. |
+
+### Borders
+
+| Variable | Used by | Notes |
+|---|---|---|
+| `--border` | Default panel borders | Should be visible but not loud. |
+| `--border-hot` | Active / focused borders | Brighter version of `--border`. |
+| `--border-edge` | Subtle dividers, separators | Nearly invisible (alpha ~0.05). |
+
+### Foregrounds
+
+| Variable | Used by | Notes |
+|---|---|---|
+| `--fg` | Primary text | Should pass contrast against `--bg`. |
+| `--fg-dim` | Secondary text | Labels, less important info. |
+| `--fg-mute` | Tertiary text | Captions, kicker text. |
+| `--fg-faint` | Quaternary text | Disabled, divider labels. |
+
+### Accents (semantic colors)
+
+| Variable | Semantic role | Where |
+|---|---|---|
+| `--accent` | Default information / focus | Buttons, highlights, brand dot, search focus border |
+| `--accent-warm` | Active set / starred | Star buttons, pipelines panel, active markings |
+| `--accent-pink` | Warning / danger | Delete buttons, error states |
+| `--accent-cool` | Secondary focus | Focus ripples (less common) |
+| `--danger` | Errors | Validation failures, destructive confirmation |
+
+### Typography
+
+| Variable | Used by |
+|---|---|
+| `--font-mono` | Monospace text (code, data, default body) |
+| `--font-display` | Display text (logo, headers) |
+
+The defaults expect `'JetBrains Mono'` to be available, with fallbacks
+to `'SF Mono'`, `ui-monospace`, `Menlo`. You can change to any font
+stack you like; the user must have it installed.
+
+### Layout
+
+| Variable | Used by |
+|---|---|
+| `--radius` | Border-radius for panels, buttons | `0` = brutalist, `4-6px` = friendly, `12px+` = bubbly |
+| `--space-1` through `--space-6` | 4px grid spacing | Rarely needs override |
+
+### Motion & decoration flags
+
+| Variable | What it controls |
+|---|---|
+| `--decoration` | `1` to show corner brackets on panels, `0` to hide |
+| `--grain` | Opacity of background noise overlay (`0` to `0.05`) |
+| `--motion-scale` | Multiplier for ambient animations (`0` = none, `1` = default, `1.5` = more) |
+
+### Easing
+
+| Variable | Used by |
+|---|---|
+| `--ease-out` | Smooth ease-out for hover transitions |
+| `--ease-snap` | Snappy ease for selection changes |
+
+## Palette construction
+
+A good theme needs **5 colors** at minimum:
+
+1. **Background** (`--bg`)
+2. **Foreground** (`--fg`)
+3. **Three accents** (`--accent`, `--accent-warm`, `--accent-pink`)
+
+### Step-by-step
+
+**1. Pick a background.** This sets the mood:
+- Near-black (`#0A0A0A`) — neutral terminal feel
+- Tinted dark (`#1A1B26` Tokyo Night, `#2A1810` warm) — character
+- True white (`#FAFAFA`) — light mode
+
+**2. Pick a foreground that contrasts.**
+- For dark bg: `#E0E0E0` to `#F5F5F5`
+- For light bg: `#1A1A1A` to `#333333`
+- Aim for **WCAG AA** contrast (4.5:1 minimum for normal text).
+
+**3. Pick `--accent`.** This is the main signal color. Used everywhere
+you want to draw the eye. Choose something that:
+- Stands out against `--bg`
+- Doesn't fight `--fg` (don't pick a similar hue)
+
+**4. Pick `--accent-warm` and `--accent-pink`.** These are semantic:
+- `--accent-warm` = active set, starred (golds, oranges work great)
+- `--accent-pink` = danger, deletion (reds, hot pinks)
+
+The three accents should be **distinguishable at a glance**. If they're
+all bluish, users can't tell what each one means.
+
+**5. Generate the supporting colors.**
+
+Common pattern (in HSL):
+```
+--fg:       hsl(H, S,   95%)
+--fg-dim:   hsl(H, S*0.8, 75%)
+--fg-mute:  hsl(H, S*0.5, 50%)
+--fg-faint: hsl(H, S*0.3, 35%)
+```
+
+Where `H, S` are the hue/saturation of the base foreground.
+
+For borders, use the accent color at low alpha:
+```
+--border:      rgba(R, G, B, 0.16)   /* visible */
+--border-hot:  rgba(R, G, B, 0.55)   /* active */
+--border-edge: rgba(R, G, B, 0.06)   /* nearly invisible */
+```
+
+Where `R, G, B` is your accent color's RGB.
+
+## Decorations: corner brackets and accents
+
+filegraph3d's built-in themes have **corner brackets** on panels —
+small `┌` `┐` `└` `┘` marks that frame each panel. These are part of
+the "Observatory" aesthetic.
+
+You control them with `--decoration`:
+
+```css
+body[data-theme="my-clean-theme"] {
+  --decoration: 0;   /* hide all corner brackets */
+}
+```
+
+```css
+body[data-theme="my-bold-theme"] {
+  --decoration: 1;   /* show corner brackets (default) */
+}
+```
+
+When `--decoration: 0`:
+- Corner brackets disappear
+- ASCII dividers in welcome screen hide
+- `[ ]` brackets around the brand label hide
+
+This single switch controls roughly two dozen decorative elements.
+
+## Dark vs light themes
+
+Light themes need a few extra tweaks. Set everything as usual, then:
+
+```css
+body[data-theme="my-light-theme"] {
+  --bg:           #FAFAFA;
+  --fg:           #1A1A1A;
+  --accent:       #0066CC;
+  --accent-warm:  #B87000;
+  --accent-pink:  #CC2233;
+
+  /* Soften the grain overlay (it looks bad on white) */
+  --grain: 0;
+
+  /* Borders need to be dark on light bg */
+  --border:       rgba(0, 0, 0, 0.08);
+  --border-hot:   rgba(0, 0, 0, 0.3);
+  --border-edge:  rgba(0, 0, 0, 0.04);
+}
+
+/* Hide the grain overlay specifically for this theme */
+body[data-theme="my-light-theme"]::before {
+  opacity: 0 !important;
+}
+```
+
+The grain overlay is set on `body::before` and uses
+`mix-blend-mode: overlay`, which looks fine on dark but adds ugly
+specks on light. Force it off.
+
+## Studying built-in themes
+
+The seven built-in themes are great references. They live in the
+app's `public/style.css`. Each is implemented as a `body[data-theme="..."]`
+block:
+
+- `observatory` — the default, brutalist + corner brackets
+- `minimal` — Obsidian-style, soft and quiet
+- `terminal` — Linear-style, monochrome
+- `maximal` — bold gradients
+- `carbon` — CRT phosphor green
+- `mono` — Tokyo Night warmth
+- `daylight` — light mode
+
+Open `style.css` and grep for `body[data-theme=` to find each one.
+Copy the parts you like.
+
+## Common mistakes
+
+### "My theme doesn't show up"
+
+- Did you **fully quit** the app (Cmd/Ctrl+Q) and reopen? Themes are
+  injected at startup.
+- Is `manifest.json` valid JSON? Try `jsonlint.com`.
+- Is the folder name and `manifest.id` matching? They don't have to be
+  identical, but the `id` determines what selector you need (it's
+  `body[data-theme="<id>"]`, not the folder name).
+
+### "Colors look right but layout is weird"
+
+You probably forgot `--decoration` or `--radius`. Set them explicitly
+even if you want defaults — relying on inheritance gives unpredictable
+results when users switch from another theme.
+
+### "It looks fine in my theme but broken in others"
+
+Don't define your CSS variables outside the `body[data-theme="..."]`
+selector. If you do, they leak into other themes. Bad:
+
+```css
+/* ❌ leaks to all themes */
+:root {
+  --accent: #FF0000;
+}
+```
+
+Good:
+
+```css
+/* ✅ scoped to this theme only */
+body[data-theme="my-theme"] {
+  --accent: #FF0000;
+}
+```
+
+### "Light mode text is unreadable"
+
+Check your contrast ratios. On light backgrounds:
+- `--fg` should be very dark (`#1A1A1A` to `#333`)
+- `--fg-mute` should still be readable (`#666` minimum)
+
+Use a contrast checker like `webaim.org/resources/contrastchecker/`.
+
+### "My theme breaks the file tree colors"
+
+The colored squares next to filenames come from the **app's** file-type
+palette, not your theme. They're hardcoded by extension (`.js` = yellow,
+`.tsx` = blue, etc). If you want a different file-type palette, that's
+a different feature — currently not user-overridable.
+
+## Next steps
+
+- Try the [sunset-theme example](../../examples/sunset-theme/) — a
+  warm coral-orange theme you can copy and modify.
+- Read the [exporter guide](./exporter.md) for your next plugin type.
+- Or jump to the [API reference](../api-reference.md) for the full
+  surface.

package/plugin-api/examples/hello-world-plugin/README.md

@@ -0,0 +1,70 @@
+# hello-world-plugin
+
+A minimal action plugin that demonstrates:
+
+- Registering a context-menu item
+- Subscribing to selection events
+- Showing toast notifications
+- Using `ctx.log` for debugging
+
+## What it does
+
+When installed:
+
+1. **Right-click any node** in the graph — a "Hello from plugin" item
+   appears in the menu. Click it to see a toast.
+
+2. **Click any node** — a toast pops up with that node's basic stats
+   (incoming/outgoing edge counts).
+
+## Install
+
+Copy this folder into your filegraph3d plugins directory:
+
+```
+macOS:   ~/Library/Application Support/FileGraph 3D/plugins/
+Windows: %APPDATA%\FileGraph 3D\plugins\
+Linux:   ~/.config/FileGraph 3D/plugins/
+```
+
+Quit and reopen filegraph3d. Open any folder. Click or right-click
+nodes.
+
+## Files
+
+- **`manifest.json`** — declares the plugin as type `action` with no
+  required permissions (read-graph is implicit, and the toast/log
+  helpers don't need permissions).
+
+- **`main.js`** — the entry point. Subscribes to events, registers a
+  context-menu item, and stores its unsubscribe function so
+  `deactivate()` can clean up.
+
+## What to look at
+
+- The `default export` shape — every code plugin has an object with
+  at least an `activate(ctx)` function.
+
+- `ctx.events.on(...)` returns an unsubscribe function. The plugin
+  stores it as `this._unsub` and calls it from `deactivate()`.
+
+- `ctx.ui.registerContextMenuItem(...)` doesn't return a useful handle
+  for the plugin to track because the plugin host handles cleanup
+  automatically when the plugin unloads.
+
+- `ctx.toast(...)` automatically prefixes messages with `[hello-world]`
+  so the user knows where they came from.
+
+## What to try next
+
+Modify `main.js` to:
+
+- Show different info in the toast (e.g. file extension, size in KB)
+- Filter the context menu to only appear on `.js` files (use the
+  `enabled` callback)
+- Subscribe to a different event (`focus:changed`, `snapshot:applied`)
+- Persist a counter in `ctx.storage` ("you've clicked X files")
+
+## License
+
+MIT.

package/plugin-api/examples/hello-world-plugin/main.js

@@ -0,0 +1,36 @@
+// Minimal plugin example.
+// Listens for node selections and shows a toast with stats.
+
+export default {
+  activate(ctx) {
+    ctx.log('Hello World plugin loaded')
+
+    // Subscribe to selection events
+    const unsub = ctx.events.on('selection:changed', (id) => {
+      if (!id) return
+      const node = ctx.graph.getNode(id)
+      if (!node) return
+
+      const outCount = ctx.graph.outgoing(id).length
+      const inCount = ctx.graph.incoming(id).length
+
+      ctx.toast(`${id} — ${outCount} out, ${inCount} in`)
+    })
+
+    // Register a context-menu item
+    ctx.ui.registerContextMenuItem({
+      label: 'Hello from plugin',
+      icon: '👋',
+      action: (nodeId) => {
+        ctx.toast(`You picked: ${nodeId}`)
+      }
+    })
+
+    // Cleanup function — called when plugin is disabled
+    this._unsub = unsub
+  },
+
+  deactivate() {
+    if (this._unsub) this._unsub()
+  }
+}

package/plugin-api/examples/hello-world-plugin/manifest.json

@@ -0,0 +1,12 @@
+{
+  "id": "hello-world",
+  "name": "Hello World",
+  "version": "1.0.0",
+  "author": "filegraph3d",
+  "description": "Minimal plugin scaffold — shows a toast on every selection",
+  "type": "action",
+  "main": "main.js",
+  "minAppVersion": "0.10.0",
+  "license": "MIT",
+  "permissions": []
+}

package/plugin-api/examples/mermaid-exporter/README.md

@@ -0,0 +1,125 @@
+# mermaid-exporter
+
+Exports the current graph as a [Mermaid](https://mermaid.js.org/)
+diagram (`.mmd`). Mermaid renders natively in GitHub Markdown, Notion,
+Obsidian, GitLab, and many other tools.
+
+## What it does
+
+Adds **"Mermaid Diagram"** as a new option in the export menu.
+
+Clicking it generates a file like:
+
+```mermaid
+graph LR
+  index_js["index.js"]
+  utils_js["utils.js"]
+  parser_js["parser.js"]
+  index_js --> utils_js
+  index_js --> parser_js
+  parser_js --> utils_js
+```
+
+You can paste this directly into a GitHub README inside a
+```` ```mermaid ```` code block, and it'll render as a diagram.
+
+## Install
+
+Copy this folder into your filegraph3d plugins directory:
+
+```
+macOS:   ~/Library/Application Support/FileGraph 3D/plugins/
+Windows: %APPDATA%\FileGraph 3D\plugins\
+Linux:   ~/.config/FileGraph 3D/plugins/
+```
+
+Quit and reopen filegraph3d. Open a folder. Open **Settings → Export**
+— you'll see "Mermaid Diagram" listed.
+
+## Files
+
+- **`manifest.json`** — declares the plugin as type `exporter` with
+  the `export` permission.
+
+- **`main.js`** — registers the exporter. The `generate` function
+  receives the graph and returns a Mermaid-format string.
+
+## How it handles ids
+
+Mermaid identifiers must be alphanumeric. The plugin maps every file
+path to a safe alias by:
+
+1. Taking the basename: `src/foo/bar.js` → `bar.js`
+2. Replacing non-alphanumeric chars with `_`: `bar.js` → `bar_js`
+3. Disambiguating duplicates: if two files have the same basename,
+   the second becomes `bar_js2`, the third `bar_js3`, etc.
+
+The original path is preserved as the **label** so it's still readable
+in the rendered diagram.
+
+## Limitations
+
+Mermaid struggles with very large graphs. Performance gets sluggish
+past ~500 nodes; rendering may fail past ~2000.
+
+For large codebases:
+
+1. Use filegraph3d's **active set** feature to mark just the files
+   you care about, then export.
+
+2. Or use the [GraphViz DOT exporter pattern](../../docs/types/exporter.md#example-graphviz-dot)
+   — GraphViz handles 10k+ nodes well.
+
+## What to change
+
+If you want to customize the output:
+
+### Different layout direction
+
+```js
+// Top-to-bottom instead of left-to-right:
+const lines = ['graph TB']
+```
+
+Options: `TB` (top→bottom), `BT`, `LR` (left→right), `RL`.
+
+### Group by folder
+
+```js
+const lines = ['graph LR']
+const folders = new Map()
+for (const node of graph.nodes) {
+  const dir = node.id.split('/').slice(0, -1).join('/') || 'root'
+  if (!folders.has(dir)) folders.set(dir, [])
+  folders.get(dir).push(node)
+}
+for (const [dir, nodes] of folders) {
+  lines.push(`  subgraph "${dir}"`)
+  for (const node of nodes) {
+    lines.push(`    ${alias(node.id)}["${basename(node.id)}"]`)
+  }
+  lines.push('  end')
+}
+// ... edges
+```
+
+### Style by extension
+
+```js
+// After declaring nodes:
+lines.push('  classDef js fill:#F7DF1E,stroke:#000')
+lines.push('  classDef ts fill:#3178C6,stroke:#000')
+for (const node of graph.nodes) {
+  lines.push(`  class ${alias(node.id)} ${node.ext}`)
+}
+```
+
+## License
+
+MIT.
+
+## More
+
+See [../../docs/types/exporter.md](../../docs/types/exporter.md) for
+the full exporter guide, including more output formats (GraphViz,
+custom JSON) and patterns for handling the active set.

package/plugin-api/examples/mermaid-exporter/main.js

@@ -0,0 +1,58 @@
+// Exports the current graph as a Mermaid diagram.
+// Output renders inside GitHub Markdown, Notion, Obsidian, etc.
+
+export default {
+  activate(ctx) {
+    ctx.exporters.register({
+      name: 'Mermaid Diagram',
+      extension: 'mmd',
+      mimeType: 'text/plain',
+      generate(graph) {
+        const lines = ['graph LR']
+
+        // Build a short alias for each node so the diagram stays readable
+        // when file paths are long
+        const aliases = new Map()
+        for (const node of graph.nodes) {
+          const short = node.id.split('/').pop() || node.id
+          let alias = sanitize(short)
+          // Disambiguate if two files share a basename
+          let n = 2
+          const taken = new Set(aliases.values())
+          while (taken.has(alias)) {
+            alias = sanitize(short) + n
+            n++
+          }
+          aliases.set(node.id, alias)
+        }
+
+        // Declare nodes with their display names
+        for (const node of graph.nodes) {
+          const alias = aliases.get(node.id)
+          const label = node.id.split('/').pop() || node.id
+          lines.push(`  ${alias}["${escapeLabel(label)}"]`)
+        }
+
+        // Then edges
+        for (const e of graph.edges) {
+          const sa = aliases.get(e.s)
+          const ta = aliases.get(e.t)
+          if (sa && ta) lines.push(`  ${sa} --> ${ta}`)
+        }
+
+        return lines.join('\n')
+      }
+    })
+
+    ctx.log('Mermaid exporter ready — use Export → Mermaid Diagram')
+  }
+}
+
+// Mermaid requires alphanumeric node ids — strip everything else
+function sanitize(s) {
+  return s.replace(/[^a-zA-Z0-9_]/g, '_').replace(/^(\d)/, '_$1')
+}
+
+function escapeLabel(s) {
+  return s.replace(/"/g, '\\"')
+}

package/plugin-api/examples/mermaid-exporter/manifest.json

@@ -0,0 +1,12 @@
+{
+  "id": "mermaid-exporter",
+  "name": "Mermaid Exporter",
+  "version": "1.0.0",
+  "author": "filegraph3d",
+  "description": "Export the graph as a Mermaid diagram (.mmd) for use in Markdown",
+  "type": "exporter",
+  "main": "main.js",
+  "minAppVersion": "0.10.0",
+  "license": "MIT",
+  "permissions": []
+}

package/plugin-api/examples/rust-parser/README.md

@@ -0,0 +1,71 @@
+# rust-parser
+
+A filegraph3d plugin that adds support for **Rust** (`.rs`) files.
+
+## What it does
+
+Without this plugin, filegraph3d ignores `.rs` files — they appear as
+isolated nodes with no edges, because the app doesn't know how to
+read Rust's import syntax.
+
+With this plugin installed, filegraph3d parses:
+
+- `use path::to::thing;` — including `pub use`
+- `mod foo;` — local module declarations
+- `extern crate foo;` — legacy crate imports
+
+Comments are stripped first so commented-out imports don't produce
+false edges.
+
+## Install
+
+```sh
+# Copy this folder into your filegraph3d plugins directory:
+# macOS:   ~/Library/Application Support/FileGraph 3D/plugins/
+# Windows: %APPDATA%\FileGraph 3D\plugins\
+# Linux:   ~/.config/FileGraph 3D/plugins/
+
+cp -r rust-parser ~/Library/Application\ Support/FileGraph\ 3D/plugins/
+```
+
+Then quit and reopen filegraph3d.
+
+Open a Rust project (or any folder containing `.rs` files). You'll
+see them connected by import edges in the graph.
+
+## Limitations
+
+This is a regex-based parser. It handles 95% of real-world Rust code
+but has known blind spots:
+
+| Case | Handling |
+|---|---|
+| `use foo::bar;` | ✅ Captures `foo` (the leading path segment) |
+| `use foo::{bar, baz};` | ✅ Captures `foo` once |
+| `use foo as f;` | ✅ Captures `foo` |
+| `use foo::*;` | ✅ Captures `foo` |
+| `pub use foo::bar;` | ✅ Captures `foo` |
+| Macro-generated `use` | ❌ Not seen (macros not expanded) |
+| `use` inside `mod { ... }` blocks | ⚠️ Captured but path may be wrong |
+| `#[cfg(...)] use foo;` | ✅ Captures (cfg-gated imports counted) |
+
+If you need precise Rust parsing (workspace resolution, real path
+resolution, cfg evaluation), this isn't the right tool — use
+[cargo-modules](https://github.com/regexident/cargo-modules) and
+export its graph.
+
+## How resolution works
+
+The parser returns import paths like `"std::collections"`. filegraph3d
+then tries to match these against actual files in your project. The
+matching is path-prefix based, so:
+
+- `use crate::foo::bar` → matches `src/foo/bar.rs` or `src/foo/bar/mod.rs`
+- `use std::collections` → no match (external crate, no source in your project)
+
+External crates appear as imports with no resolved target — they're
+visible in the inspector but don't create edges.
+
+## License
+
+MIT. Copy, modify, redistribute freely.