Architecture Overview

VS Code employs a multi-process architecture built on Electron. Extensions run in a dedicated Extension Host process, separate from the main UI rendering process. This separation ensures that extension code cannot block the editor's interface — a misbehaving extension might hang the Extension Host, but users can still type, save, and close files.

The Extension Host is a Node.js process exposing the VS Code API. Extensions are JavaScript/TypeScript packages with a manifest (package.json) declaring:

Key protocols enable language-agnostic tooling:

Security Model

VS Code extensions are not sandboxed. The Extension Host has the same permissions as VS Code itself:

The official documentation acknowledges this explicitly: "providing a scalable solution with full Node.js support is the reason for separating the extension process from the sandboxed Renderer Process."

Security relies on external measures:

Research has demonstrated these measures are insufficient. Security researchers have successfully published malicious extensions that bypass all checks using simple evasion techniques (detecting sandbox environments, delaying malicious behavior).

Performance Characteristics

VS Code's performance model is sophisticated:

What We Learned

VS Code demonstrates that process isolation provides stability (crash protection, non-blocking UI) but not security. The lazy loading model via activation events is excellent and worth emulating. The LSP/DAP approach of standardized protocols for common functionality reduces redundant work.

What We Avoid

The complete lack of sandboxing is unacceptable for Seed. Users should not need to trust that extension authors are benevolent. The "marketplace scanning" security model provides an illusion of safety without substance.

Architecture Overview

Figma employs a sophisticated dual-environment architecture specifically designed for security. Each plugin consists of two components:

Communication between these environments uses postMessage, creating a clear security boundary.

The evolution of this architecture is instructive. Figma initially used the Realms shim for sandboxing — a JavaScript-based approach to creating isolated execution contexts. Within weeks of launch, security researchers discovered vulnerabilities allowing sandbox escape. Figma quickly pivoted to QuickJS compiled to WebAssembly, their backup plan.

QuickJS-to-Wasm is fundamentally more secure because:

Security Model

Figma's model provides strong isolation:

Manual review focuses on user experience, not security auditing — the sandbox provides the security guarantee.

Performance Characteristics

Running JavaScript through an interpreter compiled to WebAssembly introduces overhead compared to JIT-compiled JavaScript. Figma accepts this tradeoff; they note the interpreter is slower than regular JavaScript since it's not a JIT, but performance is acceptable.

Key optimizations:

UI Limitations

The iframe approach has UX drawbacks:

What We Learned

Figma proves that strong sandboxing is achievable for browser-based applications. The QuickJS-to-Wasm approach provides real security guarantees, not security theater. The dual-environment model (sandbox for logic, iframe for UI) cleanly separates concerns.

What We Improve

Figma's iframe-only UI leads to inconsistent plugin experiences. By offering a declarative UI layer that Seed renders natively, we can achieve better visual integration while keeping iframes as an escape hatch.

Architecture Overview

Factorio uses a modified Lua 5.2 runtime for modding. The system operates in three distinct stages:

A critical constraint drives the entire design: multiplayer determinism. Factorio uses lockstep networking where all clients simulate identical game state. Every mod must produce identical results across different machines, or multiplayer desyncs occur.

This constraint influences everything:

Security Model

Factorio's security model prioritizes determinism over isolation. Mods have significant game state access but operate within Lua's inherent limitations.

Removed standard library modules:

The require() function only loads files from mod directories. Mods cannot access system files or network resources.

Performance Characteristics

Lua was chosen for its lightweight embedding and fast execution. The event-driven architecture enables efficient interaction — mods register handlers for specific events (on_entity_died, on_player_crafted_item) rather than polling.

The prototype/runtime split means expensive operations (defining hundreds of recipes, loading graphics) happen once at load time, not during gameplay. Runtime code responds to events and manipulates existing objects.

What We Learned

Factorio demonstrates that a well-designed event system can provide significant flexibility even within a restricted environment. The staged loading model (settings → prototypes → runtime) cleanly separates concerns. The determinism constraints, while specific to games, illustrate how environmental requirements shape architecture.

What Doesn't Apply

Factorio's threat model differs from ours. They're protecting against accidental desyncs, not malicious code. Their users install mods knowing they're modifying their single-player or self-hosted game. Seed handles collaborative documents across organizations — the trust model is fundamentally different.

Architecture Overview

Chrome extensions use a multi-component architecture:

Manifest V3 (the current extension format) introduced significant changes:

Security Model

Chrome uses a permission-based security model declared in manifest.json:

Manifest V3 tightened security:

Content scripts have reduced privileges:

Performance Characteristics

Service workers are ephemeral — they start on demand and shut down when idle. This reduces memory for inactive extensions but introduces cold start latency. Extensions must correctly handle the startup/shutdown lifecycle, persisting state to chrome.storage.

The declarativeNetRequest API moves network filtering to the browser process, improving performance over JavaScript-based webRequest but reducing flexibility (rules are static, not programmable).

Controversy

Manifest V3 has been controversial. The Electronic Frontier Foundation called it "deceitful and threatening," arguing it restricts privacy tools and ad blockers to benefit Google's advertising business. The shift toward declarative APIs (safer, more performant) comes at the cost of programmatic flexibility.

What We Learned

Chrome demonstrates the tension between security constraints and developer/user expectations. The permission model is more explicit than VS Code's but still relies on user approval rather than technical enforcement. The service worker model shows how ephemeral execution reduces resource usage.

What We Avoid

Chrome's permission prompts train users to click "Allow" without reading. Seed's capability model should be more granular and contextual, with meaningful distinctions that users can understand.

Architecture Overview

Minecraft modding operates through mod loaders that intercept and modify the game's Java bytecode at runtime. Two dominant loaders exist:

Forge (established 2011):

Fabric (established 2018):

