codesynapt 0.0.0

package/plugin-api/examples/rust-parser/main.js

@@ -0,0 +1,123 @@
+// Rust parser plugin for filegraph3d.
+//
+// Recognizes:
+//   - `use path::to::thing;`  → an import to "path::to::thing"
+//   - `mod foo;`              → an import to the sibling/child module
+//   - `extern crate foo;`     → an import to the named crate
+//
+// Skips:
+//   - Statements inside line comments (`// use foo`)
+//   - Statements inside block comments (`/* use foo */`)
+//   - Use statements inside macro definitions (rare, would need a
+//     real parser; we accept some false positives)
+
+export default {
+  activate(ctx) {
+    ctx.parsers.register({
+      name: 'Rust',
+      extensions: ['rs'],
+      parse(filePath, content) {
+        // Strip comments first so we don't match `use` statements
+        // that are commented out.
+        const stripped = stripComments(content)
+
+        const imports = []
+
+        // `use path::to::thing;` — match the path portion only.
+        // Groups, aliases, and wildcards complicate this; we capture
+        // the leading path which is enough for graph edges.
+        const useRegex = /^\s*(?:pub\s+)?use\s+([a-zA-Z_][\w:]*)/gm
+        let m
+        while ((m = useRegex.exec(stripped)) !== null) {
+          imports.push({
+            path: m[1],
+            kind: 'import',
+            line: lineNumberAt(stripped, m.index),
+          })
+        }
+
+        // `mod foo;` — local module declaration
+        const modRegex = /^\s*(?:pub\s+)?mod\s+([a-zA-Z_]\w*)\s*;/gm
+        while ((m = modRegex.exec(stripped)) !== null) {
+          imports.push({
+            path: m[1],
+            kind: 'import',
+            line: lineNumberAt(stripped, m.index),
+          })
+        }
+
+        // `extern crate foo;` — older crate import syntax
+        const externRegex = /^\s*extern\s+crate\s+([a-zA-Z_]\w*)/gm
+        while ((m = externRegex.exec(stripped)) !== null) {
+          imports.push({
+            path: m[1],
+            kind: 'import',
+            line: lineNumberAt(stripped, m.index),
+          })
+        }
+
+        return { imports }
+      }
+    })
+
+    ctx.log('Rust parser registered — .rs files will now be parsed')
+  }
+}
+
+// Replace comments with spaces so regex line numbers stay accurate
+function stripComments(src) {
+  let result = ''
+  let i = 0
+  while (i < src.length) {
+    // Line comment: //...\n
+    if (src[i] === '/' && src[i + 1] === '/') {
+      while (i < src.length && src[i] !== '\n') {
+        result += ' '
+        i++
+      }
+      continue
+    }
+    // Block comment: /* ... */ (non-nested; Rust allows nested but
+    // for our purposes flat handling is sufficient)
+    if (src[i] === '/' && src[i + 1] === '*') {
+      result += '  '
+      i += 2
+      while (i < src.length - 1 && !(src[i] === '*' && src[i + 1] === '/')) {
+        result += src[i] === '\n' ? '\n' : ' '
+        i++
+      }
+      result += '  '
+      i += 2
+      continue
+    }
+    // String literal — skip past it so `use` inside strings doesn't
+    // produce a false positive
+    if (src[i] === '"') {
+      result += '"'
+      i++
+      while (i < src.length && src[i] !== '"') {
+        if (src[i] === '\\' && i + 1 < src.length) {
+          result += '  '
+          i += 2
+          continue
+        }
+        result += src[i] === '\n' ? '\n' : ' '
+        i++
+      }
+      result += '"'
+      i++
+      continue
+    }
+    result += src[i]
+    i++
+  }
+  return result
+}
+
+function lineNumberAt(str, offset) {
+  let line = 1
+  for (let i = 0; i < offset && i < str.length; i++) {
+    if (str[i] === '\n') line++
+  }
+  return line
+}

package/plugin-api/examples/rust-parser/manifest.json

