Plugin system

[ampelectrecuted]

ide-shell is being built using plugins. There will be:

• Core plugins (things that always run no matter what)
• Custom plugins (you can register them manually)

There is already a primitive implementation, but how can we improve it?

[traycerai]

Plan

Observations

The current plugin system in ide-shell is primitive but functional. It uses React Context (LayoutProvider) for plugin registration, supports UI panels (left/center/bottom) and status bar items, and exposes a global API via window.omniCore and window.omniLayout. The implementation lacks formal plugin contracts, lifecycle management, error isolation, lazy loading, event communication, and plugin discovery mechanisms. Core plugins are hard-coded in file:src/main.jsx, and there's no distinction between core and custom plugins beyond manual registration.

Approach

The improvement strategy follows VS Code's extension architecture principles adapted for React: establish a formal plugin contract with metadata and lifecycle hooks, implement a centralized plugin registry with lazy loading based on activation events, add error boundaries for plugin isolation, create an event bus for inter-plugin communication, and separate core plugins from custom plugins with a clear loading mechanism. This approach maintains backward compatibility while enabling extensibility, developer experience improvements, and production-ready plugin management.

Implementation Plan

1. Define Plugin Contract and Types

Create a formal plugin interface structure in file:src/plugins/types.js:

Plugin Manifest Structure:

• id (string, required) - Unique plugin identifier
• name (string, required) - Display name
• version (string, required) - Semantic version
• author (string, optional) - Plugin author
• description (string, optional) - Plugin description
• type (enum, required) - Plugin type: 'ui', 'service', 'command', 'theme'
• activationEvents (array, optional) - Events that trigger plugin activation (e.g., ['onStartup'], ['onCommand:myCommand'], ['onLanguage:javascript'])
• contributes (object, optional) - What the plugin contributes (panels, commands, statusItems, etc.)
• dependencies (array, optional) - Other plugin IDs this plugin depends on
• main (function, required) - Plugin entry point that receives plugin API

Plugin Lifecycle Hooks:

• onLoad() - Called when plugin is first loaded (async supported)
• onActivate(context) - Called when activation event fires
• onDeactivate() - Called when plugin is deactivated
• onUnload() - Called before plugin is removed
• onError(error) - Called when plugin encounters an error

2. Create Plugin Registry System

Implement centralized plugin management in file:src/plugins/PluginRegistry.js:

Registry Responsibilities:

• Maintain map of registered plugins (core and custom)
• Track plugin states: 'unloaded', 'loaded', 'activated', 'deactivated', 'error'
• Validate plugin manifests on registration
• Resolve plugin dependencies and load in correct order
• Handle plugin lifecycle transitions
• Provide plugin query methods (getPlugin, getAllPlugins, getPluginsByType)
• Emit registry events ('plugin:registered', 'plugin:activated', 'plugin:error')

Core vs Custom Plugins:

• Core plugins: Auto-registered from file:src/plugins/core/ directory
• Custom plugins: Registered via registerCustomPlugin(pluginModule) API
• Core plugins always load first and cannot be disabled

3. Implement Plugin Context and Provider

Enhance file:src/hooks/useOmniLayout.jsx to become file:src/plugins/PluginProvider.jsx:

Plugin Context Structure:

• registry - Plugin registry instance
• pluginAPI - Stable API exposed to plugins
• eventBus - Event communication system
• registerPlugin(manifest) - Register new plugin
• activatePlugin(id) - Manually activate plugin
• deactivatePlugin(id) - Deactivate plugin
• getPluginAPI(pluginId) - Get scoped API for specific plugin

Plugin API (exposed to plugins):

• ui.registerPanel(config) - Register UI panel
• ui.registerStatusItem(config) - Register status bar item
• ui.togglePanel(id) - Control panel visibility
• commands.registerCommand(id, handler) - Register command
• commands.executeCommand(id, ...args) - Execute command
• events.on(event, handler) - Subscribe to events
• events.emit(event, data) - Emit events
• storage.get(key) - Get plugin-scoped storage
• storage.set(key, value) - Set plugin-scoped storage
• workspace.getActiveEditor() - Get active editor reference
• notifications.show(message, type) - Show notification

4. Create Event Bus System

Implement event-driven communication in file:src/plugins/EventBus.js:

Event Bus Features:

• Subscribe to events with on(event, handler) returning disposable
• Emit events with emit(event, data)
• One-time subscriptions with once(event, handler)
• Namespace support for plugin-scoped events (e.g., 'plugin:myPlugin:customEvent')
• Wildcard subscriptions (e.g., 'plugin:*')
• Event priority levels for ordered execution
• Async event handlers with error handling

Standard Events:

• 'editor:opened', 'editor:closed', 'editor:changed'
• 'file:opened', 'file:saved', 'file:closed'
• 'panel:opened', 'panel:closed'
• 'command:executed'
• 'plugin:activated', 'plugin:deactivated', 'plugin:error'

5. Implement Lazy Loading and Activation

Create activation system in file:src/plugins/ActivationManager.js:

Activation Events:

• 'onStartup' - Activate immediately on app start
• 'onCommand:commandId' - Activate when command is invoked
• 'onLanguage:languageId' - Activate when file type is opened
• 'onView:viewId' - Activate when specific view is opened
• 'onEvent:eventName' - Activate on custom event
• '*' - Always active (for core plugins)

Lazy Loading Strategy:

• Plugins with no activation events remain unloaded
• Monitor activation events and trigger plugin loading
• Use dynamic imports for plugin modules: import(pluginPath)
• Show loading indicators during plugin activation
• Cache loaded plugin modules for quick reactivation

6. Add Plugin Isolation and Error Handling

Create error boundary wrapper in file:src/plugins/PluginErrorBoundary.jsx:

Error Isolation:

• Wrap each plugin component in React Error Boundary
• Catch and log plugin errors without crashing app
• Display fallback UI when plugin fails
• Emit 'plugin:error' event with error details
• Provide "Reload Plugin" action in error UI
• Track plugin error count and auto-disable after threshold

Error Handling:

• Try-catch around all plugin lifecycle methods
• Timeout protection for long-running plugin operations
• Memory leak detection for plugins
• Console warnings for deprecated API usage

7. Restructure Core Plugins

Reorganize core plugins into file:src/plugins/core/ directory:

Core Plugin Structure:

• file:src/plugins/core/editor/ - Main editor plugin (Monaco integration)
• file:src/plugins/core/notifications/ - Notifications system
• file:src/plugins/core/statusbar/ - Status bar management
• file:src/plugins/core/explorer/ - File explorer (future)
• file:src/plugins/core/terminal/ - Integrated terminal (future)

Each Core Plugin Contains:

• manifest.js - Plugin manifest export
• index.jsx - Main plugin component
• hooks/ - Plugin-specific hooks
• components/ - Plugin UI components

Auto-Discovery:

• Create file:src/plugins/core/index.js that exports all core plugins
• Load core plugins automatically in PluginProvider

8. Create Plugin Development Kit

Provide utilities in file:src/plugins/sdk/:

SDK Components:

• file:src/plugins/sdk/createPlugin.js - Helper to create plugin with validation
• file:src/plugins/sdk/usePluginAPI.js - Hook to access plugin API
• file:src/plugins/sdk/PluginContext.jsx - Context for plugin-scoped data
• file:src/plugins/sdk/testing.js - Testing utilities for plugins
• file:src/plugins/sdk/types.d.ts - TypeScript definitions (if using TS)

Developer Experience:

• Hot reload support for plugin development
• Plugin development mode with detailed logging
• Plugin inspector UI showing loaded plugins and their state
• Plugin template generator CLI tool (future)

9. Implement Plugin Storage

Create plugin-scoped storage in file:src/plugins/PluginStorage.js:

Storage Features:

• Namespace storage by plugin ID
• Support for localStorage and sessionStorage
• JSON serialization/deserialization
• Storage quota management
• Storage events for cross-tab synchronization
• Migration helpers for storage schema changes

Storage API:

• get(key, defaultValue) - Retrieve value
• set(key, value) - Store value
• remove(key) - Delete value
• clear() - Clear all plugin storage
• keys() - List all keys
• onChanged(callback) - Listen for storage changes

10. Update Main Application Entry

Modify file:src/main.jsx to use new plugin system:

Changes:

• Replace LayoutProvider with PluginProvider
• Remove hard-coded CorePlugin component
• Core plugins auto-load from registry
• Add plugin initialization before rendering
• Add error boundary around entire app
• Expose plugin registration API globally for custom plugins

Initialization Sequence:

1. Create plugin registry
2. Register core plugins
3. Register custom plugins (from config or window API)
4. Activate plugins with 'onStartup' event
5. Render application with PluginProvider
6. Monitor activation events

11. Create Plugin Configuration System

Implement configuration in file:src/plugins/PluginConfig.js:

Configuration Features:

• Plugin-specific configuration schema
• Default configuration values
• Configuration validation
• UI for plugin settings (future)
• Configuration persistence in storage
• Configuration change events

Configuration API:

• getConfig(key, defaultValue) - Get config value
• setConfig(key, value) - Update config value
• resetConfig() - Reset to defaults
• onConfigChanged(callback) - Listen for changes

12. Add Plugin Commands System

Create command palette integration in file:src/plugins/CommandRegistry.js:

Command System:

• Register commands with unique IDs
• Command metadata (title, category, keybinding)
• Command execution with arguments
• Command palette UI (future)
• Keybinding management
• Command history

Command API:

• registerCommand(id, handler, metadata) - Register command
• unregisterCommand(id) - Remove command
• executeCommand(id, ...args) - Execute command
• getCommands() - List all commands

13. Implement Plugin Contribution Points

Define contribution points in file:src/plugins/ContributionPoints.js:

Contribution Types:

• panels - UI panels (sidebar, bottom, center)
• statusItems - Status bar items
• commands - Commands
• menus - Menu items (future)
• keybindings - Keyboard shortcuts (future)
• themes - Color themes (future)
• languages - Language support (future)

Contribution Validation:

• Validate contribution structure
• Check for conflicts (duplicate IDs)
• Merge contributions from multiple plugins
• Priority/ordering for contributions

14. Create Plugin Documentation

Add documentation in file:docs/plugins/:

Documentation Structure:

• file:docs/plugins/README.md - Plugin system overview
• file:docs/plugins/getting-started.md - Creating first plugin
• file:docs/plugins/api-reference.md - Complete API documentation
• file:docs/plugins/lifecycle.md - Plugin lifecycle explanation
• file:docs/plugins/examples.md - Example plugins
• file:docs/plugins/best-practices.md - Plugin development guidelines

15. Add Plugin Inspector UI (Development Tool)

Create developer tool in file:src/plugins/inspector/:

Inspector Features:

• List all registered plugins with status
• Show plugin metadata and dependencies
• Display plugin lifecycle state
• View plugin contributions
• Monitor plugin events
• Reload/disable plugins
• View plugin errors and logs
• Performance metrics per plugin

Access:

• Add command 'developer.showPluginInspector'
• Keyboard shortcut (Ctrl+Shift+P)
• Status bar item in development mode

Architecture Diagram

sequenceDiagram
    participant App as Application
    participant PR as PluginRegistry
    participant PM as PluginProvider
    participant AM as ActivationManager
    participant EB as EventBus
    participant P1 as CorePlugin
    participant P2 as CustomPlugin
    participant API as PluginAPI

    App->>PR: Initialize Registry
    App->>PR: Register Core Plugins
    PR->>P1: Validate Manifest
    PR->>PR: Store Plugin (unloaded)
    
    App->>PM: Create Provider
    PM->>API: Initialize Plugin API
    PM->>EB: Initialize Event Bus
    PM->>AM: Initialize Activation Manager
    
    App->>AM: Trigger 'onStartup' Event
    AM->>PR: Get Plugins with 'onStartup'
    PR-->>AM: Return Plugin List
    AM->>P1: Load Plugin Module
    P1-->>AM: Plugin Module
    AM->>P1: Call onLoad()
    AM->>P1: Call onActivate(context)
    P1->>API: Register Panel
    P1->>API: Register Command
    P1->>EB: Subscribe to Events
    
    Note over App,P2: User Triggers Custom Event
    App->>EB: Emit 'onCommand:custom'
    EB->>AM: Activation Event Detected
    AM->>PR: Get Plugins for Event
    PR-->>AM: Return P2
    AM->>P2: Load Plugin Module
    AM->>P2: Call onActivate(context)
    P2->>API: Use Plugin API
    
    Note over P1,P2: Inter-Plugin Communication
    P1->>EB: Emit Custom Event
    EB->>P2: Deliver Event
    P2->>API: Execute Command
    API->>P1: Command Handler

Loading

File Structure

src/
├── plugins/
│   ├── types.js                    # Plugin type definitions
│   ├── PluginRegistry.js           # Central plugin registry
│   ├── PluginProvider.jsx          # React context provider
│   ├── EventBus.js                 # Event communication system
│   ├── ActivationManager.js        # Lazy loading & activation
│   ├── PluginErrorBoundary.jsx     # Error isolation
│   ├── PluginStorage.js            # Plugin-scoped storage
│   ├── PluginConfig.js             # Configuration management
│   ├── CommandRegistry.js          # Command system
│   ├── ContributionPoints.js       # Contribution validation
│   │
│   ├── core/                       # Core plugins
│   │   ├── index.js                # Core plugin exports
│   │   ├── editor/
│   │   │   ├── manifest.js
│   │   │   ├── index.jsx
│   │   │   └── components/
│   │   ├── notifications/
│   │   │   ├── manifest.js
│   │   │   ├── index.jsx
│   │   │   └── components/
│   │   └── statusbar/
│   │       ├── manifest.js
│   │       └── index.jsx
│   │
│   ├── sdk/                        # Plugin development kit
│   │   ├── createPlugin.js
│   │   ├── usePluginAPI.js
│   │   ├── PluginContext.jsx
│   │   └── testing.js
│   │
│   └── inspector/                  # Development tool
│       ├── PluginInspector.jsx
│       └── components/
│
├── hooks/
│   └── useOmniLayout.jsx           # Deprecated, migrate to PluginProvider
│
├── lib/
│   ├── Layout.jsx                  # Update to use PluginProvider
│   └── Monaco.jsx                  # Move to core/editor plugin
│
└── main.jsx                        # Update initialization

Migration Strategy

Phase 1 - Foundation:

1. Create plugin types and registry
2. Implement event bus
3. Create plugin provider (parallel to existing LayoutProvider)

Phase 2 - Core Migration:
4. Migrate existing core plugins to new structure
5. Update Layout.jsx to support both systems
6. Add error boundaries

Phase 3 - Features:
7. Implement lazy loading and activation
8. Add plugin storage and configuration
9. Create command system

Phase 4 - Developer Experience:
10. Build plugin SDK
11. Create plugin inspector
12. Write documentation

Phase 5 - Cleanup:
13. Remove old LayoutProvider
14. Deprecate window.omniCore/omniLayout
15. Finalize API versioning

Backward Compatibility

• Keep existing window.omniCore and window.omniLayout as compatibility layer
• Existing registerPlugin calls work through adapter
• Gradual migration path for core plugins
• Deprecation warnings for old APIs
• Support both systems during transition period

Import In IDE

🤖 Prompt for AI Agents

## Observations

The current plugin system in ide-shell is primitive but functional. It uses React Context (`LayoutProvider`) for plugin registration, supports UI panels (left/center/bottom) and status bar items, and exposes a global API via `window.omniCore` and `window.omniLayout`. The implementation lacks formal plugin contracts, lifecycle management, error isolation, lazy loading, event communication, and plugin discovery mechanisms. Core plugins are hard-coded in `file:src/main.jsx`, and there's no distinction between core and custom plugins beyond manual registration.

## Approach

The improvement strategy follows VS Code's extension architecture principles adapted for React: establish a formal plugin contract with metadata and lifecycle hooks, implement a centralized plugin registry with lazy loading based on activation events, add error boundaries for plugin isolation, create an event bus for inter-plugin communication, and separate core plugins from custom plugins with a clear loading mechanism. This approach maintains backward compatibility while enabling extensibility, developer experience improvements, and production-ready plugin management.