Forge works by patching Minecraft's code at load time, inserting event dispatchers throughout. Mods subscribe to events (BlockBreakEvent, EntitySpawnEvent) and register content through registries.

Fabric's Mixin framework allows direct bytecode injection. Developers specify injection points using annotations, and the framework weaves mod code into vanilla classes at runtime. This is more surgical but requires deeper understanding of Minecraft internals.

Security Model

Minecraft mods have no security boundary whatsoever. Mods are Java code running with full JVM permissions:

The only protection is social: community trust, open-source code review, and distribution platform scanning. Malicious mods have caused real damage, including credential theft and cryptocurrency miners.

Performance Characteristics

Forge's heavyweight approach introduces baseline overhead but provides stability guarantees for complex modpacks with hundreds of mods. Its mature API reduces inter-mod conflicts.

Fabric's minimal footprint offers faster startup and lower memory overhead. Mixin's direct bytecode modification can be more performant than event dispatch for certain operations.

Both support large modpacks (100+ mods), though Forge historically handles complex dependencies better.

What We Learned

Minecraft demonstrates that users will accept significant security risks for powerful extensibility. The existence of both Forge (comprehensive but heavy) and Fabric (minimal but flexible) shows that different architectural philosophies serve different needs.

What We Avoid

The complete absence of sandboxing is unacceptable. Minecraft's trust model works only because users knowingly run local modifications to a game. Seed handles collaborative documents potentially containing sensitive information across organizational boundaries.

Architecture Overview

Obsidian is an Electron application, and its plugins are JavaScript/TypeScript code running directly in the application context. Plugins have access to:

The plugin architecture is straightforward: plugins are npm packages with a manifest.json, a main.js entry point, and optional styles.css. They load into the main Electron process with direct access to application internals.

Security Model

Obsidian's documentation is explicit: "Due to technical limitations in the plugin architecture, Obsidian cannot implement granular permission controls for community plugins. Instead, plugins inherit the full access level of the host application."

This means plugins can:

The only mitigation is community review before plugins appear in the official directory. This catches obvious issues but not sophisticated attacks.

Performance Characteristics

Plugins run in the main Electron process, so poorly-written plugins can block the UI. There's no lazy loading — enabled plugins load at startup. Performance varies wildly by plugin quality.

What We Learned

Obsidian's architecture is essentially identical to VS Code's — both are Electron applications with unsandboxed JavaScript plugins. The honesty of Obsidian's documentation about security limitations is refreshing, but the limitations themselves are concerning.

What We Avoid

Seed requires real security, not trust-based security theater. Users collaborating on documents should not need to worry that a teammate's installed plugin might exfiltrate data.

Architecture Overview

WordPress uses a hook-based plugin architecture implemented entirely in PHP. The system revolves around two types of hooks:

Actions: Execute code at specific points

add_action('wp_head', 'my_custom_function');

function my_custom_function() {
    echo '<meta name="custom" content="value">';
}

Filters: Modify data before it's used

add_filter('the_content', 'modify_content');

function modify_content($content) {
    return $content . '<p>Added by plugin</p>';
}

WordPress core (and themes) trigger hooks using do_action() and apply_filters(). A page request flows through hundreds of hooks, each providing an opportunity for plugins to inject behavior or modify content.

The WP_Hook class manages all registrations, storing callbacks with priorities that determine execution order.

Security Model

WordPress plugins have full server-side PHP execution capabilities:

Security relies on:

These are developer responsibilities, not enforced boundaries. Poorly-written plugins are a primary attack vector for WordPress sites, responsible for the majority of WordPress security breaches.

Performance Characteristics

Every active plugin adds overhead to every page request. Plugins registering many hooks or implementing expensive callbacks significantly impact performance. WordPress lacks lazy loading — all active plugins initialize on every request.

Caching (page, object, opcode) is the primary mitigation, but poorly-optimized plugins can defeat caching strategies.

What We Learned

WordPress's hook system is elegantly simple: register callbacks to named hooks, and they execute at the right time. The action/filter distinction (side effects vs. data transformation) is a useful conceptual model.

The WordPress ecosystem demonstrates that simple extensibility primitives can enable a massive plugin economy. The existence of plugins like WooCommerce shows that hook-based systems can support complex functionality.

What We Avoid

WordPress's complete lack of isolation makes it unsuitable as a security model. The server-side PHP execution model doesn't translate to our client-side/Wasm architecture anyway.

Architecture Overview

WebAssembly represents a new paradigm for plugin systems. Extism is a framework for building Wasm-based extensibility, providing:

The architecture:

WebAssembly Interface Types (WIT) define contracts between host and plugins with strong typing that goes beyond C's limitations.

Security Model

WebAssembly's security is fundamentally different from traditional plugin systems:

Capability-Based Security: By default, Wasm modules cannot access anything. The host explicitly grants capabilities:

Sandboxed Execution:

Interface Enforcement:

Performance Characteristics

WebAssembly approaches native performance through AOT or JIT compilation. Research shows Wasm is approximately 2.3× slower than native code for typical workloads, excluding cases where native code benefits from hardware-specific instructions.

Startup time is significantly faster than containers or VMs — Wasm instances spin up in milliseconds. Memory overhead per instance is minimal.

Real-World Adoption

WebAssembly plugins are used in production by:

What We Learned

WebAssembly solves the security-flexibility tradeoff that plagues other systems. True sandboxing with explicit capabilities, language-agnostic development, and near-native performance represent a genuine advance.

Extism specifically provides the infrastructure we need: host SDKs for both browser (JavaScript) and Electron (Node.js), PDKs for TypeScript and other languages, and a proven model for capability injection.

What We Build Upon

Seed's plugin architecture uses WebAssembly (via Extism) as its foundation. The sandboxing model, capability-based security, and host-mediated communication are exactly what we need. We extend this foundation with our declarative UI layer, schema-first blocks, and extension point model.