@@ -0,0 +1,12 @@
+{
+  "id": "rust-parser",
+  "name": "Rust Parser",
+  "version": "1.0.0",
+  "author": "filegraph3d",
+  "description": "Parse Rust `use` statements and mod declarations to build the dependency graph",
+  "type": "parser",
+  "main": "main.js",
+  "minAppVersion": "0.10.0",
+  "license": "MIT",
+  "permissions": ["parse"]
+}

package/plugin-api/examples/sunset-theme/README.md

@@ -0,0 +1,95 @@
+# sunset-theme
+
+A warm coral-orange theme inspired by sunset over the ocean. Useful
+as a starting point for your own theme plugin — copy and modify.
+
+## What it looks like
+
+| Element | Color |
+|---|---|
+| Background | Deep brown `#1A0F0A` |
+| Foreground | Cream `#FFE4C4` |
+| Primary accent | Warm orange `#FF8C42` |
+| Active set color | Amber `#FFB347` |
+| Warning color | Coral red `#FF6B6B` |
+
+The theme uses 4px rounded corners and no decorative corner brackets,
+giving it a softer feel than the default Observatory theme.
+
+## 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 **Settings → Appearance** — "Sunset"
+appears in the theme grid. Click it.
+
+## Files
+
+- **`manifest.json`** — declares the plugin as type `theme`. Theme
+  plugins don't need any permissions because they only contribute CSS.
+
+- **`theme.css`** — overrides CSS variables under the
+  `body[data-theme="sunset-theme"]` selector. The selector value
+  matches the `id` in the manifest.
+
+## What to change
+
+Open `theme.css` and tweak. Some easy starting points:
+
+### Different color family
+
+The whole theme is built around `--accent: #FF8C42`. Swap that for any
+other hue and pick three colors that:
+
+- `--bg`: a deep version of (or complement to) the accent
+- `--fg`: a light tint of the accent or a neutral
+- `--accent-warm`: a brighter sibling color
+- `--accent-pink`: contrast color for warnings
+
+### Add corner brackets
+
+```css
+body[data-theme="sunset-theme"] {
+  --decoration: 1;   /* show corner brackets on panels */
+}
+```
+
+### Make it brutalist
+
+```css
+body[data-theme="sunset-theme"] {
+  --decoration: 1;
+  --radius:     0;   /* sharp corners */
+}
+```
+
+### Lighter background
+
+If you want a "sunrise" version instead:
+
+```css
+body[data-theme="sunset-theme"] {
+  --bg:        #FFF4E6;
+  --fg:        #4A2810;
+  --grain:     0;
+  /* ... and adjust borders/accents accordingly */
+}
+body[data-theme="sunset-theme"]::before {
+  opacity: 0 !important;   /* turn off the dark-mode grain */
+}
+```
+
+## License
+
+MIT — fork, modify, redistribute freely.
+
+## More
+
+For the complete list of CSS variables and theming guidance, see
+[../../docs/types/theme.md](../../docs/types/theme.md).

package/plugin-api/examples/sunset-theme/manifest.json

@@ -0,0 +1,12 @@
+{
+  "id": "sunset-theme",
+  "name": "Sunset",
+  "version": "1.0.0",
+  "author": "filegraph3d",
+  "description": "Warm orange-coral theme inspired by sunset over the ocean",
+  "type": "theme",
+  "main": "theme.css",
+  "minAppVersion": "0.10.0",
+  "license": "MIT",
+  "permissions": []
+}

package/plugin-api/examples/sunset-theme/theme.css