## Implementation Plan

### 1. Define Plugin Contract and Types

Create a formal plugin interface structure in `file:src/plugins/types.js`:

**Plugin Manifest Structure:**
- `id` (string, required) - Unique plugin identifier
- `name` (string, required) - Display name
- `version` (string, required) - Semantic version
- `author` (string, optional) - Plugin author
- `description` (string, optional) - Plugin description
- `type` (enum, required) - Plugin type: `'ui'`, `'service'`, `'command'`, `'theme'`
- `activationEvents` (array, optional) - Events that trigger plugin activation (e.g., `['onStartup']`, `['onCommand:myCommand']`, `['onLanguage:javascript']`)
- `contributes` (object, optional) - What the plugin contributes (panels, commands, statusItems, etc.)
- `dependencies` (array, optional) - Other plugin IDs this plugin depends on
- `main` (function, required) - Plugin entry point that receives plugin API

**Plugin Lifecycle Hooks:**
- `onLoad()` - Called when plugin is first loaded (async supported)
- `onActivate(context)` - Called when activation event fires
- `onDeactivate()` - Called when plugin is deactivated
- `onUnload()` - Called before plugin is removed
- `onError(error)` - Called when plugin encounters an error

### 2. Create Plugin Registry System

Implement centralized plugin management in `file:src/plugins/PluginRegistry.js`:

**Registry Responsibilities:**
- Maintain map of registered plugins (core and custom)
- Track plugin states: `'unloaded'`, `'loaded'`, `'activated'`, `'deactivated'`, `'error'`
- Validate plugin manifests on registration
- Resolve plugin dependencies and load in correct order
- Handle plugin lifecycle transitions
- Provide plugin query methods (`getPlugin`, `getAllPlugins`, `getPluginsByType`)
- Emit registry events (`'plugin:registered'`, `'plugin:activated'`, `'plugin:error'`)

**Core vs Custom Plugins:**
- Core plugins: Auto-registered from `file:src/plugins/core/` directory
- Custom plugins: Registered via `registerCustomPlugin(pluginModule)` API
- Core plugins always load first and cannot be disabled

### 3. Implement Plugin Context and Provider

Enhance `file:src/hooks/useOmniLayout.jsx` to become `file:src/plugins/PluginProvider.jsx`:

**Plugin Context Structure:**
- `registry` - Plugin registry instance
- `pluginAPI` - Stable API exposed to plugins
- `eventBus` - Event communication system
- `registerPlugin(manifest)` - Register new plugin
- `activatePlugin(id)` - Manually activate plugin
- `deactivatePlugin(id)` - Deactivate plugin
- `getPluginAPI(pluginId)` - Get scoped API for specific plugin

**Plugin API (exposed to plugins):**
- `ui.registerPanel(config)` - Register UI panel
- `ui.registerStatusItem(config)` - Register status bar item
- `ui.togglePanel(id)` - Control panel visibility
- `commands.registerCommand(id, handler)` - Register command
- `commands.executeCommand(id, ...args)` - Execute command
- `events.on(event, handler)` - Subscribe to events
- `events.emit(event, data)` - Emit events
- `storage.get(key)` - Get plugin-scoped storage
- `storage.set(key, value)` - Set plugin-scoped storage
- `workspace.getActiveEditor()` - Get active editor reference
- `notifications.show(message, type)` - Show notification

### 4. Create Event Bus System

Implement event-driven communication in `file:src/plugins/EventBus.js`:

**Event Bus Features:**
- Subscribe to events with `on(event, handler)` returning disposable
- Emit events with `emit(event, data)`
- One-time subscriptions with `once(event, handler)`
- Namespace support for plugin-scoped events (e.g., `'plugin:myPlugin:customEvent'`)
- Wildcard subscriptions (e.g., `'plugin:*'`)
- Event priority levels for ordered execution
- Async event handlers with error handling

**Standard Events:**
- `'editor:opened'`, `'editor:closed'`, `'editor:changed'`
- `'file:opened'`, `'file:saved'`, `'file:closed'`
- `'panel:opened'`, `'panel:closed'`
- `'command:executed'`
- `'plugin:activated'`, `'plugin:deactivated'`, `'plugin:error'`

### 5. Implement Lazy Loading and Activation

Create activation system in `file:src/plugins/ActivationManager.js`:

**Activation Events:**
- `'onStartup'` - Activate immediately on app start
- `'onCommand:commandId'` - Activate when command is invoked
- `'onLanguage:languageId'` - Activate when file type is opened
- `'onView:viewId'` - Activate when specific view is opened
- `'onEvent:eventName'` - Activate on custom event
- `'*'` - Always active (for core plugins)

**Lazy Loading Strategy:**
- Plugins with no activation events remain unloaded
- Monitor activation events and trigger plugin loading
- Use dynamic imports for plugin modules: `import(pluginPath)`
- Show loading indicators during plugin activation
- Cache loaded plugin modules for quick reactivation

### 6. Add Plugin Isolation and Error Handling

Create error boundary wrapper in `file:src/plugins/PluginErrorBoundary.jsx`:

**Error Isolation:**
- Wrap each plugin component in React Error Boundary
- Catch and log plugin errors without crashing app
- Display fallback UI when plugin fails
- Emit `'plugin:error'` event with error details
- Provide "Reload Plugin" action in error UI
- Track plugin error count and auto-disable after threshold