Traditionally, you could pick two:

Security + Performance → Limited Flexibility Chrome's Manifest V3 moves toward declarative APIs that are secure and performant but restrict what extensions can do.

Flexibility + Performance → No Security VS Code and Minecraft provide maximum capability with minimal overhead but zero isolation.

Security + Flexibility → Performance Cost Figma's QuickJS-to-Wasm approach is secure and reasonably capable but incurs interpreter overhead.

WebAssembly changes this equation:

The remaining constraint is communication overhead. If plugins need to make thousands of fine-grained calls per frame, message passing latency accumulates. This is acceptable for Seed's use case (document editing, not real-time game simulation).

Seed's plugin architecture consists of three layers:

┌─────────────────────────────────────────────────────────────────────┐
│                        SEED APPLICATION                              │
│                                                                      │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │                      MAIN THREAD                              │   │
│  │                                                               │   │
│  │   ┌─────────────┐  ┌─────────────┐  ┌────────────────────┐   │   │
│  │   │   Seed UI   │  │ Declarative │  │   iframe WebViews  │   │   │
│  │   │   (React)   │  │  Plugin UI  │  │   (escape hatch)   │   │   │
│  │   └─────────────┘  └─────────────┘  └────────────────────┘   │   │
│  │          │                │                    │              │   │
│  │          └────────────────┼────────────────────┘              │   │
│  │                           │                                    │   │
│  │                    Message Passing                             │   │
│  │                           │                                    │   │
│  └───────────────────────────┼────────────────────────────────────┘   │
│                              │                                        │
│  ┌───────────────────────────┼────────────────────────────────────┐   │
│  │                    WORKER THREAD(S)                            │   │
│  │                           │                                    │   │
│  │   ┌───────────────────────▼───────────────────────────────┐   │   │
│  │   │              WASM RUNTIME (Extism)                     │   │   │
│  │   │                                                        │   │   │
│  │   │   ┌──────────┐  ┌──────────┐  ┌──────────┐            │   │   │
│  │   │   │ Plugin A │  │ Plugin B │  │ Plugin C │   ...      │   │   │
│  │   │   │  .wasm   │  │  .wasm   │  │  .wasm   │            │   │   │
│  │   │   └──────────┘  └──────────┘  └──────────┘            │   │   │
│  │   │                                                        │   │   │
│  │   │   ┌────────────────────────────────────────────────┐  │   │   │
│  │   │   │           CAPABILITY LAYER                      │  │   │   │
│  │   │   │   Network │ Storage │ Document │ UI │ ...      │  │   │   │
│  │   │   └────────────────────────────────────────────────┘  │   │   │
│  │   └────────────────────────────────────────────────────────┘   │   │
│  │                                                                │   │
│  └────────────────────────────────────────────────────────────────┘   │
│                                                                       │
│  ┌────────────────────────────────────────────────────────────────┐   │
│  │               ELECTRON ONLY: NODE.JS BACKEND                   │   │
│  │                (optional, for native integrations)              │   │
│  └────────────────────────────────────────────────────────────────┘   │
│                                                                       │
└───────────────────────────────────────────────────────────────────────┘

We use Extism as our Wasm runtime framework. Extism provides:

Host SDK (runs in our worker):

Plugin Development Kit (used by plugin authors):

Why Extism over raw Wasm runtimes:

Plugin Wasm code runs in Web Workers (browser) or Worker Threads (Node.js/Electron). This provides:

Non-Blocking UI: The main thread remains responsive regardless of plugin behavior. A plugin stuck in an infinite loop cannot freeze the editor.

Crash Isolation: A plugin crash terminates only its worker, not the entire application.

Security Boundary: Workers have limited access to the main thread's context. Combined with Wasm sandboxing, this creates defense in depth.

Architecture by Platform:

| Context | Web Browser | Electron | |---------|-------------|----------| | UI Extensions | Web Worker | Web Worker (renderer process) | | Services | Web Worker | Worker Thread (can use Node.js APIs) | | Document Access | Via main thread message | Via main thread message |

All communication between plugins and the host uses structured message passing:

// Host → Plugin
interface HostMessage {
  type: 'invoke' | 'event' | 'response';
  id: string;           // Correlation ID for request/response
  surface: string;      // Which plugin surface (block, action, etc.)
  payload: unknown;     // Typed by surface schema
}

// Plugin → Host  
interface PluginMessage {
  type: 'request' | 'response' | 'ui-update';
  id: string;
  payload: unknown;
}

Message Types:

The protocol is symmetric and asynchronous. All operations that might take time return Promises resolved via response messages.

Most plugin UIs don't need arbitrary HTML/CSS/JavaScript. They need forms, lists, buttons, and status displays. By providing a declarative component vocabulary, Seed can render plugin UIs natively, ensuring:

Core Component Vocabulary:

