Plugin Development Workflow

This guide covers advanced development workflows: selecting starter templates, checking host compatibility, interacting with .eidos SQLite database packages, building dynamic table action providers, creating standalone themes, and publishing bundles.

1. Choose a Scaffold Template

The official tooling provides templates tailored for different development scenarios:

# List all available templates
npx @eidos.space/plugin-tools templates

# Create a project with a specific template
npx @eidos.space/plugin-tools create my-plugin --template file-view

# Or use the eidos CLI (equivalent command)
eidos plugin create my-plugin --template file-view

cd my-plugin
npm install
npm run check

Template	Target Scenario	Core Capabilities & APIs
file-view (Recommended)	Custom views for physical files (Open with menu)	`context: "file"`, `ctx.file`, `ctx.fs`, optional React UI
table-view	Internal table views (New view inside a table)	`context: "table"`, `ctx.table` record queries & SQLite aggregation
table-action	Batch operations on table records (Table context menu)	`registerTableProvider`, task progress, and read-token safe updates
page	Standalone top-level panels (Sidebar navigation)	`context: "page"`, `navigation`, `workspace.files`
theme	Eidos Lite host appearance customization	`kind: "theme"`, semantic color palettes, offline embedded fonts

2. Check Host Compatibility

Eidos Lite and CLI Serve support different scopes of plugin features. Before releasing, run static compatibility checks using the built-in toolchain:

# Perform full verification against Eidos Lite Desktop
npm run check -- --target lite

# Perform verification against Eidos CLI Serve Web
npm run check -- --target cli

# Output JSON diagnostics (ideal for CI/CD integration)
npm run check -- --json

Host Profile	Supported Scope
Eidos Lite (Desktop)	Full capability support: File Views, Page Views, Table Views, Actions, Formatters, full `ctx.fs` primitives, private storage, controlled network, and standalone host themes.
Eidos CLI (Serve Web)	Focused on table visualization: Table Views, declared Web Workers, and browser network origins.

Executable plugins for the current Eidos Lite must declare API 2.0.0:

{
  "requires": { "pluginApi": "2.0.0" }
}

API 1.x executable plugins must migrate file access to ctx.fs, navigation to ctx.ui.openFile, and Space permissions to workspace.files. Old resource declarations and Markdown-specific helpers are no longer supported. Installed incompatible plugins remain visible and removable. Pure API 1.6.0 themes remain compatible. CLI Serve continues to use API 1.0.0 for its table-only scope.

3. Working with `.eidos` Data Files

When a plugin view opens an .eidos file, the ctx.eidos interface allows you to inspect tables, read field schemas, and persist table-level configuration:

// 1. List all tables contained in the current .eidos file
const tables = await ctx.eidos.listTables()

// 2. Read field definitions and metadata for a specific table
const { fields } = await ctx.eidos.readTable(tables[0].id)

// 3. Read the plugin's persistent private configuration stored on the table
const config = await ctx.eidos.readPluginConfig(tables[0].id)

// 4. Safely save table configuration with optimistic concurrency (moves and syncs with the .eidos file)
await ctx.eidos.writePluginConfig(tables[0].id, {
  value: { customFilter: "status = 'done'" },
  expectedVersion: config.version,
})

4. Dynamic Table Actions (`registerTableProvider`)

For workflows requiring deep integration with table context menus or bulk record processing, register a dynamic table action provider during extension activation:

Declare the action in plugin.json:

{
  "extension": "./src/extension.ts",
  "actions": [
    {
      "id": "batch-processor",
      "title": "Batch Process Records",
      "context": "table",
      "access": "write"
    }
  ],
  "placements": [
    { "location": "table/context", "action": "batch-processor" }
  ]
}

Implement the provider in src/extension.ts:

import type { ExtensionContext, TableActionProvider } from "@eidos.space/plugin-sdk"

export default function activate(ctx: ExtensionContext) {
  const provider: TableActionProvider = {
    // Dynamically produce menu items
    getItems({ table, signal }) {
      return [
        {
          id: "uppercase-names",
          title: "Convert Selected Text to Uppercase",
          targets: ["row", "selection"],
        },
      ]
    },

    // Execute the selected action item
    async run(actionCtx, itemId) {
      const { target, task, signal } = actionCtx

      // 1. Read target rows in batches with read tokens
      const rows = await target.read({ offset: 0, limit: 100, fields: ["name"] })

      // 2. Declare sample output fields (Lite applies directly)
      await task.preview(rows)

      // 3. Update records in a loop
      for (let i = 0; i < rows.length; i++) {
        signal.throwIfAborted()
        const row = rows[i]
        const currentName = String(row.values["name"] || "")

        await target.update({
          readToken: row.readToken,
          values: { name: currentName.toUpperCase() },
        })

        // Report task progress to the host UI
        await task.report({
          completed: i + 1,
          message: `Processing row ${i + 1}/${rows.length}...`,
        })
      }
    },
  }

  const registration = ctx.actions.registerTableProvider("batch-processor", provider)
  ctx.subscriptions.add(registration)
}

5. Build Standalone Eidos Lite Themes

Beyond functional plugins, you can create theme packages that customize the entire desktop host interface:

npx @eidos.space/plugin-tools create my-theme --template theme
cd my-theme
npm run check -- --target lite
npm run pack:plugin

Define semantic light and dark variables in theme.css:

:root[data-theme="light"] {
  --theme-surface: #f7f8fa;
  --theme-ink: #19212b;
  --theme-accent: #2563eb;
  --lite-sidebar: #f1f3f7;
  --control-radius: 8px;
}

:root[data-theme="dark"] {
  --theme-surface: #181d24;
  --theme-ink: #eef2f6;
  --theme-accent: #3b82f6;
  --lite-sidebar: #13171c;
  --control-radius: 8px;
}

Semantic token coverage: Surface backgrounds, text colors, accent highlights, sidebar styling, control radius, and typography tokens.
Offline embedded fonts: Use @font-face to declare local .woff2 or .ttf font files; packing automatically inlines them as Base64 Data URLs.
Pure static & secure: Theme packages contain zero executable JavaScript code. Once installed, users can activate the theme globally in Eidos Lite settings.

6. View Styling & Design System Variables

When styling custom view interfaces, use the injected design system CSS variables to blend seamlessly with the user’s active theme:

.viewer-container {
  background-color: var(--eidos-background);
  color: var(--eidos-foreground);
  font-family: var(--eidos-font-family, system-ui);
  border: 1px solid var(--eidos-border);
}

button.primary {
  background-color: var(--eidos-accent);
  color: #ffffff;
  border-radius: var(--eidos-control-radius, 6px);
}

7. Debugging, Testing, and Publishing

Structured diagnostics: Run npm run check to instantly catch missing declarations, unmapped entry points, or TypeScript errors.
Live hot-reload debugging: In the Eidos Lite toolbar, click Plugins → Load development source… and select your project directory. Code edits hot-reload automatically within seconds upon saving.
Packaging for distribution: Run npm run pack:plugin to produce a self-contained .eidos-plugin bundle and its SHA-256 checksum in dist/. The archive can be shared directly with users or submitted to the official plugin registry.