modularize docs

2026-06-22 13:04:33 -05:00
parent 7aaf115e2f
commit 5f75f5ca6f
9 changed files with 981 additions and 1535 deletions
@@ -0,0 +1,89 @@
+# 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.