**Error Handling:**
- Try-catch around all plugin lifecycle methods
- Timeout protection for long-running plugin operations
- Memory leak detection for plugins
- Console warnings for deprecated API usage

### 7. Restructure Core Plugins

Reorganize core plugins into `file:src/plugins/core/` directory:

**Core Plugin Structure:**
- `file:src/plugins/core/editor/` - Main editor plugin (Monaco integration)
- `file:src/plugins/core/notifications/` - Notifications system
- `file:src/plugins/core/statusbar/` - Status bar management
- `file:src/plugins/core/explorer/` - File explorer (future)
- `file:src/plugins/core/terminal/` - Integrated terminal (future)

**Each Core Plugin Contains:**
- `manifest.js` - Plugin manifest export
- `index.jsx` - Main plugin component
- `hooks/` - Plugin-specific hooks
- `components/` - Plugin UI components

**Auto-Discovery:**
- Create `file:src/plugins/core/index.js` that exports all core plugins
- Load core plugins automatically in `PluginProvider`

### 8. Create Plugin Development Kit

Provide utilities in `file:src/plugins/sdk/`:

**SDK Components:**
- `file:src/plugins/sdk/createPlugin.js` - Helper to create plugin with validation
- `file:src/plugins/sdk/usePluginAPI.js` - Hook to access plugin API
- `file:src/plugins/sdk/PluginContext.jsx` - Context for plugin-scoped data
- `file:src/plugins/sdk/testing.js` - Testing utilities for plugins
- `file:src/plugins/sdk/types.d.ts` - TypeScript definitions (if using TS)

**Developer Experience:**
- Hot reload support for plugin development
- Plugin development mode with detailed logging
- Plugin inspector UI showing loaded plugins and their state
- Plugin template generator CLI tool (future)

### 9. Implement Plugin Storage

Create plugin-scoped storage in `file:src/plugins/PluginStorage.js`:

**Storage Features:**
- Namespace storage by plugin ID
- Support for localStorage and sessionStorage
- JSON serialization/deserialization
- Storage quota management
- Storage events for cross-tab synchronization
- Migration helpers for storage schema changes

**Storage API:**
- `get(key, defaultValue)` - Retrieve value
- `set(key, value)` - Store value
- `remove(key)` - Delete value
- `clear()` - Clear all plugin storage
- `keys()` - List all keys
- `onChanged(callback)` - Listen for storage changes

### 10. Update Main Application Entry

Modify `file:src/main.jsx` to use new plugin system:

**Changes:**
- Replace `LayoutProvider` with `PluginProvider`
- Remove hard-coded `CorePlugin` component
- Core plugins auto-load from registry
- Add plugin initialization before rendering
- Add error boundary around entire app
- Expose plugin registration API globally for custom plugins

**Initialization Sequence:**
1. Create plugin registry
2. Register core plugins
3. Register custom plugins (from config or window API)
4. Activate plugins with `'onStartup'` event
5. Render application with `PluginProvider`
6. Monitor activation events

### 11. Create Plugin Configuration System

Implement configuration in `file:src/plugins/PluginConfig.js`:

**Configuration Features:**
- Plugin-specific configuration schema
- Default configuration values
- Configuration validation
- UI for plugin settings (future)
- Configuration persistence in storage
- Configuration change events

**Configuration API:**
- `getConfig(key, defaultValue)` - Get config value
- `setConfig(key, value)` - Update config value
- `resetConfig()` - Reset to defaults
- `onConfigChanged(callback)` - Listen for changes

### 12. Add Plugin Commands System

Create command palette integration in `file:src/plugins/CommandRegistry.js`:

**Command System:**
- Register commands with unique IDs
- Command metadata (title, category, keybinding)
- Command execution with arguments
- Command palette UI (future)
- Keybinding management
- Command history

**Command API:**
- `registerCommand(id, handler, metadata)` - Register command
- `unregisterCommand(id)` - Remove command
- `executeCommand(id, ...args)` - Execute command
- `getCommands()` - List all commands

### 13. Implement Plugin Contribution Points

Define contribution points in `file:src/plugins/ContributionPoints.js`:

**Contribution Types:**
- `panels` - UI panels (sidebar, bottom, center)
- `statusItems` - Status bar items
- `commands` - Commands
- `menus` - Menu items (future)
- `keybindings` - Keyboard shortcuts (future)
- `themes` - Color themes (future)
- `languages` - Language support (future)

**Contribution Validation:**
- Validate contribution structure
- Check for conflicts (duplicate IDs)
- Merge contributions from multiple plugins
- Priority/ordering for contributions

### 14. Create Plugin Documentation

Add documentation in `file:docs/plugins/`:

**Documentation Structure:**
- `file:docs/plugins/README.md` - Plugin system overview
- `file:docs/plugins/getting-started.md` - Creating first plugin
- `file:docs/plugins/api-reference.md` - Complete API documentation
- `file:docs/plugins/lifecycle.md` - Plugin lifecycle explanation
- `file:docs/plugins/examples.md` - Example plugins
- `file:docs/plugins/best-practices.md` - Plugin development guidelines

### 15. Add Plugin Inspector UI (Development Tool)

Create developer tool in `file:src/plugins/inspector/`:

**Inspector Features:**
- List all registered plugins with status
- Show plugin metadata and dependencies
- Display plugin lifecycle state
- View plugin contributions
- Monitor plugin events
- Reload/disable plugins
- View plugin errors and logs
- Performance metrics per plugin

**Access:**
- Add command `'developer.showPluginInspector'`
- Keyboard shortcut (Ctrl+Shift+P)
- Status bar item in development mode

