Plugin System - Complete Guide
Extend Scribe Animator with plugins that add new features, processors, exporters, and UI panels. This guide covers the Plugin Manager interface and understanding how plugins enhance your workflow.
Overview
The plugin system allows modular extension of Scribe Animator through two execution models:
PLUGIN SYSTEM ARCHITECTURE
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ SCRIBE ANIMATOR HOST │
│ │
│ ┌─────────────────────────┐ ┌─────────────────────────────────┐ │
│ │ Plugin Manager UI │────│ Plugin Registry │ │
│ │ │ │ │ │
│ │ • Enable/Disable │ │ • Host plugins (direct) │ │
│ │ • View details │ │ • Sandboxed plugins (isolated) │ │
│ │ • Monitor health │ │ • Permissions & capabilities │ │
│ │ • Manage permissions │ │ │ │
│ └─────────────────────────┘ └─────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ HOST PLUGINS SANDBOXED PLUGINS │ │
│ │ ┌─────────┐ ┌─────────────────────────────────┐ │ │
│ │ │ Direct │ │ ┌─────────┐ ┌─────────┐ │ │ │
│ │ │ Access │ │ │ iframe │ │ Worker │ │ │ │
│ │ │ │ │ │ (UI) │ │ (Proc) │ │ │ │
│ │ └─────────┘ │ └─────────┘ └─────────┘ │ │ │
│ │ │ │ │ │
│ │ • Timeline Panel │ • Inspector Modal │ │ │
│ │ • Scene Manager │ • Vector Processor │ │ │
│ │ • Audio Processor │ • SVG Exporter │ │ │
│ │ • Hand Animator │ • Video Exporter │ │ │
│ │ └─────────────────────────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Opening Plugin Manager
Method 1: Menu
View → Plugin Manager or Settings → Plugins
Method 2: Keyboard Shortcut
| Platform | Shortcut |
|---|---|
| Windows/Linux | Ctrl+Shift+P |
| macOS | ⌘+Shift+P |
Plugin Manager Interface
Main Panel
┌──────────────────────────────────────────────────────────────────────────┐
│ Plugin Manager [X] │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ PLUGIN TYPE VERSION STATUS TOGGLE │ │
│ ├────────────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ Hand Animator Animator 1.0.0 ● Active [████████] │ │
│ │ LUT-based hand follower for draw animations │ │
│ │ │ │
│ │ Timeline Panel UI 1.0.0 ● Active [████████] │ │
│ │ Main timeline interface for animation control │ │
│ │ │ │
│ │ Audio Processor UI 1.0.0 ● Active [████████] │ │
│ │ Web Audio API based audio processing │ │
│ │ │ │
│ │ Vector Processor Processor 1.0.0 ● Active [████████] │ │
│ │ Default vector path processor for SVG handling │ │
│ │ │ │
│ │ Inspector Modal UI 1.0.0 ● Active [████████] │ │
│ │ Properties panel for selected objects │ │
│ │ │ │
│ │ SVG Exporter Exporter 1.0.0 ● Active [████████] │ │
│ │ Static SVG export capability │ │
│ │ │ │
│ │ Video Exporter Exporter 1.0.0 ● Active [████████] │ │
│ │ MP4/WebM video rendering with hidden stage │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
├──────────────────────────────────────────────────────────────────────────┤
│ 🔒 Security Log [ Clear ] │
│ └─ No security events │
└──────────────────────────────────────────────────────────────────────────┘
Plugin Status Indicators
| Status | Icon | Description |
|---|---|---|
| Active | ● (green) | Plugin running normally |
| Disabled | ○ (gray) | Plugin turned off |
| Warning | ⚠ (yellow) | Plugin experiencing issues |
| Error | ✕ (red) | Plugin failed to load/run |
| Pending | ◐ (spinning) | Action in progress |
Enabling/Disabling Plugins
Toggle Switch
Click the toggle switch next to any plugin to enable or disable it:
TOGGLE STATES
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ ENABLED DISABLED │
│ ┌────────────────────┐ ┌────────────────────┐ │
│ │ █████████████████ │ │ ░░░░░░░░░░░░░░░░░░ │ │
│ └────────────────────┘ └────────────────────┘ │
│ │
│ Plugin features active Plugin features hidden │
│ Resources allocated Resources released │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Effect of Disabling
| Plugin Type | What Happens |
|---|---|
| UI Plugins | Panel/UI element hidden |
| Processors | Processing capability disabled |
| Exporters | Export format unavailable |
| Animators | Animation feature disabled |
warning
Disabling core plugins like Timeline Panel or Hand Animator will remove key features from the interface. You can re-enable them at any time.
Plugin Details Drawer
Click on a plugin row to open the details drawer:
┌──────────────────────────────────────────────────────────────────────────┐
│ Plugin Manager [X] │
├────────────────────────────────────┬─────────────────────────────────────┤
│ │ │
│ PLUGIN LIST │ PLUGIN DETAILS │
│ │ │
│ ┌────────────────────────────┐ │ Hand Animator │
│ │ ► Hand Animator ● │ │ ───────────────────────────────── │
│ │ Timeline Panel ● │ │ │
│ │ Audio Processor ● │ │ ID: animator.hand.lut │
│ │ Vector Processor ● │ │ Version: 1.0.0 │
│ │ Inspector Modal ● │ │ Type: Animator (Host) │
│ │ SVG Exporter ● │ │ Publisher: Core Team │
│ │ Video Exporter ● │ │ │
│ └────────────────────────────┘ │ DESCRIPTION │
│ │ LUT-based hand follower system │
│ │ for realistic draw-in animations │
│ │ with configurable presets. │
│ │ │
│ │ CAPABILITIES │
│ │ ├ core.scene.read │
│ │ ├ telemetry.emit │
│ │ └ ui.panel.register │
│ │ │
│ │ PERMISSIONS │
│ │ ├ telemetry │
│ │ └ timeline.read │
│ │ │
│ │ [ Reload ] [ Repair ] │
│ │ │
└────────────────────────────────────┴─────────────────────────────────────┘
Detail Sections
| Section | Description |
|---|---|
| Basic Info | ID, version, type, publisher |
| Description | What the plugin does |
| Capabilities | Features the plugin can access |
| Permissions | System permissions granted |
| Actions | Reload, Repair, Revoke buttons |
Built-in Plugins
Core Plugins
These plugins provide essential functionality:
| Plugin | Type | Description |
|---|---|---|
| Hand Animator | Animator | LUT-based hand follower for draw animations |
| Timeline Panel | UI | Main timeline interface with playback controls |
| Scene Manager | UI | Scene list, transitions, and organization |
| Audio Processor | UI | Background music and voiceover support |
Processing Plugins
| Plugin | Type | Description |
|---|---|---|
| Vector Processor | Processor | SVG path processing and optimization |
Export Plugins
| Plugin | Type | Description |
|---|---|---|
| SVG Exporter | Exporter | Export static SVG files |
| Video Exporter | Exporter | Export MP4/WebM videos |
UI Plugins
| Plugin | Type | Description |
|---|---|---|
| Inspector Modal | UI | Properties panel for object editing |
Plugin Types
Host Plugins
Run directly in the main application:
HOST PLUGIN CHARACTERISTICS
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ ✓ Direct access to application state │
│ ✓ No performance overhead from message passing │
│ ✓ Can use React components directly │
│ ✓ Full access to FIG domain services │
│ │
│ Examples: Timeline Panel, Scene Manager, Hand Animator │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Sandboxed Plugins
Run in isolated environments (iframe or worker):
SANDBOXED PLUGIN CHARACTERISTICS
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ IFRAME SANDBOX WORKER SANDBOX │
│ ┌───────────────────────────┐ ┌───────────────────────────┐ │
│ │ ✓ Full DOM access │ │ ✓ Heavy computation │ │
│ │ ✓ React UI rendering │ │ ✓ No DOM (pure logic) │ │
│ │ ✓ Isolated document │ │ ✓ Better isolation │ │
│ │ │ │ │ │
│ │ Inspector Modal │ │ Vector Processor │ │
│ │ SVG Exporter │ │ Video Exporter │ │
│ └───────────────────────────┘ └───────────────────────────┘ │
│ │
│ Both types communicate via RPC messages with budget enforcement │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Permissions System
Permission Types
| Permission | Description | Auto-Granted |
|---|---|---|
| telemetry | Emit performance metrics | ✓ Yes |
| timeline.read | Read timeline state | ✓ Yes |
| workers | Use Web Workers | ✓ Yes |
| dom.iframe | Render iframe UI | Prompt |
| theme.access | Access theme tokens | Prompt |
| filesystem | File system access | ✓ Yes |
Permission Prompt
When a plugin requests a permission that requires user consent:
┌──────────────────────────────────────────────────────────────────────────┐
│ Permission Request │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ "Inspector Modal" is requesting: │
│ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ 📋 dom.iframe │ │
│ │ Allow this plugin to render an iframe interface. │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │
│ This permission allows the plugin to display its user interface. │
│ │
├──────────────────────────────────────────────────────────────────────────┤
│ [ Deny ] [ Allow ] │
└──────────────────────────────────────────────────────────────────────────┘
Revoking Permissions
In the plugin details drawer, you can revoke previously granted permissions:
- Open Plugin Manager
- Click on plugin row to open details
- Find the permission in the Permissions section
- Click Revoke next to the permission
Resource Budgets
Sandboxed plugins have resource limits:
PLUGIN BUDGETS
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ Resource Budget Warning Critical │
│ ───────────────────────────────────────────────────────────────────── │
│ CPU per frame 5ms 3x budget exceeded │
│ CPU per operation 6ms 3x budget exceeded │
│ Memory 79 MB 3x budget 2x budget │
│ Messages/second 96 3x budget 2x budget │
│ │
│ When a plugin exceeds its budget: │
│ • Warning → Yellow status in Plugin Manager │
│ • Critical → Plugin may be throttled or disabled │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Telemetry Dashboard
Click the 📊 icon in the plugin details to view telemetry:
┌──────────────────────────────────────────────────────────────────────────┐
│ Telemetry Dashboard [X] │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ [ Runtime ] [ UI ] │
│ │
│ RUNTIME METRICS │
│ ───────────────────────────────────────────────────────────────────── │
│ │
│ CPU Usage (per frame) │
│ ████████████░░░░░░░░░░░░░░░░░░ 2.4ms / 5ms budget │
│ │
│ Memory │
│ ██████░░░░░░░░░░░░░░░░░░░░░░░░ 18 MB / 79 MB budget │
│ │
│ Messages/second │
│ ████░░░░░░░░░░░░░░░░░░░░░░░░░░ 12 / 96 budget │
│ │
│ ───────────────────────────────────────────────────────────────────── │
│ │
│ RECENT EVENTS │
│ 12:45:32 plugin.initialized { pluginId: "inspector.modal.shell" } │
│ 12:45:33 panel.registered { panelId: "inspector-panel" } │
│ 12:46:01 scene.read { sceneId: "scene-1", objects: 5 } │
│ │
└──────────────────────────────────────────────────────────────────────────┘
Security Log
The security log tracks plugin-related security events:
SECURITY LOG
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ 🔒 Security Log [ Clear ] │
│ ─────────────────────────────────────────────────────────────────── │
│ │
│ 12:45:32 ⚠ Warning inspector.modal.shell │
│ Budget warning: CPU usage at 4.2ms (budget: 5ms) │
│ │
│ 12:46:01 ⚠ Warning processor.vector.default │
│ High message rate: 85/sec (budget: 96/sec) │
│ │
│ ─── No violations ─── │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Event Types
| Type | Icon | Description |
|---|---|---|
| Violation | 🚫 | Security rule broken |
| Warning | ⚠ | Approaching limits |
Plugin Actions
Reload
Restart a plugin without disabling it:
- Open plugin details drawer
- Click Reload
- Plugin reinitializes with fresh state
Use when: Plugin is behaving unexpectedly
Repair
Attempt to fix a broken plugin:
- Open plugin details drawer
- Click Repair
- System attempts to recover plugin state
Use when: Plugin shows error status
Revoke (Admin)
Permanently block a plugin version:
- Open plugin details drawer
- Click Revoke (requires admin rights)
- Enter reason for revocation
- Plugin cannot be enabled until updated
Keyboard Navigation
| Shortcut | Action |
|---|---|
↑ / ↓ | Navigate plugin list |
Enter | Open plugin details |
Space | Toggle plugin enable/disable |
Escape | Close drawer / Close panel |
Tab | Move focus to next element |
Home | Jump to first plugin |
End | Jump to last plugin |
Troubleshooting
Plugin Won't Enable
| Cause | Solution |
|---|---|
| Missing permissions | Grant required permissions |
| Version incompatible | Update plugin or app |
| Dependency missing | Enable required plugins first |
| Corrupted state | Try Repair action |
Plugin Shows Error
| Cause | Solution |
|---|---|
| Load failure | Check console for errors |
| Manifest invalid | Plugin needs update |
| Signature invalid | Contact plugin author |
| Budget exceeded | Reduce plugin usage |
Plugin UI Not Showing
| Cause | Solution |
|---|---|
| Plugin disabled | Enable in Plugin Manager |
| Permission denied | Grant dom.iframe permission |
| Feature flag off | Check feature flags |
| Panel collapsed | Expand the panel |
Performance Issues
| Cause | Solution |
|---|---|
| Too many plugins | Disable unused plugins |
| Budget exhaustion | Check telemetry dashboard |
| Memory leak | Reload the plugin |
| Heavy processing | Wait for operation to complete |
Best Practices
For Users
- Keep plugins updated — Updates include bug fixes and performance improvements
- Disable unused plugins — Free up resources for plugins you use
- Monitor telemetry — Check for budget warnings periodically
- Grant minimum permissions — Only allow what plugins need
For Performance
- Limit active processors — Only one vector processor needed
- Watch security log — Warnings indicate potential issues
- Reload periodically — Clears accumulated state
- Close Plugin Manager — Don't leave it open during work
Plugin Categories
By Function
| Category | Examples |
|---|---|
| UI Panels | Timeline, Inspector, Scene Manager |
| Animators | Hand Animator |
| Processors | Vector Processor |
| Exporters | SVG Exporter, Video Exporter |
By Sandbox Type
| Type | Examples |
|---|---|
| Host | Timeline Panel, Hand Animator, Audio Processor |
| Iframe | Inspector Modal, SVG Exporter |
| Worker | Vector Processor, Video Exporter |
Default Plugin States
On first launch, these plugins are enabled by default:
| Plugin | Default | Critical |
|---|---|---|
| Hand Animator | ✓ Enabled | Yes |
| Timeline Panel | ✓ Enabled | Yes |
| Scene Manager | ✓ Enabled | Yes |
| Audio Processor | ✓ Enabled | No |
| Inspector Modal | ✓ Enabled | Yes |
| Vector Processor | ✓ Enabled | Yes |
| SVG Exporter | ✓ Enabled | No |
| Video Exporter | ✓ Enabled | No |
note
Critical plugins are required for basic functionality. Disabling them will significantly reduce application capabilities.
File Locations
| Component | Path |
|---|---|
| Plugin Manager Panel | frontend/src/features/plugin-manager/ui/PluginManagerPanel.tsx |
| Plugin Host | frontend/src/plugins/host.ts |
| Plugin Registry State | frontend/src/features/plugin-manager/state/pluginRegistryState.ts |
| Architecture Docs | docs/architecture/PLUGIN_SYSTEM_ARCHITECTURE.md |
| Host Plugins | frontend/src/plugins/ |
| Sandboxed Plugins | plugins/ |