type SeedUIComponent =
  // Layout
  | { type: 'container'; direction: 'row' | 'column'; children: SeedUIComponent[] }
  | { type: 'divider' }
  | { type: 'spacer'; size: 'small' | 'medium' | 'large' }
  
  // Typography
  | { type: 'text'; content: string; variant?: 'body' | 'caption' | 'code' }
  | { type: 'heading'; content: string; level: 1 | 2 | 3 }
  
  // Form Controls
  | { type: 'textInput'; id: string; label: string; placeholder?: string; value?: string }
  | { type: 'textArea'; id: string; label: string; rows?: number; value?: string }
  | { type: 'select'; id: string; label: string; options: Array<{value: string; label: string}>; value?: string }
  | { type: 'checkbox'; id: string; label: string; checked?: boolean }
  | { type: 'toggle'; id: string; label: string; enabled?: boolean }
  | { type: 'slider'; id: string; label: string; min: number; max: number; value?: number }
  
  // Actions
  | { type: 'button'; id: string; label: string; variant?: 'primary' | 'secondary' | 'danger' }
  | { type: 'buttonGroup'; children: Array<{ type: 'button'; id: string; label: string }> }
  
  // Display
  | { type: 'image'; src: string; alt: string; width?: number; height?: number }
  | { type: 'icon'; name: string; size?: 'small' | 'medium' | 'large' }
  | { type: 'badge'; content: string; variant?: 'info' | 'success' | 'warning' | 'error' }
  | { type: 'progressBar'; value: number; max: number }
  
  // Structure
  | { type: 'list'; items: Array<{ id: string; primary: string; secondary?: string; icon?: string }> }
  | { type: 'tabs'; id: string; tabs: Array<{ id: string; label: string; content: SeedUIComponent[] }> }
  | { type: 'accordion'; sections: Array<{ id: string; title: string; content: SeedUIComponent[] }> }
  
  // Escape Hatch
  | { type: 'webView'; id: string; src: string; height: number };

This vocabulary covers ~95% of plugin UI needs. This approach follows successful prior art:

Plugins describe their UI declaratively:

const ui: SeedUIComponent = {
  type: 'container',
  direction: 'column',
  children: [
    { type: 'heading', content: 'Import Settings', level: 2 },
    { type: 'textInput', id: 'url', label: 'Source URL', placeholder: 'https://...' },
    { type: 'select', id: 'format', label: 'Format', options: [
      { value: 'json', label: 'JSON' },
      { value: 'csv', label: 'CSV' },
    ]},
    { type: 'checkbox', id: 'overwrite', label: 'Overwrite existing data' },
    { type: 'divider' },
    { type: 'buttonGroup', children: [
      { type: 'button', id: 'cancel', label: 'Cancel', variant: 'secondary' },
      { type: 'button', id: 'import', label: 'Import', variant: 'primary' },
    ]},
  ],
};

Seed renders this using its native React components. The plugin never touches the DOM.

Some plugins genuinely need capabilities beyond declarative UI:

For these cases, the webView component embeds an iframe:

const ui: SeedUIComponent = {
  type: 'container',
  direction: 'column',
  children: [
    { type: 'heading', content: '3D Model Preview', level: 2 },
    { type: 'webView', id: 'preview', src: 'plugin://model-viewer/preview.html', height: 400 },
    { type: 'button', id: 'import', label: 'Import to Document', variant: 'primary' },
  ],
};

The iframe loads content bundled with the plugin. It has browser APIs (Canvas, WebGL, fetch) but runs in a null-origin sandbox.

The key insight — and what makes this architecture elegant — is that iframes are leaf nodes in the declarative tree, not a separate mode. This means:

Example: Video Editor Plugin

const ui: SeedUIComponent = {
  type: 'container',
  direction: 'column',
  children: [
    { type: 'heading', content: 'Video Trimmer', level: 2 },
    
    // Declarative: native Seed components
    { type: 'textInput', id: 'title', label: 'Video Title', value: 'Untitled' },
    
    // Escape hatch: custom video timeline UI
    { type: 'webView', id: 'timeline', src: 'plugin://video-editor/timeline.html', height: 200 },
    
    // Declarative again
    { type: 'container', direction: 'row', children: [
      { type: 'text', content: 'Start: ' },
      { type: 'textInput', id: 'startTime', label: '', value: '00:00' },
      { type: 'text', content: 'End: ' },
      { type: 'textInput', id: 'endTime', label: '', value: '00:30' },
    ]},
    
    { type: 'button', id: 'apply', label: 'Apply Trim', variant: 'primary' },
  ],
};

The video timeline (a complex interactive canvas) uses the escape hatch, while everything else is native.

With iframes in the picture, plugins span three execution contexts:

┌───────────────────────────────────────────────────────────────────────────┐
│                                                                           │
│  CONTEXT 1: Worker Thread                                                 │
│  ┌─────────────────────────────────────────────────────────────────────┐  │
│  │  Wasm Plugin Code                                                    │  │
│  │  - Business logic                                                    │  │
│  │  - Document manipulation                                             │  │
│  │  - State management                                                  │  │
│  │  - Produces declarative UI descriptions                              │  │
│  └─────────────────────────────────────────────────────────────────────┘  │
│       │                                                                    │
│       │ postMessage (structured data)                                      │
│       ▼                                                                    │
│  CONTEXT 2: Main Thread                                                   │
│  ┌─────────────────────────────────────────────────────────────────────┐  │
│  │  Seed Host Application                                               │  │
│  │  - Renders declarative UI using React                                │  │
│  │  - Creates iframe elements for webView components                    │  │
│  │  - Routes events back to Wasm                                        │  │
│  │  - Mediates all communication                                        │  │
│  └─────────────────────────────────────────────────────────────────────┘  │
│       │                                                                    │
│       │ postMessage (to iframe)                                            │
│       ▼                                                                    │
│  CONTEXT 3: iframe (when webView used)                                    │
│  ┌─────────────────────────────────────────────────────────────────────┐  │
│  │  Plugin UI Code (JavaScript)                                         │  │
│  │  - Custom rendering (Canvas, WebGL, DOM)                             │  │
│  │  - Browser APIs (fetch, localStorage*)                               │  │
│  │  - Handles local interactions                                        │  │
│  │  - Sends significant events back to main thread                      │  │
│  │                                                                       │  │
│  │  * localStorage scoped to plugin origin                               │  │
│  └─────────────────────────────────────────────────────────────────────┘  │
│                                                                           │
└───────────────────────────────────────────────────────────────────────────┘

Communication Paths:

This architecture ensures the host can audit, rate-limit, and control all communication.