## Architecture Diagram

```mermaid
sequenceDiagram
    participant App as Application
    participant PR as PluginRegistry
    participant PM as PluginProvider
    participant AM as ActivationManager
    participant EB as EventBus
    participant P1 as CorePlugin
    participant P2 as CustomPlugin
    participant API as PluginAPI

    App->>PR: Initialize Registry
    App->>PR: Register Core Plugins
    PR->>P1: Validate Manifest
    PR->>PR: Store Plugin (unloaded)
    
    App->>PM: Create Provider
    PM->>API: Initialize Plugin API
    PM->>EB: Initialize Event Bus
    PM->>AM: Initialize Activation Manager
    
    App->>AM: Trigger 'onStartup' Event
    AM->>PR: Get Plugins with 'onStartup'
    PR-->>AM: Return Plugin List
    AM->>P1: Load Plugin Module
    P1-->>AM: Plugin Module
    AM->>P1: Call onLoad()
    AM->>P1: Call onActivate(context)
    P1->>API: Register Panel
    P1->>API: Register Command
    P1->>EB: Subscribe to Events
    
    Note over App,P2: User Triggers Custom Event
    App->>EB: Emit 'onCommand:custom'
    EB->>AM: Activation Event Detected
    AM->>PR: Get Plugins for Event
    PR-->>AM: Return P2
    AM->>P2: Load Plugin Module
    AM->>P2: Call onActivate(context)
    P2->>API: Use Plugin API
    
    Note over P1,P2: Inter-Plugin Communication
    P1->>EB: Emit Custom Event
    EB->>P2: Deliver Event
    P2->>API: Execute Command
    API->>P1: Command Handler
```

## File Structure

```
src/
├── plugins/
│   ├── types.js                    # Plugin type definitions
│   ├── PluginRegistry.js           # Central plugin registry
│   ├── PluginProvider.jsx          # React context provider
│   ├── EventBus.js                 # Event communication system
│   ├── ActivationManager.js        # Lazy loading & activation
│   ├── PluginErrorBoundary.jsx     # Error isolation
│   ├── PluginStorage.js            # Plugin-scoped storage
│   ├── PluginConfig.js             # Configuration management
│   ├── CommandRegistry.js          # Command system
│   ├── ContributionPoints.js       # Contribution validation
│   │
│   ├── core/                       # Core plugins
│   │   ├── index.js                # Core plugin exports
│   │   ├── editor/
│   │   │   ├── manifest.js
│   │   │   ├── index.jsx
│   │   │   └── components/
│   │   ├── notifications/
│   │   │   ├── manifest.js
│   │   │   ├── index.jsx
│   │   │   └── components/
│   │   └── statusbar/
│   │       ├── manifest.js
│   │       └── index.jsx
│   │
│   ├── sdk/                        # Plugin development kit
│   │   ├── createPlugin.js
│   │   ├── usePluginAPI.js
│   │   ├── PluginContext.jsx
│   │   └── testing.js
│   │
│   └── inspector/                  # Development tool
│       ├── PluginInspector.jsx
│       └── components/
│
├── hooks/
│   └── useOmniLayout.jsx           # Deprecated, migrate to PluginProvider
│
├── lib/
│   ├── Layout.jsx                  # Update to use PluginProvider
│   └── Monaco.jsx                  # Move to core/editor plugin
│
└── main.jsx                        # Update initialization
```

## Migration Strategy

**Phase 1 - Foundation:**
1. Create plugin types and registry
2. Implement event bus
3. Create plugin provider (parallel to existing LayoutProvider)

**Phase 2 - Core Migration:**
4. Migrate existing core plugins to new structure
5. Update Layout.jsx to support both systems
6. Add error boundaries

**Phase 3 - Features:**
7. Implement lazy loading and activation
8. Add plugin storage and configuration
9. Create command system

**Phase 4 - Developer Experience:**
10. Build plugin SDK
11. Create plugin inspector
12. Write documentation

**Phase 5 - Cleanup:**
13. Remove old LayoutProvider
14. Deprecate window.omniCore/omniLayout
15. Finalize API versioning

## Backward Compatibility

- Keep existing `window.omniCore` and `window.omniLayout` as compatibility layer
- Existing `registerPlugin` calls work through adapter
- Gradual migration path for core plugins
- Deprecation warnings for old APIs
- Support both systems during transition period

---

Execution Information

Branch: main
Commit: 65dc765

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[ampelectrecuted]

@coderabbitai

[coderabbitai]

Coding Plan

Approach

Improve the existing primitive plugin system to formally distinguish between core plugins (always run) and custom plugins (manually registered), while enhancing the plugin contract, lifecycle management, and loading infrastructure.

Observations

The application is a VS Code-like IDE shell built with React 19 and Vite (Rolldown-Vite). The current plugin system uses a functional, hook-driven architecture centered around LayoutProvider (in useOmniLayout.jsx) which provides a Context-based registry. Plugins register via registerPlugin() with position-based layout slots (left, center, right, bottom). Currently, only one plugin exists (CorePlugin) which registers the Monaco editor and notifications panel. The system exposes APIs globally via window.omniLayout and window.omniCore for external integration. The architecture lacks formal plugin type distinction, has limited lifecycle hooks (only onLoad), and has no centralized loader for core plugins.

Assumptions

Assumption 1: Plugin Loading Strategy

Options Considered:

