codesynapt 0.0.0

package/plugin-api/README.md

@@ -0,0 +1,114 @@
+# filegraph3d plugin development
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+[![Plugin API: v0.1](https://img.shields.io/badge/Plugin%20API-v0.1.0-orange.svg)](./package.json)
+[![Plugin types: 6](https://img.shields.io/badge/plugin%20types-6-blueviolet)](#six-plugin-types)
+[![Examples: 4](https://img.shields.io/badge/examples-4-success)](./examples/)
+
+> Build themes, exporters, parsers, layouts, panels, and context-menu
+> actions for [filegraph3d](https://github.com/YOUR_USER/filegraph3d).
+
+This package contains the public API surface for filegraph3d plugins.
+It is **MIT-licensed** — you can build and distribute plugins under any
+license you choose, including commercially. The main filegraph3d app
+itself is AGPL-licensed; see the top-level `LICENSE` for details.
+
+---
+
+## Where to start
+
+| If you want to… | Read this |
+|---|---|
+| Build your first plugin in 5 minutes | [Getting started](./docs/01-getting-started.md) |
+| Understand how plugins work | [Concepts](./docs/02-concepts.md) |
+| Add a new color theme | [Theme guide](./docs/types/theme.md) |
+| Add an export format | [Exporter guide](./docs/types/exporter.md) |
+| Look up an API method | [API reference](./docs/api-reference.md) |
+| Fix something that's not working | [Troubleshooting](./docs/troubleshooting.md) |
+| Copy a working example | [examples/](./examples/) |
+
+---
+
+## Six plugin types
+
+| Type | What it does | Difficulty | Example |
+|---|---|---|---|
+| `theme` | A new color palette and look | ★☆☆ | [sunset-theme](./examples/sunset-theme/) |
+| `exporter` | A new export format (Mermaid, GraphViz, etc.) | ★☆☆ | [mermaid-exporter](./examples/mermaid-exporter/) |
+| `action` | A right-click item on graph nodes | ★☆☆ | [hello-world-plugin](./examples/hello-world-plugin/) |
+| `parser` | Support for a new language | ★★☆ | [rust-parser](./examples/rust-parser/) |
+| `panel` | A side panel in the app UI | ★★☆ | (in progress) |
+| `layout` | A new graph layout algorithm | ★★★ | (in progress) |
+
+A plugin has exactly one type — pick the smallest one that fits. You
+can ship multiple plugins for different concerns.
+
+---
+
+## Anatomy of a plugin
+
+Every plugin is a folder containing **at least two files**:
+
+```
+my-plugin/
+├── manifest.json      ← metadata (id, name, type, permissions)
+└── main.js            ← entry point (theme.css for theme plugins)
+```
+
+That's it. No build step required (you can use plain JS), no `npm install`
+needed (the API surface is just a type definition for IDE support).
+
+---
+
+## Where plugins live
+
+filegraph3d looks for plugins in a per-user directory:
+
+| OS | Path |
+|---|---|
+| **macOS** | `~/Library/Application Support/FileGraph 3D/plugins/` |
+| **Windows** | `%APPDATA%\FileGraph 3D\plugins\` |
+| **Linux** | `~/.config/FileGraph 3D/plugins/` |
+
+You can open this folder from the app via **Settings → Appearance →
+Open plugin folder…**.
+
+Each plugin is its own subfolder. Restart filegraph3d after installing
+a plugin to pick it up.
+
+---
+
+## TypeScript support (optional)
+
+If you're using TypeScript, the types in `types.d.ts` give you full
+IntelliSense and compile-time checks:
+
+```sh
+npm install --save-dev @filegraph3d/plugin-api
+```
+
+```ts
+import type { Plugin } from '@filegraph3d/plugin-api'
+
+const plugin: Plugin = {
+  activate(ctx) {
+    ctx.log('hello from typescript')
+  }
+}
+export default plugin
+```
+
+You can also use plain JavaScript — the API works identically.
+
+---
+
+## License
+
+This API package: **MIT** — see [LICENSE](./LICENSE).
+
+You can publish your plugins under any license you like (MIT,
+Apache-2.0, proprietary, etc).
+
+The filegraph3d app itself: **AGPL-3.0** — see [`../LICENSE`](../LICENSE).
+Personal and internal use is free; commercial redistribution requires
+a license.

package/plugin-api/docs/01-getting-started.md

@@ -0,0 +1,197 @@
+# Getting started
+
+You'll build your first filegraph3d plugin in five minutes. We'll walk
+through two starter plugins — a **theme** (no JavaScript, just CSS)
+and an **action** (a context-menu item that runs code).
+
+## Prerequisites
+
+- filegraph3d installed and working
+- A text editor of any kind
+- That's it — no Node.js, no build tools, nothing to install
+
+## 1. Open your plugin folder
+
+In filegraph3d, click **Settings → Appearance → Open plugin folder…**.
+
+This opens (and creates if missing) the per-user plugin directory:
+
+| OS | Path |
+|---|---|
+| macOS | `~/Library/Application Support/FileGraph 3D/plugins/` |
+| Windows | `%APPDATA%\FileGraph 3D\plugins\` |
+| Linux | `~/.config/FileGraph 3D/plugins/` |
+
+## 2A. Track A — make a theme (the easiest plugin)
+
+Inside the plugin folder, create a new subfolder called `my-theme`:
+
+```
+plugins/
+└── my-theme/
+    ├── manifest.json
+    └── theme.css
+```
+
+**`manifest.json`:**
+
+```json
+{
+  "id": "my-theme",
+  "name": "My Theme",
+  "version": "1.0.0",
+  "author": "you",
+  "description": "My very first theme",
+  "type": "theme",
+  "main": "theme.css",
+  "minAppVersion": "0.10.0",
+  "license": "MIT"
+}
+```
+
+**`theme.css`:**
+
+```css
+body[data-theme="my-theme"] {
+  --bg:           #1F1B2E;
+  --bg-glass:     rgba(30, 25, 50, 0.85);
+  --fg:           #F0E8FF;
+  --fg-dim:       #C5B8E0;
+  --fg-mute:      #8B7DB0;
+
+  --border:       rgba(180, 120, 255, 0.18);
+  --border-hot:   rgba(180, 120, 255, 0.55);
+  --border-edge:  rgba(180, 120, 255, 0.06);
+
+  --accent:       #B478FF;    /* purple */
+  --accent-warm:  #FFB845;    /* warm gold */
+  --accent-pink:  #FF6B9F;
+  --accent-cool:  #78D9FF;
+
+  --decoration: 0;
+  --grain:      0.02;
+  --radius:     4px;
+}
+```
+
+That's everything. Now:
+
+1. **Quit filegraph3d completely** (Cmd/Ctrl+Q, not just close window).
+2. **Reopen** the app.
+3. Go to **Settings → Appearance**. You'll see "My Theme" in the
+   theme grid.
+4. Click it.
+
+The whole UI flips to your purple palette. You just made a theme.
+
+→ **For the full list of CSS variables and how to tune them, read
+the [theme guide](./types/theme.md).**
+
+## 2B. Track B — make an action plugin (your first JS plugin)
+
+Actions are the simplest code plugins. They add an item to the
+right-click menu on graph nodes.
+
+Create `plugins/my-action/`:
+
+**`manifest.json`:**
+
+```json
+{
+  "id": "my-action",
+  "name": "My Action",
+  "version": "1.0.0",
+  "author": "you",
+  "description": "Shows file info when you right-click a node",
+  "type": "action",
+  "main": "main.js",
+  "minAppVersion": "0.10.0",
+  "license": "MIT",
+  "permissions": ["context-menu", "read-graph"]
+}
+```
+
+**`main.js`:**
+
+```js
+export default {
+  activate(ctx) {
+    ctx.log('My Action plugin loaded')
+
+    ctx.ui.registerContextMenuItem({
+      label: 'Show info for this file',
+      icon: 'ℹ',
+      action: (nodeId) => {
+        const node = ctx.graph.getNode(nodeId)
+        if (!node) {
+          ctx.toast('Node not found')
+          return
+        }
+        const outs = ctx.graph.outgoing(nodeId).length
+        const ins  = ctx.graph.incoming(nodeId).length
+        ctx.toast(
+          `${nodeId}\n` +
+          `  ${node.loc} lines, ${node.size} bytes\n` +
+          `  imports ${outs}, used by ${ins}`
+        )
+      }
+    })
+  }
+}
+```
+
+Quit filegraph3d. Reopen. Open a folder. Right-click any node in the
+graph. You'll see "Show info for this file" in the menu. Click it.
+
+A toast pops up with the file's stats. You just made a code plugin.
+
+## What just happened
+
+Every plugin follows the same shape:
+
+1. **`manifest.json`** declares who the plugin is, what it does, and
+   what permissions it needs.
+2. **The entry file** (either `theme.css` for themes or `main.js` for
+   code plugins) is the actual implementation.
+3. **For code plugins**, the default export has an `activate(ctx)`
+   function. `ctx` is a curated API — see the
+   [API reference](./api-reference.md) for the full surface.
+
+## Hot reload (limitations)
+
+filegraph3d doesn't yet support hot-reload for plugins. Any change to
+a plugin requires **quitting and reopening the app**.
+
+A common workflow is:
+
+1. Edit the plugin file in your text editor.
+2. **Cmd/Ctrl+Q** to quit filegraph3d.
+3. Reopen the app — your plugin reloads with the changes.
+
+(Hot reload is on the roadmap; until then, the quit-restart cycle is
+fast — a few seconds.)
+
+## Next steps
+
+Now that you have a working plugin:
+
+- **[Concepts](./02-concepts.md)** — understand the plugin lifecycle,
+  manifest, and permission system in depth.
+- **[Theme guide](./types/theme.md)** — every CSS variable you can override.
+- **[Exporter guide](./types/exporter.md)** — add a new export format.
+- **[API reference](./api-reference.md)** — every method on `ctx`.
+- **[Troubleshooting](./troubleshooting.md)** — what to do when things break.
+
+## Got stuck?
+
+If your plugin doesn't show up:
+
+1. Check **Settings → Appearance → Open plugin folder…** is the actual
+   path you put files in.
+2. Make sure each plugin is in its own **subfolder** (not loose files).
+3. Make sure `manifest.json` is **valid JSON** — paste it into
+   `jsonlint.com` if unsure.
+4. Open **DevTools** (View → Toggle Developer Tools) and look at the
+   Console — plugin load errors are logged there.
+
+More in [troubleshooting](./troubleshooting.md).

package/plugin-api/docs/02-concepts.md

@@ -0,0 +1,269 @@
+# Concepts
+
+Once you've built [your first plugin](./01-getting-started.md), the
+pieces below explain why the system is shaped the way it is.
+
+- [Plugin types](#plugin-types)
+- [The manifest](#the-manifest)
+- [Lifecycle](#lifecycle)
+- [The `ctx` object](#the-ctx-object)
+- [Permissions](#permissions)
+- [Disposables](#disposables)
+- [Plugin storage](#plugin-storage)
+- [The event bus](#the-event-bus)
+
+## Plugin types
+
+A plugin has exactly one `type` declared in its manifest. The type
+determines what API surface the plugin gets and where its entry file
+lives.
+
+| Type | Entry file | What it adds |
+|---|---|---|
+| `theme` | `theme.css` | Visual theme (color variables, decorations) |
+| `exporter` | `main.js` | A new "Export As…" format |
+| `parser` | `main.js` | Support for a new file extension/language |
+| `layout` | `main.js` | A new graph layout algorithm |
+| `panel` | `main.js` | A side panel in the right rail |
+| `action` | `main.js` | A right-click item on graph nodes |
+
+Pick the smallest type that fits. If you want both a theme and a
+context-menu action, ship them as **two separate plugins**.
+
+## The manifest
+
+`manifest.json` is the only required file besides the entry. Every
+plugin must have one.
+
+### Required fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | string | Unique. Use kebab-case (`my-plugin`, not `My Plugin!`). Must match `[a-z0-9][a-z0-9-_]*`. |
+| `name` | string | Display name shown to users. |
+| `version` | string | Semver (`1.0.0`, `0.3.1`, etc.). |
+| `type` | string | One of the six plugin types above. |
+| `main` | string | Path to the entry file, relative to the plugin folder. |
+
+### Recommended fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `author` | string | Your name (no email required). Defaults to `"unknown"`. |
+| `description` | string | One-line summary shown in the plugin list. |
+| `minAppVersion` | string | Earliest filegraph3d version this plugin supports. |
+| `license` | string | SPDX identifier (`MIT`, `Apache-2.0`, etc.). |
+
+### Optional fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `homepage` | string | URL for the plugin's documentation or repo. |
+| `permissions` | string[] | What capabilities the plugin needs — see [Permissions](#permissions). |
+
+### Path safety
+
+`main` must point to a file **inside** the plugin folder. Paths
+containing `..` or absolute paths are rejected at load time. So
+`main: "../../etc/passwd"` won't work — and that's by design.
+
+### Example: a full manifest
+
+```json
+{
+  "id": "rust-parser",
+  "name": "Rust Parser",
+  "version": "1.0.0",
+  "author": "you",
+  "description": "Parse `use` statements from .rs files",
+  "type": "parser",
+  "main": "main.js",
+  "minAppVersion": "0.10.0",
+  "license": "MIT",
+  "homepage": "https://github.com/you/rust-parser",
+  "permissions": ["parse"]
+}
+```
+
+## Lifecycle
+
+Code plugins have two lifecycle hooks: `activate` and `deactivate`.
+
+```js
+export default {
+  activate(ctx) {
+    // Called once when the plugin is loaded.
+    // Register everything you need here.
+  },
+
+  deactivate() {
+    // Optional. Called when the plugin is unloaded.
+    // Clean up timers, intervals, custom DOM elements you created
+    // directly, etc.
+  }
+}
+```
+
+Right now, "loaded" means **the app started and discovered this plugin
+in the plugin folder**. There's no in-app enable/disable toggle yet
+(planned). So in practice `activate()` runs once at startup and
+`deactivate()` is mostly a forward-compatible hook.
+
+### What `activate` should do
+
+- Register handlers (`ctx.ui.registerContextMenuItem`, etc.)
+- Subscribe to events (`ctx.events.on`)
+- Set up timers if needed
+- Store an unsubscribe handle so `deactivate` can clean up
+
+### What `activate` should NOT do
+
+- **Don't** do heavy work synchronously — it blocks app startup.
+- **Don't** read large files or scan directories — defer to user
+  interaction.
+- **Don't** throw — the app catches it, but the plugin won't load.
+
+### Theme plugins
+
+Themes don't have lifecycle hooks. They're just CSS, injected once at
+startup. Override the `body[data-theme="your-id"]` selector and you're
+done.
+
+## The `ctx` object
+
+Every `activate(ctx)` call receives a context object. It's the only
+way a plugin should talk to the app — don't reach into `window`
+globals or DOM internals, those aren't stable across versions.
+
+```js
+ctx.manifest      // your own manifest (handy for version checks)
+ctx.appVersion    // host filegraph3d version
+
+ctx.graph         // read-only access to nodes/edges/selection
+ctx.ui            // register UI: panels, context-menu items, commands
+ctx.exporters     // register export formats
+ctx.parsers       // register language parsers
+ctx.layouts       // register layout algorithms
+ctx.events        // subscribe to app events (selection, snapshot, etc.)
+
+ctx.storage       // persistent per-plugin key-value store
+ctx.toast(msg)    // show user a notification
+ctx.log(...args)  // log to plugin console (prefixed with plugin id)
+```
+
+For each property's full surface, see the
+[API reference](./api-reference.md).
+
+## Permissions
+
+Plugins must declare what they need in `manifest.permissions`. Attempting
+to call an API without the matching permission throws an error.
+
+| Permission | Required for |
+|---|---|
+| `read-files` | `ctx.graph.readFile(id)` |
+| `read-graph` | Always granted (nodes/edges access). Declaring it is good form. |
+| `modify-graph` | Reserved for future use (adding nodes/edges from plugins). |
+| `ui-panel` | `ctx.ui.registerPanel(...)` |
+| `context-menu` | `ctx.ui.registerContextMenuItem(...)` |
+| `export` | `ctx.exporters.register(...)` |
+| `parse` | `ctx.parsers.register(...)` |
+
+### Why bother?
+
+Two reasons:
+
+1. **Self-documentation.** Anyone reading your manifest knows what the
+   plugin can do without reading the code.
+2. **Future-proofing.** filegraph3d may eventually show a permission
+   prompt to users before enabling a plugin (Obsidian and VS Code both
+   have similar mechanisms). Declaring permissions now means your
+   plugin won't break when that lands.
+
+### Example
+
+```json
+{
+  "id": "my-plugin",
+  ...
+  "permissions": ["read-files", "context-menu"]
+}
+```
+
+This plugin can read file contents and add right-click items. It
+cannot register an exporter or a panel — if it tries, `ctx.exporters.
+register(...)` throws.
+
+## Disposables
+
+Several API methods return a `{ dispose() }` handle. Calling `dispose()`
+removes the registration.
+
+```js
+const panel = ctx.ui.registerPanel({
+  id: 'my-panel',
+  title: 'My Panel',
+  render(container) { container.textContent = 'hello' }
+})
+
+// Later, if you want to remove the panel:
+panel.dispose()
+```
+
+If you don't dispose explicitly, the app does it for you when the
+plugin is unloaded. But if your plugin shows/hides UI based on state,
+you'll want to call `dispose()` yourself.
+
+## Plugin storage
+
+Each plugin gets a private key-value store backed by `localStorage`:
+
+```js
+ctx.storage.set('lastSelection', { nodeId: 'src/index.js', at: Date.now() })
+
+// Next time the plugin loads:
+const last = ctx.storage.get('lastSelection')
+if (last) ctx.log(`Last selection was ${last.nodeId}`)
+```
+
+Keys are namespaced per plugin id — you can't accidentally clash with
+another plugin or with the app itself.
+
+Values must be JSON-serializable. Don't put DOM nodes, functions, or
+circular structures in there.
+
+## The event bus
+
+Plugins can subscribe to app-level events. These fire whenever the
+relevant state changes.
+
+| Event | When it fires | Payload |
+|---|---|---|
+| `snapshot:applied` | New graph data loaded (folder opened or rescanned) | `{ root: string }` |
+| `selection:changed` | User clicked a node or selected something | `string \| null` (node id) |
+| `filter:changed` | Search text or filter state changed | (no payload) |
+| `focus:changed` | Hovered/focused node changed | `string \| null` |
+| `graph:cleared` | Folder was closed | (no payload) |
+| `activeset:changed` | User starred a file or toggled a pipeline | (no payload) |
+
+```js
+const off = ctx.events.on('selection:changed', (nodeId) => {
+  if (nodeId) ctx.log('user picked', nodeId)
+})
+
+// Unsubscribe:
+off()
+```
+
+`ctx.events.on()` returns an unsubscribe function. Save it and call it
+from `deactivate()`, or it'll keep firing after your plugin is gone.
+
+## What's next
+
+You now know enough to build any plugin type. The next docs are
+type-specific:
+
+- [Theme guide](./types/theme.md)
+- [Exporter guide](./types/exporter.md)
+- [API reference](./api-reference.md) — the precise surface
+- [Troubleshooting](./troubleshooting.md) — when things go wrong