Plugin authors shouldn't need to think about the three contexts. The TypeScript SDK provides a unified authoring experience:

// youtube-block.ts — single file, SDK handles the split

import { defineBlock, ui, webView } from '@seed/plugin-sdk';

export const youtubeBlock = defineBlock({
  name: 'youtube-embed',
  schema: z.object({
    videoId: z.string(),
    startTime: z.number().optional(),
  }),
  
  // Runs in Wasm context
  async onRender(ctx) {
    const { videoId, startTime } = ctx.blockData;
    
    return ui.container({ direction: 'column' }, [
      ui.heading('YouTube Video', 2),
      
      // This webView is authored inline but extracted to iframe bundle
      webView({
        id: 'player',
        height: 315,
        
        // This function runs in iframe context
        render: ({ onMessage, sendMessage }) => {
          const container = document.createElement('div');
          
          // Use YouTube iframe API
          const player = new YT.Player(container, {
            videoId: ctx.blockData.videoId,  // Captured from outer scope
            playerVars: { start: ctx.blockData.startTime || 0 },
            events: {
              onStateChange: (e) => sendMessage({ type: 'state', state: e.data }),
            },
          });
          
          onMessage('seek', (time) => player.seekTo(time));
          
          return container;
        },
      }),
      
      ui.button('Copy Link', { id: 'copy', variant: 'secondary' }),
    ]);
  },
  
  // Runs in Wasm context
  async onEvent(ctx, event) {
    if (event.type === 'click' && event.id === 'copy') {
      const url = `https://youtube.com/watch?v=${ctx.blockData.videoId}`;
      await ctx.clipboard.write(url);
      ctx.toast('Link copied!');
    }
  },
});

The SDK build toolchain:

Block extensions render custom block types or provide alternative renderers for existing blocks.

Manifest Declaration:

{
  "surfaces": {
    "mermaidRenderer": {
      "type": "block",
      "extends": "code",
      "when": { "language": "mermaid" },
      "schema": "./schemas/mermaid.json",
      "entry": "blocks/mermaid.wasm"
    },
    "customDiagram": {
      "type": "block",
      "blockType": "custom-diagram",
      "schema": "./schemas/diagram.json",
      "entry": "blocks/diagram.wasm"
    }
  }
}

Capabilities:

Lifecycle:

Block appears in viewport
         │
         ▼
    Load plugin Wasm (if not loaded)
         │
         ▼
    Call onRender(blockData) ──────► Returns UI description
         │
         ▼
    Host renders UI
         │
         ├──► User interacts ──► onEvent(event) ──► May return new UI
         │
         ├──► Block data changes (collab edit) ──► onRender(newData)
         │
         └──► Block leaves viewport ──► onUnmount() (cleanup)

Actions are commands users can invoke. They appear in command palettes, context menus, or keyboard shortcuts.

Manifest Declaration:

{
  "surfaces": {
    "formatDocument": {
      "type": "action",
      "label": "Format Document",
      "description": "Apply consistent formatting to the document",
      "icon": "format-align-left",
      "shortcut": "Cmd+Shift+F",
      "parameters": {
        "type": "object",
        "properties": {
          "style": { "enum": ["compact", "spaced", "academic"] }
        }
      },
      "entry": "actions/format.wasm"
    }
  }
}

Capabilities:

Execution Flow:

User triggers action (menu, shortcut, command palette)
         │
         ▼
    Parameter collection (if parameters defined)
         │
         ▼
    Call onExecute(params, context)
         │
         ├──► Plugin reads document
         │
         ├──► Plugin performs computation
         │
         ├──► Plugin requests writes ──► Host validates & applies
         │
         └──► Plugin returns result ──► Host shows completion

Services are long-running background processes that respond to events or provide capabilities to other plugins.

Manifest Declaration:

{
  "surfaces": {
    "aiService": {
      "type": "service",
      "provides": ["text-completion", "summarization"],
      "capabilities": {
        "network": ["api.openai.com"]
      },
      "entry": "services/ai.wasm"
    }
  }
}

Capabilities:

Use Cases:

Page extensions add new pages/views to Seed's navigation, like settings panels or dashboards.

Manifest Declaration:

{
  "surfaces": {
    "analyticsPage": {
      "type": "page",
      "path": "/plugins/analytics",
      "label": "Analytics Dashboard",
      "icon": "chart-bar",
      "navigation": "sidebar",
      "entry": "pages/analytics.wasm"
    }
  }
}

Capabilities:

Unlike permission-based models (where users approve capabilities at install time), capability-based security means the host explicitly provides each capability to plugins. Plugins cannot discover or access capabilities they haven't been granted.

In practice:

This is fundamentally more secure than permission prompts because:

By default, plugins cannot make network requests. The Wasm sandbox has no fetch, no XMLHttpRequest, no WebSocket.

Plugins that need network access:

{
  "capabilities": {
    "network": ["api.example.com", "cdn.example.com"]
  }
}

// Inside Wasm, plugin calls:
const response = await Host.httpRequest({
  method: 'GET',
  url: 'https://api.example.com/data',
  headers: { 'Authorization': 'Bearer ...' },
});

Why host-mediated networking:

Document access is the most sensitive capability for Seed. Plugins can request:

Read Access:

Write Access:

Access Flow:

// Plugin requests document content
const page = await ctx.document.getCurrentPage();

// Host checks:
// 1. Does plugin have document:read:current-page capability?
// 2. Is user authenticated with access to this page?
// 3. Are there any collaboration locks?

// If approved, host returns sanitized document data

Write Validation:

All document writes go through the host:

// Plugin requests a write
await ctx.document.updateBlock(blockId, newData);

// Host validates:
// 1. Does plugin have write capability for this scope?
// 2. Does newData match the block's schema?
// 3. Is the write valid per CRDT rules?
// 4. Apply through sync layer (handles conflicts)