1. Static registration only - all plugins bundled with the app, registered at startup
2. Dynamic import support - allow lazy loading of custom plugins via import() for code splitting
3. External URL loading - support loading plugins from remote URLs at runtime

Chosen Option: 2

Rationale: This provides code splitting benefits for custom plugins while avoiding the complexity and security concerns of external URL loading. It aligns with existing patterns (Monaco workers already use dynamic imports) and Vite's native capabilities.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Plugin Contract & Type System

Establish a formal plugin interface that distinguishes core from custom plugins and provides a consistent contract for all plugin metadata and capabilities.

Task 1: Define Plugin Interface Structure

Create a well-documented plugin contract that all plugins must follow, establishing the foundation for type-safe plugin registration.

• Create src/plugins/pluginContract.js to document and export the plugin interface specification
• Define required fields: id (string), type ('core' | 'custom'), name (string)
• Define optional fields: version, description, icon, position, dependencies (array of plugin IDs), priority (number for load order)
• Add a validatePlugin() helper function that checks required fields and logs warnings for malformed plugins
• Export constants for plugin types (PLUGIN_TYPE.CORE, PLUGIN_TYPE.CUSTOM) and positions

Task 2: Enhance Plugin Registry

Update the central registry to handle the enhanced plugin contract and track plugin metadata.

• Update registerPlugin() in src/hooks/useOmniLayout.jsx to accept the new contract fields
• Add validation call before registration using the validatePlugin() helper
• Store plugin type in the panels state to enable core vs custom filtering
• Add getPluginsByType(type) helper to the context value for retrieving core or custom plugins
• Update the window.omniLayout exposure to include the new helper functions

🤖 Prompt for AI agents

Implement the formal plugin contract and type system to distinguish between core
and custom plugins.

Create `src/plugins/pluginContract.js`:
- Export plugin type constants (PLUGIN_TYPE.CORE, PLUGIN_TYPE.CUSTOM)
- Define plugin interface with required fields (id, type, name) and optional
fields (version, description, icon, position, dependencies, priority)
- Implement `validatePlugin()` function that validates required fields and logs
warnings

Update `src/hooks/useOmniLayout.jsx`:
- Modify `registerPlugin()` to accept and validate the enhanced plugin contract
fields
- Store plugin type in the panels state
- Add `getPluginsByType(type)` helper function to context
- Update `window.omniLayout` exposure to include new helper functions

Phase 2: Plugin Lifecycle Enhancement

Implement proper lifecycle hooks that allow plugins to respond to state changes and clean up resources appropriately.

Task 1: Add Lifecycle Hook Support

Extend the plugin contract and registry to support full lifecycle management beyond the current onLoad hook.

• Add lifecycle hook fields to the plugin contract: onLoad, onEnable, onDisable, onDestroy
• Update src/hooks/useOmniLayout.jsx to track plugin enabled/disabled state in a new pluginStates state object
• Implement enablePlugin(id) function that calls the plugin's onEnable hook and updates state
• Implement disablePlugin(id) function that calls onDisable hook (only for custom plugins - core plugins cannot be disabled)
• Add cleanup logic to call onDestroy when plugins are unregistered

Task 2: Implement Plugin State Management

Create the infrastructure to track and manage individual plugin states throughout the application lifecycle.

• Add pluginStates state to LayoutProvider to track each plugin's status (loading, enabled, disabled, error)
• Create getPluginState(id) helper exposed via context
• Ensure core plugins are automatically set to 'enabled' state and cannot transition to 'disabled'
• Add error handling that captures plugin lifecycle hook failures and stores error state
• Expose plugin state information to window.omniLayout for debugging and external access

🤖 Prompt for AI agents

Add comprehensive lifecycle management to the plugin system.

Update `src/plugins/pluginContract.js`:
- Add lifecycle hook fields to plugin interface: onLoad, onEnable, onDisable,
onDestroy

Update `src/hooks/useOmniLayout.jsx`:
- Add `pluginStates` state object to track plugin status (loading, enabled,
disabled, error)
- Implement `enablePlugin(id)` that calls onEnable hook and updates state
- Implement `disablePlugin(id)` that calls onDisable hook (only for custom
plugins)
- Add cleanup logic to call onDestroy when plugins are unregistered
- Create `getPluginState(id)` helper and expose via context
- Ensure core plugins are always enabled and cannot be disabled
- Add error handling for lifecycle hook failures
- Expose plugin state to `window.omniLayout`

Phase 3: Plugin Loading Infrastructure

Create a centralized plugin loader that ensures core plugins are always loaded and provides utilities for registering custom plugins.

Task 1: Create Plugin Loader Utility

Build a plugin loader that handles initialization order, dependency resolution, and automatic core plugin loading.

• Create src/plugins/pluginLoader.js with a PluginLoader class or functional module
• Implement loadCorePlugins() function that imports and registers all plugins from src/plugins/core/
• Implement loadCustomPlugin(pluginConfig) for manually registering custom plugins
• Add loadPluginAsync(importFn) that wraps dynamic imports with error handling and loading state
• Implement basic dependency resolution that ensures plugins load after their declared dependencies
• Sort plugins by priority field before registration

Task 2: Reorganize Plugin Directory Structure

Establish a clear directory structure that separates core and custom plugins.

• Create src/plugins/core/ directory for core plugins that always load
• Create src/plugins/custom/ directory for optional/custom plugin examples
• Move existing corePlugin.js to src/plugins/core/corePlugin.js
• Create src/plugins/core/index.js that exports all core plugins as an array for the loader
• Update src/plugins/index.js as the main entry point that exports the loader and plugin utilities

