# Plugin architecture

Extends ADR 0008 with the concrete contracts implementers need.

## Package format

A plugin is a ZIP archive:

```
my-plugin.zip
├── manifest.json      (required)
├── plugin.js          (required for kind=code; single ES module bundle)
├── styles.css         (optional; required for kind=section_style)
├── i18n/de.json       (optional UI strings)
├── i18n/en.json
└── assets/…           (optional images etc.)
```

### `manifest.json`

```json
{
  "id": "toc",
  "name": "Table of Contents",
  "version": "1.2.0",
  "apiVersion": "1",
  "kind": "code",
  "extensionPoints": [
    { "type": "pageTool", "id": "toc", "title": { "de": "Inhaltsverzeichnis", "en": "Table of contents" } }
  ],
  "permissions": ["readCurrentPage"],
  "fallback": { "type": "text", "value": "[Table of contents]" },
  "license": "MIT",
  "homepage": "https://…"
}
```

- `apiVersion`: host checks against its supported range at install time.
- `permissions`: the capabilities the plugin may call (see API below);
  shown to the Site Admin at install time. Requests outside the declared
  set are rejected at runtime.
- `fallback`: static representation used in Word/PDF exports and when the
  plugin is disabled but its blocks still exist in documents.

## Kinds and extension points

| Kind | Extension point | What it does | Sandbox |
| --- | --- | --- | --- |
| `section_style` | `sectionStyle` | declares named styles (name, i18n label, CSS class body) applicable to container blocks — e.g. colored background boxes | none needed: CSS is sanitized (no `@import`, no `url()` to external hosts) and scoped under `.dt-style-<pluginId>-<styleId>` |
| `code` | `block` | a custom editor block (diagram, embed, …); host registers a ProseMirror node `plugin_block` instance with `pluginId`, `blockType`, `data` attrs | sandboxed iframe per block |
| `code` | `pageTool` | read-only widget rendered in the page tools panel or embedded as a block (TOC, page index, cross-page block embed) | sandboxed iframe |

## Sandbox runtime

- Each code-plugin surface runs in `<iframe sandbox="allow-scripts">`
  **without** `allow-same-origin` → opaque origin: no cookies, storage, or
  parent DOM. The iframe document is generated by the host and loads only
  the plugin bundle + its assets from the plugin's static path.
- CSP on plugin frames: `default-src 'none'; script-src <plugin path>;
  img-src <plugin path> blob: data:; style-src <plugin path> 'unsafe-inline'`.
  No network access (`connect-src 'none'`) in v1.
- Host ↔ plugin communication: `postMessage` RPC with structured-clone
  payloads. `packages/plugin-sdk` provides both sides:
  - plugin side: `createPlugin({ onRender, onEdit, … })`, typed `host.*`
    calls;
  - host side: frame lifecycle, request routing, permission filtering,
    timeouts (a hung plugin never blocks the app).

## Plugin API (v1 capabilities)

All calls are mediated by the host and executed against the REST API with
the **viewing user's** session — a plugin can never read more than the
person looking at it could.

| Capability | Methods |
| --- | --- |
| `readCurrentPage` | `getOutline()`, `getContent()` (Markdown), `getMeta()` |
| `readPond` | `listPages()`, `getPageOutline(pageId)`, `getPageContent(pageId)` |
| `readBlock` | `getBlock(pageId, blockId)` — cross-page block embedding |
| `blockData` | `getData()` / `setData(data)` for the plugin's own block instance (writes go through the editor as a normal document change — requires the viewer to have write permission) |
| `ui` | `resize(height)`, `openPage(pageId)` (host navigates), `toast(msgKey)` |

## Lifecycle & administration

1. **Install** (Site Admin): upload ZIP in the admin UI **or** drop it into
   the `plugins/` volume directory (a watcher picks it up). The API
   validates: ZIP structure, manifest schema, `apiVersion`, CSS sanitation,
   bundle size limit. Invalid packages are rejected with a precise error.
2. **Instance mode** (Site Admin): `disabled` | `optional` | `required`
   (vision: Site Admin activates plugins optionally or mandatorily).
3. **Pond activation** (Pond Admin): toggle `optional` plugins per pond.
4. **Update**: uploading the same id with a higher version replaces the
   package after the same validation; open clients use the new version on
   next load.
5. **Uninstall**: blocked while `required`; otherwise the package is
   removed, existing `plugin_block` nodes render the manifest `fallback`
   (documents are never mutated by plugin removal).

## Reference plugins (shipped with the product, also serving as examples)

- `section-styles-basic` (`section_style`): a set of colored callout/box
  styles — proves the declarative path.
- `toc` (`pageTool`): table of contents from the page outline.
- `page-index` (`pageTool`): filtered page list by label.
- `mermaid` (`block`): diagram block rendering Mermaid source — proves the
  code-block path end to end (editing UI inside the sandbox).

These live in `packages/plugins/` in the monorepo, are built by CI, and
double as the plugin-SDK integration tests.