Plugins can store persistent data scoped to themselves:

// Simple key-value storage
await ctx.storage.set('preferences', { theme: 'dark' });
const prefs = await ctx.storage.get('preferences');

Constraints:

Plugins declare which UI surfaces they need:

{
  "ui": {
    "panel": true,
    "modal": true,
    "contextMenu": true,
    "notification": true,
    "webView": false
  }
}

Why declare UI capabilities:

The webView: true capability triggers a specific warning (see section 14.3).

When a plugin requests capabilities, Seed shows contextual prompts:

At Install Time (basic capabilities):

┌──────────────────────────────────────────────────────────┐
│  Install "Mermaid Diagrams"?                             │
│                                                          │
│  This plugin will be able to:                            │
│  ✓ Render mermaid code blocks                            │
│  ✓ Store preferences                                     │
│                                                          │
│  [Cancel]                              [Install Plugin]  │
└──────────────────────────────────────────────────────────┘

At First Use (sensitive capabilities):

┌──────────────────────────────────────────────────────────┐
│  "AI Assistant" wants to access:                         │
│                                                          │
│  ⚠️  Read all content on this page                       │
│  ⚠️  Connect to api.openai.com                           │
│                                                          │
│  This allows the plugin to send your document content    │
│  to OpenAI's servers for processing.                     │
│                                                          │
│  [Deny]     [Allow Once]     [Always Allow]              │
└──────────────────────────────────────────────────────────┘

For Unrestricted UI (webView with network):

┌──────────────────────────────────────────────────────────┐
│  ⚠️  "YouTube Embed" requests enhanced access            │
│                                                          │
│  This plugin includes components with full browser       │
│  access. It can:                                         │
│                                                          │
│  • Connect to any website                                │
│  • Use browser features (cookies, storage)               │
│  • Track your activity within the plugin                 │
│                                                          │
│  Only install if you trust the developer.                │
│                                                          │
│  [Cancel]                              [I Understand]    │
└──────────────────────────────────────────────────────────┘

When a plugin updates and requests new capabilities, users must re-consent:

Version 1.0:

{ "capabilities": { "storage": true } }

Version 2.0:

{ "capabilities": { "storage": true, "network": ["api.example.com"] } }

On update, Seed shows:

┌──────────────────────────────────────────────────────────┐
│  "Example Plugin" update requires new permissions        │
│                                                          │
│  New capabilities requested:                             │
│  ⚠️  Connect to api.example.com                          │
│                                                          │
│  [Skip Update]           [Review & Update]               │
└──────────────────────────────────────────────────────────┘

This prevents plugins from acquiring capabilities through silent updates.

Every block type (native or plugin-provided) must define a schema. This is not optional. Schemas enable:

Validation at Write Time: Malformed data never persists. If a plugin tries to write invalid data, the host rejects it.

Validation at Read Time: Plugins receive data guaranteed to match their schema. No defensive coding against malformed input.

Portability: Seed understands block structure without executing plugin code. This enables:

Type Safety: TypeScript SDK generates types from schemas. Plugin code has full IDE support.

Plugins can define schemas using JSON Schema or Zod (TypeScript):

JSON Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "videoId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{11}$" },
    "startTime": { "type": "number", "minimum": 0 },
    "autoplay": { "type": "boolean", "default": false }
  },
  "required": ["videoId"]
}

Zod (TypeScript):

import { z } from 'zod';

export const youtubeBlockSchema = z.object({
  videoId: z.string().regex(/^[A-Za-z0-9_-]{11}$/),
  startTime: z.number().min(0).optional(),
  autoplay: z.boolean().default(false),
});

export type YouTubeBlockData = z.infer<typeof youtubeBlockSchema>;

The SDK converts Zod schemas to JSON Schema for the manifest. Plugin code uses the Zod types directly.

Plugins can reference Seed's built-in types:

import { z } from 'zod';
import { SeedSchemas } from '@seed/plugin-sdk';

export const taskBlockSchema = z.object({
  title: z.string(),
  
  // Reference to another document
  linkedDoc: SeedSchemas.documentRef,
  
  // Rich text in Seed's native format
  description: SeedSchemas.richText,
  
  // Reference to a Seed user
  assignee: SeedSchemas.userRef,
  
  // Timestamp in Seed's format
  dueDate: SeedSchemas.timestamp,
  
  // Reference to an uploaded file
  attachment: SeedSchemas.fileRef.optional(),
});

Why native primitives matter:

Plugin requests document write
         │
         ▼
    ┌────────────────────────────┐
    │   Host validates schema    │
    │                            │
    │   1. Check required fields │
    │   2. Validate types        │
    │   3. Run custom validators │
    │   4. Check constraints     │
    └────────────────────────────┘
         │
         ├──► Invalid: Reject write, return error to plugin
         │
         └──► Valid: Apply through sync layer
                      │
                      ▼
                 Persisted to network
                      │
                      ▼
                 Replicated to collaborators

When loading blocks:

Block data retrieved from network
         │
         ▼
    ┌────────────────────────────┐
    │   Host validates schema    │
    │   (same checks)            │
    └────────────────────────────┘
         │
         ├──► Invalid: Render with warning, offer repair
         │
         └──► Valid: Pass to plugin.onRender()

Schemas evolve. Plugins must handle this gracefully.

Additive Changes (safe):

// v1
z.object({ videoId: z.string() });

// v2 - adds optional field
z.object({ 
  videoId: z.string(),
  startTime: z.number().optional(),  // New, optional
});

Old data remains valid. Plugin handles missing startTime.

Breaking Changes (require migration):

// v1
z.object({ videoId: z.string() });

// v2 - renames field
z.object({ videoUrl: z.string() });  // Breaking!

Plugins declare migrations:

export const migrations = {
  '1→2': (data: V1Data): V2Data => ({
    videoUrl: `https://youtube.com/watch?v=${data.videoId}`,
  }),
};

Seed runs migrations before passing data to the plugin:

When User A creates a block with Plugin X, and User B opens the document without Plugin X:

┌─────────────────────────────────────────────────────────┐
│  ⚠️ YouTube Embed                                       │
│                                                         │
│  This block requires the "YouTube" plugin to display.   │
│                                                         │
│  Block data:                                            │
│  • videoId: "dQw4w9WgXcQ"                               │
│  • startTime: 42                                        │
│                                                         │
│  [Install Plugin]    [Show as JSON]                     │
└─────────────────────────────────────────────────────────┘

Because Seed has the schema, it can:

Seed provides robust native blocks that handle common use cases without plugins:

Critical design principle: Native blocks should handle as much as possible. For example, the native video block already handles YouTube URLs — it doesn't require a "YouTube plugin" to function. Plugins enhance the native experience (custom player controls, chapter markers, etc.) rather than providing basic functionality.

These native blocks work for all users without plugins. They're the foundation that ensures content is always accessible.

Rather than creating "mermaid-block" or "youtube-block" as entirely new block types, plugins extend native blocks:

Code Block Extension:

{
  "surfaces": {
    "mermaidRenderer": {
      "type": "block",
      "extends": "code",
      "when": { "language": "mermaid" },
      "entry": "blocks/mermaid.wasm"
    }
  }
}

This says: "When a code block has language: mermaid, I can render it."

Video Block Extension:

{
  "surfaces": {
    "youtubeEnhanced": {
      "type": "block",
      "extends": "video",
      "when": { "urlPattern": "youtube.com|youtu.be" },
      "entry": "blocks/youtube.wasm"
    }
  }
}

This says: "When a video block's URL matches YouTube, I can provide enhanced rendering."

Benefits:

When multiple plugins can handle a block, Seed presents a choice similar to operating system file associations:

┌─────────────────────────────────────────────────────────┐
│  How would you like to render this code block?          │
│                                                         │
│  Language: mermaid                                      │
│                                                         │
│  ○ Seed (syntax highlighting only)                      │
│  ◉ Mermaid Diagrams (render as diagram)                 │
│  ○ Mermaid Pro (render with themes)                     │
│                                                         │
│  ☐ Remember this choice for mermaid blocks              │
│                                                         │
│  [Cancel]                            [Use Selection]    │
└─────────────────────────────────────────────────────────┘

User preferences stored:

{
  "blockHandlers": {
    "code:mermaid": "plugin:mermaid-diagrams",
    "code:graphviz": "plugin:graphviz-renderer",
    "video:youtube.com": "plugin:youtube-enhanced"
  }
}

When rendering a block, Seed follows this priority:

If a plugin crashes or times out, Seed falls back to native rendering with a warning:

┌─────────────────────────────────────────────────────────┐
│  ⚠️ Plugin renderer failed                              │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │ ```mermaid                                       │   │
│  │ graph TD                                        │   │
│  │   A-->B                                         │   │
│  │ ```                                             │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  [Retry]  [Report Issue]  [Use Seed Renderer]          │
└─────────────────────────────────────────────────────────┘

When block data changes (from any source — local edit, collaborator edit, sync resolution), the plugin receives an event:

export const diagramBlock = defineBlock({
  // ...
  
  async onStateUpdate(ctx, previousData, newData, source) {
    // source: 'local' | 'remote' | 'migration'
    
    if (source === 'remote') {
      // Collaborator made a change
      // Re-render with new data
      return this.onRender(ctx);
    }
    
    // Local changes already reflected
    return null;  // No UI update needed
  },
});

The host calls onStateUpdate whenever block data changes, regardless of source. Plugins don't need to poll or subscribe — the host pushes updates.

Plugins don't directly mutate document state. They request writes:

async function addItem(ctx: PluginContext, item: string) {
  // Request a write
  const result = await ctx.document.updateBlock(ctx.blockId, (data) => ({
    ...data,
    items: [...data.items, item],
  }));
  
  if (result.conflict) {
    // Another edit happened simultaneously
    // result.resolved contains the merged state
    // Plugin can accept or retry
  }
}

Write Flow:

Seed works offline. Plugins must handle:

Offline Writes:

const result = await ctx.document.updateBlock(id, transform);

if (result.status === 'queued') {
  // Write accepted locally, will sync when online
  // UI should reflect the local state
}

Network Requests Offline:

try {
  const data = await ctx.network.fetch(url);
} catch (e) {
  if (e.code === 'OFFLINE') {
    // Show cached data or offline message
    return ui.text('Content unavailable offline');
  }
}

Sync Conflicts:

When the user comes back online, edits may conflict with remote changes. Seed's CRDT layer resolves most conflicts automatically. If manual resolution is needed, Seed handles the UI — plugins receive the resolved state via onStateUpdate.

Seed runs as both an Electron desktop app and a web application. Plugins should work identically on both platforms.

Identical Behavior:

| Capability | Web | Electron | |------------|-----|----------| | Wasm execution | ✅ Web Worker | ✅ Web Worker (renderer) | | Declarative UI | ✅ | ✅ | | webView (iframe) | ✅ | ✅ | | Network (permitted) | ✅ | ✅ | | Storage | ✅ | ✅ (synced) | | Document access | ✅ | ✅ | | Plugin-to-plugin | ✅ | ✅ |

Electron-Only (explicitly unavailable on web):

