dorfteich/docs/architecture/plugin-architecture.md

# 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                                                                                                             |

`styles.css` is served into the host page, so the install gate (#75) enforces
its scoping instead of rewriting it: **every rule must be written under one of
the plugin's own `.dt-style-<pluginId>-<styleId>` classes** (each `<styleId>`
a declared `sectionStyle` extension point; grouping at-rules like `@media`
are checked inside, only `@font-face`/`@keyframes` are exempt). Positioning
out of the content flow (`position` other than `static`/`relative`) is
rejected — a fixed overlay could shadow the whole app. A rule that violates
the contract fails the install with `plugin_css_unsafe`.

## 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)`, `scrollToHeading(headingId)` (host scrolls to an outline entry, #77)                                |

## 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.