Plugin Concepts

Eidos plugins are sandboxed modules that extend Eidos Lite with custom file editors and viewers, independent panels, keyboard commands, and table visualizations.

Before building a plugin, familiarize yourself with these core concepts:

1. Spaces and Files

Eidos operates directly on your local filesystem and organizes content across two levels:

Space (Workspace): The root folder of an opened project or vault. Plugins can add navigation pages to the sidebar or register global commands.
File: Any physical file within the Space (e.g. .md, .csv, .png, .mp4, or .eidos). Plugins can provide custom views or actions for specific file extensions.
- .eidos Files: Structured SQLite database packages that contain one or more data tables (Tables) and view configurations.

2. Plugin Capabilities

Plugins declare their capabilities in the plugin.json manifest:

Views

Views are visual interfaces embedded in Eidos Lite, built using standard frontend libraries (React, Vue, or vanilla DOM):

File Views (context: "file"): Custom editors or viewers for specific file extensions, accessed via the file’s Open with menu.
Independent Pages (context: "page"): Standalone application dashboards or panels, accessible from the Space’s left sidebar navigation.
Table Views (context: "table"): Custom visualizations embedded inside an .eidos data table (e.g. charts, kanban boards, calendars, or maps).

Actions

Actions are executable commands or background tasks triggered via shortcuts or context menus:

Global Actions (context: "workspace"): Registered in the global Command Palette (Cmd+K / Ctrl+K).
File Actions (context: "file"): Added to the context menu of files in the file explorer.
Table Actions (context: "table"): Added to the context menu of tables or record selections for batch processing.

Themes

Theme packages (kind: "theme") customize the light and dark appearance of the entire Eidos Lite host interface using semantic CSS variables.

3. The Context Object (`ctx`) & File Contributions

When Eidos Lite mounts a view or runs an action, it passes a context object ctx to the entry function.

Base Capabilities

All views and actions have access to a set of core capabilities on ctx:

Property	Type	Description
`ctx.fs`	`PluginFileSystem`	Complete filesystem access: read/write text and binary files, list directories, rename, delete, watch file changes, and obtain streaming media URLs.
`ctx.storage`	`PluginStorage`	Isolated persistent key-value storage for plugin data.
`ctx.network`	`PluginNetwork`	Make restricted HTTPS requests to domains declared in the manifest.
`ctx.settings`	`PluginSettings`	Read, update, and observe user-configured settings for the plugin.
`ctx.ui`	`HostUI`	Interact with the host: display toast notifications, show confirmation dialogues, open pickers, open files, and navigate routes.
`ctx.signal`	`AbortSignal`	Automatically aborts pending async work when the view unmounts or action is cancelled.
`ctx.subscriptions`	`SubscriptionDisposer`	Disposer collection for event listeners and timers, automatically cleaned up on unmount.

Specialized Interfaces & File Contribution Points

When targeting a physical file, all file views have access to ctx.file for file path, name, and size. In addition, specific file types have specialized context objects and contribution points:

Text Documents (.md, .txt, .csv, etc.):
- Specialized Interface ctx.editor: Document reading, draft editing, saving, and external conflict detection.
- Special Contribution Point: Formatters (formatters): A specialized contribution point for text files declared in the manifest formatters array and implemented via ctx.formatters.register, hooked directly into the system’s Format Document command (Shift+Alt+F / Cmd+K).
.eidos Database Files:
- Specialized Interfaces ctx.table & ctx.eidos: Table discovery, schema inspection, paginated row queries, and SQLite server-side aggregation.
- Special Contribution Points: Embedded table views (table/view) and dynamic batch actions for table records (table/context).

4. UI Placements (`placements`)

The placements array defines where your plugin’s views and actions appear in the Eidos Lite UI:

Location (`location`)	Target	Context Requirement	Description
`"file/open"`	View	`context: "file"`	Registered under the file’s Open with context menu.
`"navigation"`	View	`context: "page"`	Appears as a top-level page in the Space sidebar navigation.
`"plugin/settings"`	View	`context: "page"`	Embedded in the plugin’s details page within Settings.
`"table/view"`	View	`context: "table"`	Appears in the table’s view switcher menu (e.g. New View).
`"command-palette"`	Action	`context: "workspace" \| "file"`	Registered in the Command Palette (`Cmd`+`K` / `Ctrl`+`K`).
`"file/context"`	Action	`context: "file"`	Appears in the context menu for files in the file explorer.
`"table/context"`	Action	`context: "table"`	Appears in the context menu for table records or row selections.
`"view/toolbar"`	Action	Matches view context	Added to the header toolbar of a specific view.
`"keybinding"`	Action	Target action	Binds a custom keyboard shortcut to trigger the action.
`"Format Document"`	Formatter	`formatters`	Specialized formatting contribution point for text files, hooked into Format Document commands and shortcuts.