npm package: @fatagnus/dink-ui-plugins
Description: Plugin host system for Dink UI — trust-class isolation, bridge API, micro-frontend loader
Author: Ozan Turksever
Latest version: 2.32.0

# @fatagnus/dink-ui-plugins

Plugin host system for Dink UI -- trust-class isolation, bridge API, manifest validation, and micro-frontend loader.

## Install

```bash
npm install @fatagnus/dink-ui-plugins
```

Peer dependencies: `@fatagnus/dink-semantic`, `@fatagnus/dink-web`, `react`.

## Quick Start

```tsx
import { PluginHost, PluginSlot, PluginRegistry } from '@fatagnus/dink-ui-plugins';

const registry = new PluginRegistry();

function Dashboard() {
  return (
    <PluginHost registry={registry}>
      <PluginSlot slotId="sidebar-widget" />
    </PluginHost>
  );
}
```

## Plugin Manifest (`dink-plugin.json`)

```json
{
  "id": "siem-alert-map",
  "name": "Alert Map",
  "version": "1.0.0",
  "entry": "./dist/index.js",
  "surfaces": ["desktop", "tablet"],
  "trustClass": "verified",
  "permissions": {
    "scopes": ["read", "subscribe"],
    "resources": ["dink://alerts/**"]
  },
  "semantic": {
    "role": "widget",
    "intent": "Display alert geo-map",
    "actions": { "refresh": { "description": "Reload alert data" } }
  }
}
```

Validate with `validateManifest(json)` which uses Zod under the hood.

## Trust-Class Isolation Tiers

| Trust Class | Isolation | Use Case |
|---|---|---|
| `privileged` | Same React tree, full API | First-party modules |
| `verified` | Same React tree, scoped bridge | Audited third-party plugins |
| `untrusted` | Sandboxed iframe, message-passing | Unknown/community plugins |

## Key Exports

### Host Components

| Export | Description |
|---|---|
| `PluginHost` | Top-level provider -- manages plugin lifecycle and bridge instances |
| `PluginSlot` | Mounting point that renders a plugin by slot ID |
| `PluginLoader` | Low-level loader for dynamic import of plugin entry modules |

### Bridge API

| Export | Description |
|---|---|
| `createPluginBridge(config)` | Create a bridge instance for plugin-host communication |
| `IframeBridgeHost` | Host-side bridge for untrusted iframe plugins |
| `PluginBridge` | Type: read state, invoke actions, subscribe to semantic tree changes |

### Manifest (`./manifest`)

| Export | Description |
|---|---|
| `validateManifest(json)` | Validate and parse a `dink-plugin.json` manifest |
| `PluginManifest` | Type: full manifest schema |
| `TrustClass` | `'privileged' \| 'verified' \| 'untrusted'` |

### Registry

| Export | Description |
|---|---|
| `PluginRegistry` | In-memory registry of available plugins |
| `PluginRegistryEntry` | Type: registered plugin metadata |

### Elevation

| Export | Description |
|---|---|
| `handleElevationRequest(request)` | Process a plugin's request for elevated permissions |

### Testing (`./testing`)

| Export | Description |
|---|---|
| `MockPluginBridge` | Fake bridge for unit testing plugin components |
| `MockPluginRegistry` | Fake registry for testing host components |

## Subpath Exports

- `.` -- Everything
- `./manifest` -- Manifest types and validation only
- `./testing` -- Test mocks

## Design Spec

[docs/superpowers/specs/2026-03-16-dink-frontend-framework-design.md](../../docs/superpowers/specs/2026-03-16-dink-frontend-framework-design.md)