Task 3: Integrate Plugin Loader with Application

Wire the plugin loader into the application bootstrap process to replace manual plugin mounting.

• Create src/hooks/usePluginLoader.jsx hook that uses the plugin loader and provides loading state
• Update src/main.jsx to use the plugin loader instead of directly rendering <CorePlugin />
• Ensure core plugins load synchronously at startup (no lazy loading for core)
• Add loading indicator support while plugins initialize
• Expose window.omniPlugins API with registerCustomPlugin() for external custom plugin registration

Task 4: Update Core Plugin to New Contract

Refactor the existing CorePlugin to comply with the enhanced plugin contract and serve as a reference implementation.

• Update src/plugins/core/corePlugin.js to export a plugin configuration object following the new contract
• Add type: 'core', version, description, and priority fields
• Implement onEnable and onDisable lifecycle hooks (onDisable can be a no-op for core)
• Update src/hooks/useCorePlugin.jsx to work with the new loader pattern
• Add inline documentation demonstrating the plugin contract for future plugin authors

🤖 Prompt for AI agents

Build the centralized plugin loading infrastructure and integrate it into the
application.

Create `src/plugins/pluginLoader.js`:
- Implement `loadCorePlugins()` to import and register plugins from
src/plugins/core/
- Implement `loadCustomPlugin(pluginConfig)` for manual registration
- Add `loadPluginAsync(importFn)` with error handling and loading state
- Implement dependency resolution based on dependencies array
- Sort plugins by priority before registration

Reorganize directory structure:
- Create src/plugins/core/ and src/plugins/custom/ directories
- Move corePlugin.js to src/plugins/core/
- Create src/plugins/core/index.js exporting all core plugins
- Update src/plugins/index.js as main entry point

Create `src/hooks/usePluginLoader.jsx`:
- Hook that uses plugin loader and provides loading state

Update `src/main.jsx`:
- Replace direct CorePlugin rendering with plugin loader
- Ensure core plugins load synchronously
- Add loading indicator support
- Expose `window.omniPlugins` with `registerCustomPlugin()`

Update `src/plugins/core/corePlugin.js`:
- Export plugin config object with type: 'core', version, description, priority
- Implement onEnable and onDisable lifecycle hooks
- Update src/hooks/useCorePlugin.jsx for new loader pattern
- Add documentation for plugin contract

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the formal plugin contract and type system to distinguish between core
and custom plugins.

Create `src/plugins/pluginContract.js`:
- Export plugin type constants (PLUGIN_TYPE.CORE, PLUGIN_TYPE.CUSTOM)
- Define plugin interface with required fields (id, type, name) and optional
fields (version, description, icon, position, dependencies, priority)
- Implement `validatePlugin()` function that validates required fields and logs
warnings

Update `src/hooks/useOmniLayout.jsx`:
- Modify `registerPlugin()` to accept and validate the enhanced plugin contract
fields
- Store plugin type in the panels state
- Add `getPluginsByType(type)` helper function to context
- Update `window.omniLayout` exposure to include new helper functions
===============================================================================

Task: 2

Add comprehensive lifecycle management to the plugin system.

Update `src/plugins/pluginContract.js`:
- Add lifecycle hook fields to plugin interface: onLoad, onEnable, onDisable,
onDestroy

Update `src/hooks/useOmniLayout.jsx`:
- Add `pluginStates` state object to track plugin status (loading, enabled,
disabled, error)
- Implement `enablePlugin(id)` that calls onEnable hook and updates state
- Implement `disablePlugin(id)` that calls onDisable hook (only for custom
plugins)
- Add cleanup logic to call onDestroy when plugins are unregistered
- Create `getPluginState(id)` helper and expose via context
- Ensure core plugins are always enabled and cannot be disabled
- Add error handling for lifecycle hook failures
- Expose plugin state to `window.omniLayout`
===============================================================================

Task: 3

Build the centralized plugin loading infrastructure and integrate it into the
application.

Create `src/plugins/pluginLoader.js`:
- Implement `loadCorePlugins()` to import and register plugins from
src/plugins/core/
- Implement `loadCustomPlugin(pluginConfig)` for manual registration
- Add `loadPluginAsync(importFn)` with error handling and loading state
- Implement dependency resolution based on dependencies array
- Sort plugins by priority before registration

Reorganize directory structure:
- Create src/plugins/core/ and src/plugins/custom/ directories
- Move corePlugin.js to src/plugins/core/
- Create src/plugins/core/index.js exporting all core plugins
- Update src/plugins/index.js as main entry point

Create `src/hooks/usePluginLoader.jsx`:
- Hook that uses plugin loader and provides loading state

Update `src/main.jsx`:
- Replace direct CorePlugin rendering with plugin loader
- Ensure core plugins load synchronously
- Add loading indicator support
- Expose `window.omniPlugins` with `registerCustomPlugin()`

Update `src/plugins/core/corePlugin.js`:
- Export plugin config object with type: 'core', version, description, priority
- Implement onEnable and onDisable lifecycle hooks
- Update src/hooks/useCorePlugin.jsx for new loader pattern
- Add documentation for plugin contract

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[ampelectrecuted]

@coderabbitai generate configuration

[coderabbitai]

Created a pull request adding .coderabbit.yaml: #3

[ampelectrecuted]

@supervoidcoder https://omniblocks.github.io/ide-shell/

[ampelectrecuted]

it even has offline service worker