| Capability | Web | Electron | |------------|-----|----------| | Filesystem access | ❌ | ❌ (intentionally disabled) | | System notifications | Limited | ❌ (intentionally disabled) | | Native menus | ❌ | ❌ (use Seed's UI) | | Shell integration | ❌ | ❌ (security risk) |

We intentionally disable Electron-specific capabilities to maintain parity. Plugins cannot rely on running in Electron.

For UI-centric surfaces (blocks, pages):

For service surfaces:

Why not use Node.js for Electron services:

Node.js Worker Threads have access to Node APIs (filesystem, native modules). Using them would break parity with web and create security inconsistencies. By keeping all plugin code in browser-like workers, we maintain uniform sandboxing.

To maintain security and parity, these capabilities are explicitly not supported:

Plugins that need these capabilities are outside Seed's plugin model. They could potentially be implemented as separate applications communicating via Seed's API.

WebAssembly provides strong isolation guarantees:

Memory Safety:

Execution Isolation:

No Implicit Capabilities:

Deterministic Execution:

iframes (webView components) have different trust characteristics:

iframe CAN:

iframe CANNOT:

Residual Risk:

If Wasm sends sensitive document data to an iframe for visualization, the iframe JavaScript could exfiltrate it via fetch. Mitigations:

Plugins declare their rendering mode:

{
  "surfaces": {
    "basicBlock": {
      "type": "block",
      "render": "sandboxed"  // Declarative UI only
    },
    "complexBlock": {
      "type": "block",
      "render": "unrestricted"  // Can use webView with network
    }
  }
}

"sandboxed" render mode:

"unrestricted" render mode:

The prompt for unrestricted UI clearly communicates risks:

⚠️ This plugin requests enhanced UI access

It can:
• Display custom web content
• Connect to external websites
• Use cookies and browser storage

Your document content may be visible to this plugin's
UI components. Only install if you trust the developer.

Threat: Malicious plugin exfiltrates document data

Mitigations:

Residual risk: User approves network to attacker's domain. Mitigation: Domain reputation checking, warnings for new/unknown domains.

Threat: Plugin crashes repeatedly, degrading experience

Mitigations:

Threat: Plugin consumes excessive resources

Mitigations:

Threat: Plugin performs clickjacking via iframe

Mitigations:

Threat: Plugin supply chain attack (compromised update)

Mitigations:

The primary SDK is TypeScript, optimized for developer experience:

import { 
  defineBlock, 
  defineAction, 
  defineService,
  ui,
  z,
} from '@seed/plugin-sdk';

// Full type inference from schemas
const schema = z.object({
  title: z.string(),
  count: z.number().min(0),
});

export const counterBlock = defineBlock({
  name: 'counter',
  schema,
  
  // ctx.blockData is typed as { title: string; count: number }
  async onRender(ctx) {
    return ui.container({ direction: 'column' }, [
      ui.heading(ctx.blockData.title, 2),
      ui.text(`Count: ${ctx.blockData.count}`),
      ui.button('Increment', { id: 'inc' }),
    ]);
  },
  
  async onEvent(ctx, event) {
    if (event.type === 'click' && event.id === 'inc') {
      await ctx.document.updateBlock(ctx.blockId, (data) => ({
        ...data,
        count: data.count + 1,  // Typed!
      }));
    }
  },
});

SDK Features:

Developers can write plugins in any language compiling to Wasm:

Rust:

use seed_plugin_sdk::prelude::*;

#[seed_block]
pub struct CounterBlock {
    title: String,
    count: u32,
}

impl Block for CounterBlock {
    fn render(&self, ctx: &Context) -> UI {
        ui::container(Direction::Column, vec![
            ui::heading(&self.title, 2),
            ui::text(&format!("Count: {}", self.count)),
            ui::button("Increment").id("inc"),
        ])
    }
    
    fn on_event(&mut self, ctx: &mut Context, event: Event) {
        if event.is_click("inc") {
            self.count += 1;
            ctx.update_block(self);
        }
    }
}

Go:

package main

import (
    sdk "github.com/seed/plugin-sdk-go"
)

type CounterBlock struct {
    Title string `json:"title"`
    Count int    `json:"count"`
}

func (b *CounterBlock) Render(ctx *sdk.Context) sdk.UI {
    return sdk.Container(sdk.Column,
        sdk.Heading(b.Title, 2),
        sdk.Text(fmt.Sprintf("Count: %d", b.Count)),
        sdk.Button("Increment").ID("inc"),
    )
}

func (b *CounterBlock) OnEvent(ctx *sdk.Context, event sdk.Event) {
    if event.IsClick("inc") {
        b.Count++
        ctx.UpdateBlock(b)
    }
}

Lower-level SDKs provide the same capabilities with less automatic magic. Developers handle more serialization/deserialization themselves.

The UI components available in all SDKs:

namespace ui {
  // Layout
  function container(props: ContainerProps, children: Component[]): Component;
  function divider(): Component;
  function spacer(size: 'small' | 'medium' | 'large'): Component;
  
  // Typography
  function text(content: string, props?: TextProps): Component;
  function heading(content: string, level: 1 | 2 | 3): Component;
  
  // Form Controls
  function textInput(props: TextInputProps): Component;
  function textArea(props: TextAreaProps): Component;
  function select(props: SelectProps): Component;
  function checkbox(props: CheckboxProps): Component;
  function toggle(props: ToggleProps): Component;
  function slider(props: SliderProps): Component;
  
  // Actions
  function button(label: string, props?: ButtonProps): Component;
  function buttonGroup(buttons: ButtonProps[]): Component;
  
  // Display
  function image(props: ImageProps): Component;
  function icon(name: string, props?: IconProps): Component;
  function badge(content: string, props?: BadgeProps): Component;
  function progressBar(value: number, max: number): Component;
  
  // Structure
  function list(props: ListProps): Component;
  function tabs(props: TabsProps): Component;
  function accordion(props: AccordionProps): Component;
  
  // Escape Hatch
  function webView(props: WebViewProps): Component;
}