@@ -0,0 +1,31 @@
+/* Sunset theme — warm coral/orange palette */
+/* Loaded automatically when user selects "Sunset" in Appearance */
+
+body[data-theme="sunset-theme"] {
+  --bg:           #1A0F0A;
+  --bg-deep:      #100805;
+  --bg-elev:      rgba(40, 22, 14, 0.85);
+  --bg-glass:     rgba(26, 15, 10, 0.85);
+  --bg-solid:     #261810;
+
+  --border:       rgba(255, 140, 66, 0.18);
+  --border-hot:   rgba(255, 140, 66, 0.55);
+  --border-edge:  rgba(255, 140, 66, 0.06);
+
+  --fg:           #FFE4C4;
+  --fg-dim:       #D8B080;
+  --fg-mute:      #A88060;
+  --fg-faint:     #685040;
+
+  --accent:       #FF8C42;     /* warm orange */
+  --accent-warm:  #FFB347;     /* amber */
+  --accent-pink:  #FF6B6B;     /* coral red */
+  --accent-cool:  #E8A87C;     /* dusty rose */
+  --danger:       #FF4444;
+
+  --decoration:   0;
+  --grain:        0.03;
+  --motion-scale: 0.6;
+
+  --radius:       4px;
+}

package/plugin-api/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@filegraph3d/plugin-api",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "TypeScript types and helpers for filegraph3d plugins",
+  "types": "types.d.ts",
+  "files": [
+    "types.d.ts",
+    "README.md",
+    "LICENSE",
+    "examples/"
+  ],
+  "license": "MIT",
+  "keywords": ["filegraph3d", "plugin", "api", "code-visualization"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YOUR_USER/filegraph3d.git",
+    "directory": "plugin-api"
+  }
+}

package/plugin-api/types.d.ts

