# Bundle Format

Plugin bundles are zip files named after the plugin ID. `config.json` must be at the zip root.

## Plugin 2.0 Layout

```text
<pluginId>.zip
  config.json
  <pluginId>.html
  <pluginId>.css
  <pluginId>.js              optional when src/ui.ts exists
  <pluginId>.wasm            optional agent-side WASM module
  server.js                  optional server runtime
  src/
    ui.ts                    compiled to assets/<pluginId>.js
    server.ts                compiled to server.js
    shared.ts                optional local module
```

After extraction the server stores assets under `Overlord-Server/plugins/<pluginId>/assets/`, generated metadata in `manifest.json`, optional source in `src/`, and persistent plugin files in `data/`.

## Runtime Selection

```json
{
  "apiVersion": 2,
  "runtime": "wasm",
  "wasm": "sample-wasm.wasm"
}
```

Use:

| Runtime | Use case |
|---------|----------|
| `server` | Server-only extension, build plugin, dashboard plugin, RPC-backed plugin. |
| `wasm` | Sandboxed agent-side Plugin 2.0 module. |
| `native` or omitted v1 fields | Legacy shared-library agent plugin. |

Server-only plugins are not sent to clients and do not use auto-load.

## Manifest Fields

`config.json` is merged into the generated `manifest.json`.

```json
{
  "id": "sample",
  "name": "Sample Plugin",
  "apiVersion": 2,
  "runtime": "server",
  "version": "1.0.0",
  "description": "An example plugin",
  "entry": "sample.html",
  "assets": {
    "html": "sample.html",
    "css": "sample.css",
    "js": "sample.js"
  },
  "navbar": {
    "label": "Sample",
    "icon": "fa-cube"
  }
}
```

`navbar.icon` accepts a Font Awesome 6 solid icon class such as `fa-cube`, `fa-key`, or `fa-network-wired`. If the plugin is enabled, navbar plugins appear in the Plugin Apps group and open at `/plugins/<id>`.

## TypeScript UI And Server Logic

Plugin bundles can ship source-oriented browser and server logic. The server compiles these during extraction:

```json
{
  "apiVersion": 2,
  "uiEntry": "src/browser/main.ts",
  "serverEntry": "src/backend/index.ts"
}
```

Defaults:

| Source file | Output |
|-------------|--------|
| `src/ui.ts` | `assets/<pluginId>.js` |
| `src/server.ts` | `server.js` |

Only files under `src/` are copied for compilation. Extraction does not run `npm install`, download packages, or execute build scripts. Use relative imports and APIs already available in the browser or server plugin runtime.