codesynapt 0.0.0

package/plugin-api/docs/troubleshooting.md

@@ -0,0 +1,332 @@
+# Troubleshooting
+
+Common problems and their fixes.
+
+- [Plugin doesn't show up](#plugin-doesnt-show-up)
+- [Plugin appears in list but doesn't work](#plugin-appears-in-list-but-doesnt-work)
+- [Error: invalid manifest](#error-invalid-manifest)
+- [Error: entry path escapes plugin folder](#error-entry-path-escapes-plugin-folder)
+- [Error: missing or invalid permission](#error-missing-or-invalid-permission)
+- [Theme loads but looks wrong](#theme-loads-but-looks-wrong)
+- [Exporter generates but downloads nothing](#exporter-generates-but-downloads-nothing)
+- [Context menu item doesn't appear](#context-menu-item-doesnt-appear)
+- [Changes don't take effect](#changes-dont-take-effect)
+- [DevTools console errors](#devtools-console-errors)
+- [Still stuck](#still-stuck)
+
+## Plugin doesn't show up
+
+**Check the folder structure.** Your plugin must be in **its own
+subfolder** inside the plugins directory:
+
+```
+plugins/
+├── my-plugin/              ← ✅ this is right
+│   ├── manifest.json
+│   └── main.js
+└── my-other-plugin/        ← ✅ second plugin, also a subfolder
+    ├── manifest.json
+    └── theme.css
+```
+
+Loose files at the top of `plugins/` are ignored.
+
+**Check the plugin folder path.** filegraph3d shows the path in
+Settings → Appearance → Open plugin folder…. Verify your files are
+**in that exact directory**.
+
+**Check the manifest file.** Open `manifest.json` and confirm:
+- The file is literally named `manifest.json` (not `Manifest.json`,
+  not `manifest.JSON`).
+- It's valid JSON — paste into [jsonlint.com](https://jsonlint.com/)
+  if unsure.
+
+**Did you restart the app?** filegraph3d only scans for plugins at
+startup. **Cmd/Ctrl+Q to fully quit**, then reopen — just closing the
+window isn't enough on macOS.
+
+## Plugin appears in list but doesn't work
+
+The plugin was discovered but failed to validate or activate. Open
+**DevTools** (View → Toggle Developer Tools) and check the Console
+for messages like:
+
+```
+[plugin-loader] skipping <id>: <reason>
+[plugin:<id>] activate() threw: <error>
+```
+
+The reason will tell you exactly what's wrong. Common ones below.
+
+## Error: invalid manifest
+
+### `missing or invalid "id"`
+
+Every plugin needs an `id`. Make sure your manifest has one:
+
+```json
+{
+  "id": "my-plugin",        ← required
+  ...
+}
+```
+
+### `invalid id "..." (use alphanumeric + dash/underscore)`
+
+Plugin ids must match `[a-z0-9][a-z0-9-_]*` (lowercase alphanumeric,
+dashes, underscores). Starting character must be a letter or digit.
+
+```json
+{
+  "id": "My Plugin!"        ← ❌ spaces, capitals, punctuation
+  "id": "1plugin"           ← ✅ ok (starts with digit)
+  "id": "my-plugin"         ← ✅ standard
+  "id": "my_plugin_v2"      ← ✅ ok
+}
+```
+
+### `unknown type "..."`
+
+The `type` field must be one of:
+`theme`, `exporter`, `parser`, `layout`, `panel`, `action`.
+
+Typos like `themer` or `exporters` will fail.
+
+### `unknown permission "..."`
+
+Permissions must come from this list:
+`read-files`, `read-graph`, `modify-graph`, `ui-panel`,
+`context-menu`, `export`, `parse`.
+
+## Error: entry path escapes plugin folder
+
+You have something like `"main": "../something"` in your manifest.
+For security, plugins can only reference files inside their own folder.
+Move the file into the plugin directory.
+
+```json
+{
+  "main": "../../shared.js"   ← ❌ refuses to load
+  "main": "main.js"           ← ✅ inside plugin folder
+  "main": "src/main.js"       ← ✅ subdirectory is fine
+}
+```
+
+## Error: missing or invalid permission
+
+Trying to use an API method without declaring the matching permission:
+
+```
+Plugin "my-plugin" attempted "registerContextMenuItem" but does not declare permission "context-menu"
+```
+
+Add the permission to your manifest:
+
+```json
+{
+  ...
+  "permissions": ["context-menu"]
+}
+```
+
+Then restart the app.
+
+The full list:
+- `read-files` → `ctx.graph.readFile(id)`
+- `ui-panel` → `ctx.ui.registerPanel(...)`
+- `context-menu` → `ctx.ui.registerContextMenuItem(...)`
+- `export` → `ctx.exporters.register(...)`
+- `parse` → `ctx.parsers.register(...)`
+
+## Theme loads but looks wrong
+
+### "Some panels look broken"
+
+You probably only set a few variables. The app's UI uses ~30 CSS
+variables; if you override only `--bg` and `--accent`, you'll inherit
+the previous theme's other colors and they'll clash.
+
+Set everything from this list (with sensible values):
+
+```css
+body[data-theme="my-theme"] {
+  --bg:           ...
+  --bg-glass:     ...
+  --fg:           ...
+  --fg-dim:       ...
+  --fg-mute:      ...
+  --fg-faint:     ...
+  --border:       ...
+  --border-hot:   ...
+  --border-edge:  ...
+  --accent:       ...
+  --accent-warm:  ...
+  --accent-pink:  ...
+  --decoration:   0 or 1
+  --radius:       ...
+}
+```
+
+See [theme.md](./types/theme.md) for the full list and what each does.
+
+### "Light mode has weird specks/grain"
+
+The grain overlay (`body::before`) uses blend-mode that looks fine on
+dark but ugly on light. Disable it:
+
+```css
+body[data-theme="my-light-theme"] {
+  --grain: 0;
+}
+body[data-theme="my-light-theme"]::before {
+  opacity: 0 !important;
+}
+```
+
+### "Colors leak between themes"
+
+You defined CSS variables at `:root` instead of inside
+`body[data-theme="..."]`. The variables apply globally, polluting
+other themes. Scope them properly:
+
+```css
+/* ❌ leaks */
+:root {
+  --accent: #FF0000;
+}
+
+/* ✅ scoped */
+body[data-theme="my-theme"] {
+  --accent: #FF0000;
+}
+```
+
+## Exporter generates but downloads nothing
+
+### "Empty file downloads"
+
+Your `generate` function isn't returning the string. Check:
+
+```js
+generate(graph) {
+  console.log('hello')   // ❌ logged but never returned
+}
+```
+
+```js
+generate(graph) {
+  return 'hello'         // ✅
+}
+```
+
+### "Wrong extension on the file"
+
+`extension` should be the bare suffix, no dot:
+
+```js
+extension: 'mmd'   // ✅ → file.mmd
+extension: '.mmd'  // ❌ → file..mmd
+```
+
+### "Unicode characters render as ???"
+
+Add charset to the MIME type:
+
+```js
+mimeType: 'text/plain; charset=utf-8'
+```
+
+## Context menu item doesn't appear
+
+- Did you declare `"permissions": ["context-menu"]` in the manifest?
+- Did you fully restart the app?
+- Right-click directly on a **node** (sphere) in the graph — empty
+  space doesn't show node-context items.
+- Open DevTools and check for plugin activation errors.
+
+## Changes don't take effect
+
+filegraph3d **does not** hot-reload plugins right now. Any change to
+a plugin file requires:
+
+1. **Quit completely** (Cmd/Ctrl+Q, not just close window).
+2. **Reopen** the app.
+
+If you change `manifest.json`, the same applies. There's no way to
+reload just one plugin without restarting.
+
+(Hot reload is on the roadmap.)
+
+## DevTools console errors
+
+Open DevTools: **View → Toggle Developer Tools** (or Cmd/Ctrl+Option+I).
+
+Switch to the **Console** tab. Errors from your plugin are prefixed
+with `[plugin:<id>]`. For example:
+
+```
+[plugin:my-plugin] activate() threw: TypeError: cannot read property 'foo' of undefined
+    at activate (blob:file:///...:5:23)
+```
+
+The line number points to your `main.js`. Click the link to jump to
+the source.
+
+Common errors:
+
+### `Cannot read property '...' of undefined`
+
+You accessed something that doesn't exist. Most often:
+
+```js
+const node = ctx.graph.getNode(id)
+ctx.log(node.loc)   // ❌ if node is null, this throws
+```
+
+Add a null check:
+
+```js
+const node = ctx.graph.getNode(id)
+if (node) ctx.log(node.loc)
+```
+
+### `Plugin "..." attempted "..." but does not declare permission`
+
+Add the permission to your manifest. See
+[Error: missing or invalid permission](#error-missing-or-invalid-permission).
+
+### `Failed to fetch dynamically imported module`
+
+Your `main.js` has a syntax error preventing it from loading. Check
+it parses with `node --check main.js` if you have Node installed, or
+paste it into [esprima.org/demo/validate.html](https://esprima.org/demo/validate.html).
+
+### `await is only valid in async functions`
+
+Mark your function as `async`:
+
+```js
+generate: async (graph) => {
+  const content = await graph.readFile(...)
+  return content
+}
+```
+
+## Still stuck
+
+1. **Look at a working example.** Each `examples/*` plugin has a
+   README explaining how it's structured. Copy and modify.
+
+2. **Compare with the type definitions.** Open
+   [`../types.d.ts`](../types.d.ts) and check that your code matches
+   the expected shape.
+
+3. **File an issue.** [GitHub issues](https://github.com/YOUR_USER/filegraph3d/issues)
+   with:
+   - Your `manifest.json`
+   - Your `main.js` (or `theme.css`)
+   - The error from the DevTools console
+   - The filegraph3d version (Settings → About)
+
+4. **Ask the community.** Plugin discussion lives at
+   [GitHub Discussions](https://github.com/YOUR_USER/filegraph3d/discussions).

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

@@ -0,0 +1,377 @@
+# Exporter plugin
+
+An exporter plugin adds a new entry to filegraph3d's export menu. Your
+plugin receives the current graph and returns a string; the app handles
+file downloads, MIME types, and the user-facing UI.
+
+- [Minimal example](#minimal-example)
+- [What `generate` receives](#what-generate-receives)
+- [Example: Mermaid](#example-mermaid)
+- [Example: GraphViz DOT](#example-graphviz-dot)
+- [Example: Custom JSON](#example-custom-json)
+- [Tips & patterns](#tips--patterns)
+- [Common mistakes](#common-mistakes)
+
+## Minimal example
+
+```
+plugins/my-exporter/
+├── manifest.json
+└── main.js
+```
+
+**`manifest.json`:**
+
+```json
+{
+  "id": "my-exporter",
+  "name": "My Exporter",
+  "version": "1.0.0",
+  "type": "exporter",
+  "main": "main.js",
+  "minAppVersion": "0.10.0",
+  "license": "MIT",
+  "permissions": ["export"]
+}
+```
+
+**`main.js`:**
+
+```js
+export default {
+  activate(ctx) {
+    ctx.exporters.register({
+      name: 'My Format',
+      extension: 'txt',
+      mimeType: 'text/plain',
+      generate(graph) {
+        return `Exported ${graph.nodes.length} files`
+      }
+    })
+  }
+}
+```
+
+That's it. The user will see "My Format" in the export dropdown.
+Clicking it generates a `.txt` file with one line of text.
+
+## What `generate` receives
+
+The `generate` function gets a [`GraphAPI`](../api-reference.md#graphapi)
+object — read-only access to the current graph:
+
+```ts
+generate(graph: GraphAPI): string | Promise<string>
+```
+
+You can use:
+
+| Property/method | What it gives you |
+|---|---|
+| `graph.root` | Absolute path of the opened folder |
+| `graph.nodes` | Array of all nodes (each has `id`, `ext`, `size`, `loc`, `hex`) |
+| `graph.edges` | Array of all edges (each has `s`, `t`, `k`) |
+| `graph.selectedId` | Currently selected node id (or `null`) |
+| `graph.activeSet` | Currently active file set (or `null` if disabled) |
+| `graph.getNode(id)` | Lookup a single node |
+| `graph.outgoing(id)` / `graph.incoming(id)` | Get edges from/to a node |
+| `graph.readFile(id)` | Read file contents (requires `read-files` permission) |
+
+`generate` can be `async` if you need to do anything that takes time —
+for example reading file contents. The app shows a "Generating…"
+state while it's running.
+
+## Example: Mermaid
+
+[Mermaid](https://mermaid.js.org/) diagrams render inside GitHub
+Markdown, Notion, Obsidian, and many other tools.
+
+```js
+export default {
+  activate(ctx) {
+    ctx.exporters.register({
+      name: 'Mermaid Diagram',
+      extension: 'mmd',
+      mimeType: 'text/plain',
+      generate(graph) {
+        const lines = ['graph LR']
+
+        // Mermaid node ids must be alphanumeric, so we map every
+        // file path to a safe alias.
+        const aliases = new Map()
+        const taken = new Set()
+        for (const node of graph.nodes) {
+          const base = (node.id.split('/').pop() || node.id)
+            .replace(/[^a-zA-Z0-9_]/g, '_')
+            .replace(/^(\d)/, '_$1')
+          let alias = base
+          let n = 2
+          while (taken.has(alias)) alias = `${base}${n++}`
+          aliases.set(node.id, alias)
+          taken.add(alias)
+        }
+
+        // Declare each node with its file name as the visible label
+        for (const node of graph.nodes) {
+          const alias = aliases.get(node.id)
+          const label = (node.id.split('/').pop() || node.id)
+            .replace(/"/g, '\\"')
+          lines.push(`  ${alias}["${label}"]`)
+        }
+
+        // Then edges
+        for (const e of graph.edges) {
+          const s = aliases.get(e.s)
+          const t = aliases.get(e.t)
+          if (s && t) lines.push(`  ${s} --> ${t}`)
+        }
+
+        return lines.join('\n')
+      }
+    })
+  }
+}
+```
+
+For graphs over a few hundred nodes, Mermaid can get slow — consider
+filtering to just the active set:
+
+```js
+generate(graph) {
+  const active = graph.activeSet
+  const nodes = active
+    ? graph.nodes.filter((n) => active.has(n.id))
+    : graph.nodes
+  // ...rest as above, using `nodes` instead of `graph.nodes`
+}
+```
+
+## Example: GraphViz DOT
+
+[GraphViz](https://graphviz.org/) DOT is the lingua franca of dependency
+graphs. Render with `dot -Tsvg graph.dot -o graph.svg`.
+
+```js
+export default {
+  activate(ctx) {
+    ctx.exporters.register({
+      name: 'GraphViz DOT',
+      extension: 'dot',
+      mimeType: 'text/vnd.graphviz',
+      generate(graph) {
+        const lines = ['digraph G {']
+        lines.push('  rankdir=LR;')
+        lines.push('  node [shape=box, fontname="JetBrains Mono", fontsize=10];')
+
+        // Nodes — use file ids as both the dot identifier (quoted) and label.
+        for (const node of graph.nodes) {
+          const id = JSON.stringify(node.id)
+          const ext = node.ext
+          // Color nodes by extension
+          const color = colorForExt(ext)
+          lines.push(`  ${id} [label=${JSON.stringify(basename(node.id))}, color="${color}"];`)
+        }
+
+        // Edges
+        for (const e of graph.edges) {
+          lines.push(`  ${JSON.stringify(e.s)} -> ${JSON.stringify(e.t)};`)
+        }
+
+        lines.push('}')
+        return lines.join('\n')
+      }
+    })
+  }
+}
+
+function basename(p) {
+  return p.split('/').pop() || p
+}
+
+function colorForExt(ext) {
+  const map = { js: '#F7DF1E', ts: '#3178C6', jsx: '#61DAFB',
+                tsx: '#3178C6', py: '#3776AB', css: '#264DE4' }
+  return map[ext] || '#999999'
+}
+```
+
+DOT handles thousands of nodes gracefully — it's designed for this.
+
+## Example: Custom JSON
+
+If you want to feed the graph into your own tooling, a structured JSON
+export is often the right choice. Make sure your shape is documented
+or you'll forget what it means in six months.
+
+```js
+export default {
+  activate(ctx) {
+    ctx.exporters.register({
+      name: 'JSON (analysis)',
+      extension: 'json',
+      mimeType: 'application/json',
+      generate(graph) {
+        const data = {
+          // Versioning your export format pays off the first time you
+          // change it.
+          schemaVersion: 1,
+          generatedAt: new Date().toISOString(),
+          root: graph.root,
+          stats: {
+            nodeCount: graph.nodes.length,
+            edgeCount: graph.edges.length,
+          },
+          nodes: graph.nodes.map((n) => ({
+            id: n.id,
+            ext: n.ext,
+            size: n.size,
+            loc: n.loc,
+          })),
+          edges: graph.edges.map((e) => ({
+            from: e.s,
+            to: e.t,
+            kind: e.k,
+          })),
+        }
+        return JSON.stringify(data, null, 2)
+      }
+    })
+  }
+}
+```
+
+## Tips & patterns
+
+### Respect the active set when present
+
+If the user has curated an active set, they're telling you "the rest
+isn't really part of my project right now." Most exports should filter
+to it:
+
+```js
+const active = graph.activeSet  // null if disabled
+const nodes = active ? graph.nodes.filter((n) => active.has(n.id))
+                     : graph.nodes
+const edges = active
+  ? graph.edges.filter((e) => active.has(e.s) && active.has(e.t))
+  : graph.edges
+```
+
+### Truncate huge exports
+
+If your format struggles past 5k nodes (Mermaid does), warn the user
+or truncate:
+
+```js
+if (graph.nodes.length > 5000) {
+  ctx.toast(`Graph has ${graph.nodes.length} nodes — Mermaid may struggle. Consider using an active set.`)
+}
+```
+
+Toast access requires the plugin context, so capture it from
+`activate`:
+
+```js
+export default {
+  activate(ctx) {
+    this._ctx = ctx
+    ctx.exporters.register({
+      // ...
+      generate: (graph) => this.doExport(ctx, graph)
+    })
+  },
+  doExport(ctx, graph) {
+    if (graph.nodes.length > 5000) {
+      ctx.toast('Large graph — this may take a moment')
+    }
+    // ...
+  }
+}
+```
+
+### Make output reproducible
+
+Sort nodes/edges in a stable order. Otherwise diffing two exports of
+the same graph produces noise:
+
+```js
+const sortedNodes = [...graph.nodes].sort((a, b) => a.id.localeCompare(b.id))
+```
+
+### Don't read files unless you have to
+
+Reading file contents costs IO. If your format only needs the
+dependency structure, work from `graph.nodes` and `graph.edges` alone.
+
+If you do need contents:
+
+```js
+{
+  // ...
+  permissions: ['export', 'read-files']
+}
+```
+
+```js
+generate: async (graph) => {
+  const lines = []
+  for (const node of graph.nodes) {
+    const content = await graph.readFile(node.id)
+    // ... do something
+  }
+  return lines.join('\n')
+}
+```
+
+## Common mistakes
+
+### "My exporter doesn't appear in the export menu"
+
+- Did you declare `"permissions": ["export"]` in the manifest? Without
+  it, `ctx.exporters.register(...)` throws.
+- Did you quit and restart the app? Plugins load at startup.
+
+### "Generate runs but no file downloads"
+
+Make sure you `return` (not `console.log`) the generated string. Async
+generators must `return` a string (or `Promise<string>`).
+
+```js
+// ❌ no return — empty file
+generate(graph) {
+  console.log('done!')
+}
+
+// ✅ returns the string
+generate(graph) {
+  return 'hello'
+}
+```
+
+### "Output file has wrong extension"
+
+`extension` in your registration is the bare suffix without a dot:
+
+```js
+extension: 'mmd'  // ✅
+extension: '.mmd' // ❌ produces "file..mmd"
+```
+
+### "Unicode characters appear as ???"
+
+Make sure your `mimeType` indicates the encoding:
+
+```js
+mimeType: 'text/plain; charset=utf-8'
+```
+
+Or use a more specific type that implies UTF-8 (e.g.
+`application/json`).
+
+## Next steps
+
+- Try the [mermaid-exporter example](../../examples/mermaid-exporter/)
+  — a complete working version of the Mermaid exporter.
+- Look at the [API reference](../api-reference.md) for everything
+  available on `graph`.
+- Check [troubleshooting](../troubleshooting.md) when stuck.