@@ -0,0 +1,395 @@
+// @filegraph3d/plugin-api — public API surface for plugins
+// MIT licensed — free to use, fork, distribute.
+
+/* ════════════════════════════════════════════════════════════
+   Plugin manifest
+   ════════════════════════════════════════════════════════════ */
+
+export interface PluginManifest {
+  /** Unique identifier (kebab-case, e.g. "tokyo-night-theme") */
+  id: string
+
+  /** Display name */
+  name: string
+
+  /** Plugin version (semver) */
+  version: string
+
+  /** Author name (no email required) */
+  author: string
+
+  /** One-line description shown in plugin list */
+  description: string
+
+  /** Plugin type — determines what API surface it gets */
+  type: 'theme' | 'exporter' | 'parser' | 'layout' | 'panel' | 'action'
+
+  /**
+   * Entry point file (relative to manifest.json):
+   * - For theme: a .css file
+   * - For others: a .js module
+   */
+  main: string
+
+  /** Minimum filegraph3d app version (semver range) */
+  minAppVersion: string
+
+  /** SPDX license identifier (MIT, Apache-2.0, etc) */
+  license: string
+
+  /** Optional URL for the plugin homepage / repo */
+  homepage?: string
+
+  /** Optional: which app capabilities does this plugin need? */
+  permissions?: PluginPermission[]
+}
+
+export type PluginPermission =
+  | 'read-files'        // Read source file contents
+  | 'read-graph'        // Read the current node/edge state
+  | 'modify-graph'      // Add nodes/edges (rare, dangerous)
+  | 'ui-panel'          // Render in a side panel
+  | 'context-menu'      // Add right-click items
+  | 'export'            // Provide an export format
+  | 'parse'             // Provide a language parser
+
+/* ════════════════════════════════════════════════════════════
+   Plugin context — passed to every plugin's activate() function
+   ════════════════════════════════════════════════════════════ */
+
+export interface PluginContext {
+  /** This plugin's manifest */
+  manifest: PluginManifest
+
+  /** App version at load time */
+  appVersion: string
+
+  /** Read-only access to graph state */
+  graph: GraphAPI
+
+  /** UI registration */
+  ui: UIAPI
+
+  /** Export format registration */
+  exporters: ExporterRegistry
+
+  /** Parser registration */
+  parsers: ParserRegistry
+
+  /** Layout algorithm registration */
+  layouts: LayoutRegistry
+
+  /** Event subscription */
+  events: EventBus
+
+  /** Persistent per-plugin storage (localStorage-backed) */
+  storage: PluginStorage
+
+  /** Helper: show a toast message */
+  toast: (message: string) => void
+
+  /** Helper: log to plugin-specific console */
+  log: (...args: unknown[]) => void
+}
+
+/* ════════════════════════════════════════════════════════════
+   Graph API
+   ════════════════════════════════════════════════════════════ */
+
+export interface GraphNode {
+  /** File path relative to project root */
+  id: string
+
+  /** File extension (without dot) */
+  ext: string
+
+  /** File size in bytes */
+  size: number
+
+  /** Lines of code */
+  loc: number
+
+  /** Display color (hex) */
+  hex: string
+}
+
+export interface GraphEdge {
+  /** Source node id */
+  s: string
+
+  /** Target node id */
+  t: string
+
+  /** Edge kind: 'import' | 'require' | 'css' | etc */
+  k: string
+}
+
+export interface GraphAPI {
+  /** Current project root path */
+  readonly root: string
+
+  /** All nodes (read-only) */
+  readonly nodes: ReadonlyArray<GraphNode>
+
+  /** All edges (read-only) */
+  readonly edges: ReadonlyArray<GraphEdge>
+
+  /** Currently selected node id (or null) */
+  readonly selectedId: string | null
+
+  /** Currently active set of file ids (or null if disabled) */
+  readonly activeSet: ReadonlySet<string> | null
+
+  /** Read file contents (requires "read-files" permission) */
+  readFile(id: string): Promise<string>
+
+  /** Get node by id, or null */
+  getNode(id: string): GraphNode | null
+
+  /** Get all outgoing edges from a node */
+  outgoing(id: string): GraphEdge[]
+
+  /** Get all incoming edges to a node */
+  incoming(id: string): GraphEdge[]
+}
+
+/* ════════════════════════════════════════════════════════════
+   UI API
+   ════════════════════════════════════════════════════════════ */
+
+export interface UIAPI {
+  /**
+   * Register a panel that appears in the right rail.
+   * Returns a handle for later removal.
+   */
+  registerPanel(opts: PanelOptions): PanelHandle
+
+  /**
+   * Register a context-menu item that appears when right-clicking
+   * a node in the graph.
+   */
+  registerContextMenuItem(opts: ContextMenuOptions): MenuItemHandle
+
+  /**
+   * Register a command (shows up in command palette if available).
+   */
+  registerCommand(opts: CommandOptions): CommandHandle
+}
+
+export interface PanelOptions {
+  /** Unique id within this plugin */
+  id: string
+
+  /** Title shown in panel header */
+  title: string
+
+  /** Position (default: 'right') */
+  position?: 'right' | 'left' | 'bottom'
+
+  /**
+   * Render function — return HTML string or DOM element.
+   * Called when the panel becomes visible or when refresh() is called.
+   */
+  render: (container: HTMLElement) => void
+
+  /** Whether the panel is visible by default */
+  defaultVisible?: boolean
+}
+
+export interface PanelHandle {
+  /** Force re-render */
+  refresh(): void
+
+  /** Show the panel */
+  show(): void
+
+  /** Hide the panel */
+  hide(): void
+
+  /** Remove the panel entirely */
+  dispose(): void
+}
+
+export interface ContextMenuOptions {
+  /** Display label */
+  label: string
+
+  /** Optional icon (single character or short string) */
+  icon?: string
+
+  /** When to show — return true to enable */
+  enabled?: (nodeId: string) => boolean
+
+  /** Click handler */
+  action: (nodeId: string) => void | Promise<void>
+}
+
+export interface MenuItemHandle {
+  dispose(): void
+}
+
+export interface CommandOptions {
+  /** Unique command id */
+  id: string
+
+  /** Display name in command palette */
+  name: string
+
+  /** Optional keyboard shortcut suggestion */
+  shortcut?: string
+
+  /** Handler */
+  action: () => void | Promise<void>
+}
+
+export interface CommandHandle {
+  dispose(): void
+}
+
+/* ════════════════════════════════════════════════════════════
+   Exporter registration
+   ════════════════════════════════════════════════════════════ */
+
+export interface ExporterRegistry {
+  register(opts: ExporterOptions): ExporterHandle
+}
+
+export interface ExporterOptions {
+  /** Display name (e.g. "Mermaid diagram") */
+  name: string
+
+  /** File extension (e.g. "mmd") */
+  extension: string
+
+  /** MIME type for the download */
+  mimeType: string
+
+  /**
+   * Generate the export content.
+   * Receives the current graph state and returns the file content.
+   */
+  generate: (graph: GraphAPI) => string | Promise<string>
+}
+
+export interface ExporterHandle {
+  dispose(): void
+}
+
+/* ════════════════════════════════════════════════════════════
+   Parser registration
+   ════════════════════════════════════════════════════════════ */
+
+export interface ParserRegistry {
+  register(opts: ParserOptions): ParserHandle
+}
+
+export interface ParserOptions {
+  /** Language name (e.g. "Rust") */
+  name: string
+
+  /** File extensions this parser handles (without dot) */
+  extensions: string[]
+
+  /**
+   * Parse a file and return its imports.
+   * Resolution from import path to file id is done by the app.
+   */
+  parse: (filePath: string, content: string) => ParseResult
+}
+
+export interface ParseResult {
+  /** Import statements found in this file */
+  imports: ParseImport[]
+
+  /** Optional: lines of code count (if not given, app counts newlines) */
+  loc?: number
+}
+
+export interface ParseImport {
+  /** The raw import path (e.g. "./foo", "react", "@/utils") */
+  path: string
+
+  /** Import kind */
+  kind: 'import' | 'require' | 'dynamic' | 'css' | 'asset' | 'other'
+
+  /** Source line number (optional, for debugging) */
+  line?: number
+}
+
+export interface ParserHandle {
+  dispose(): void
+}
+
+/* ════════════════════════════════════════════════════════════
+   Layout algorithm registration
+   ════════════════════════════════════════════════════════════ */
+
+export interface LayoutRegistry {
+  register(opts: LayoutOptions): LayoutHandle
+}
+
+export interface LayoutOptions {
+  /** Display name (e.g. "Hierarchical") */
+  name: string
+
+  /** Unique id */
+  id: string
+
+  /**
+   * Compute positions for all nodes.
+   * Called once when this layout is activated, then again whenever
+   * the graph topology changes.
+   *
+   * Should return a Map from node id to {x, y, z} coordinates.
+   */
+  compute: (nodes: ReadonlyArray<GraphNode>, edges: ReadonlyArray<GraphEdge>)
+    => Map<string, { x: number; y: number; z: number }>
+    | Promise<Map<string, { x: number; y: number; z: number }>>
+}
+
+export interface LayoutHandle {
+  dispose(): void
+}
+
+/* ════════════════════════════════════════════════════════════
+   Event bus
+   ════════════════════════════════════════════════════════════ */
+
+export type EventName =
+  | 'snapshot:applied'      // New graph data loaded — { root: string }
+  | 'selection:changed'     // User selected a node — string | null
+  | 'filter:changed'        // Filter text changed
+  | 'focus:changed'         // Focused node changed
+  | 'graph:cleared'         // Graph was cleared
+  | 'activeset:changed'     // Active set updated
+
+export interface EventBus {
+  on<T = unknown>(event: EventName, handler: (payload: T) => void): () => void
+  off(event: EventName, handler: (payload: unknown) => void): void
+}
+
+/* ════════════════════════════════════════════════════════════
+   Plugin storage (persistent per-plugin key-value store)
+   ════════════════════════════════════════════════════════════ */
+
+export interface PluginStorage {
+  get<T = unknown>(key: string): T | null
+  set<T = unknown>(key: string, value: T): void
+  delete(key: string): void
+  clear(): void
+  keys(): string[]
+}
+
+/* ════════════════════════════════════════════════════════════
+   Plugin entry-point signature
+   ════════════════════════════════════════════════════════════ */
+
+/**
+ * Every plugin's main module must default-export an object with at
+ * least an `activate` function. `deactivate` is optional, called when
+ * the user disables or uninstalls the plugin.
+ */
+export interface Plugin {
+  activate(ctx: PluginContext): void | Promise<void>
+  deactivate?(): void | Promise<void>
+}