docs: add LibreSign integration architecture guide

- Document Phase 1: New Tab strategy (current implementation)
- Explain 3-layer Nextcloud URL resolution
- Outline Phase 2: Modal integration with postMessage
- Outline Phase 3: SDK architecture for deep integration
- Add configuration requirements for EuroOffice app
- Include debugging section with common issues
- Document testing strategy across phases
- Provide code examples for each integration layer

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

Author: vitormattos

docs/MAINTAINERS.md

@@ -65,3 +65,170 @@ Before upgrading `plugins.js`, test compatibility with target EuroOffice/ONLYOFF
 
 - `.github/workflows/ci.yml`: validation and package artifact for push/PR.
 - `.github/workflows/release.yml`: build and publish assets on version tags.
+
+## LibreSign Integration Architecture
+
+### Overview
+
+The LibreSign EuroOffice plugin provides a sidebar panel inside the EuroOffice editor that allows users to sign and request signatures for documents. Integration happens through:
+
+1. **Plugin iframe** (index.html) running in ONLYOFFICE/EuroOffice plugin sandbox
+2. **Nextcloud origin** hosting both the plugin and LibreSign app
+3. **PostMessage API** for future cross-iframe communication
+
+### Current Implementation: New Tab (Phase 1)
+
+**Strategy**: Open LibreSign in a new browser tab using `window.open()`.
+
+**Why this works**:
+- ✅ No CORS issues (browser same-site policy allows cross-tab navigation)
+- ✅ Simple, reliable, no DOM manipulation needed
+- ✅ No Content Security Policy (CSP) conflicts
+- ✅ Easy fallback if more complex modes fail
+
+**How it works**:
+
+```
+User clicks "Sign Document" button
+  ↓
+Plugin calls getNextcloudUrl() with 3-layer fallback:
+  1. window.__LIBRESIGN_CONFIG__.nextcloudUrl (pre-configured by Nextcloud)
+  2. ?nc_url= query parameter (manual override)
+  3. window.location.origin (auto-detect same-origin)
+  ↓
+Plugin opens: https://nextcloud.example.com/apps/libresign/#/f/filelist/sign
+  ↓
+User signs document in new tab
+  ↓
+(Future) New tab can communicate back via window.opener.postMessage()
+```
+
+**Configuration in Nextcloud app**:
+
+The EuroOffice app (`apps/eurooffice` in parent Nextcloud repo) is responsible for:
+
+1. Loading the plugin iframe (already done)
+2. Pre-configuring plugin URL (TODO - add to EuroOffice app):
+
+```js
+// apps/eurooffice/js/plugin-config.js (suggested location)
+window.__LIBRESIGN_CONFIG__ = {
+  nextcloudUrl: OC.getRootUrl(), // or similar
+  mode: 'new-tab' // future: 'modal', 'sidebar'
+};
+```
+
+Then inject before loading plugin:
+
+```html
+<!-- In EuroOffice app view -->
+<script src="plugin-config.js"></script>
+<iframe src="/sdkjs-plugins/libresign/index.html"></iframe>
+```
+
+### Future Implementation: Modal (Phase 2)
+
+**Goal**: Keep user in same window during signing (reduce distraction).
+
+**Architecture**:
+
+```
+Plugin sends postMessage:
+  window.parent.postMessage({
+    type: 'libresign:open',
+    mode: 'modal',
+    documentContext: { fileName, fileId, ... }
+  }, origin)
+  ↓
+Nextcloud app (eurooffice) receives message
+  ↓
+Nextcloud injects LibreSign modal DOM
+  (respects CSP by being server-rendered or sandboxed iframe)
+  ↓
+User signs in modal
+  ↓
+Modal returns result via postMessage
+  ↓
+Plugin updates document with annotation
+```
+
+**Required changes**:
+- Extend EuroOffice app with message listener
+- Create modal bridge component
+- Add communication layer between plugin and modal
+
+### Future Implementation: SDK (Phase 3)
+
+**Goal**: Professional, npm-consumable SDK for deep LibreSign integration.
+
+**Concept**:
+
+```ts
+// npm package: @libresign/plugin-sdk
+
+import { LibreSignPlugin } from '@libresign/plugin-sdk';
+
+const libresign = new LibreSignPlugin({
+  nextcloudUrl: 'https://...',
+  mode: 'modal', // configurable
+  viewer: euroOfficeViewer // pass instance for annotations
+});
+
+libresign.signDocument({
+  file: documentHandle,
+  onComplete: (sig) => {
+    euroOfficeViewer.addSignature(sig);
+  }
+});
+```
+
+**Benefits**:
+- Reusable across browser extensions, other apps
+- Type-safe (TypeScript)
+- Versioning independent of plugin
+- Can be distributed via npm
+
+### Debugging
+
+**Check if config is loaded**:
+
+```js
+// In browser console while plugin sidebar is open:
+console.log(window.__LIBRESIGN_CONFIG__);
+console.log(window.location);
+```
+
+**Check URL resolution**:
+
+```js
+// Plugin calls this internally, but you can inspect:
+getNextcloudUrl() // Should return https://your-nextcloud-domain
+getDocumentContext() // Should return { fileName, fileId, fileUrl }
+```
+
+**Common issues**:
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| Opens in same tab, replaces editor | w.open() not supported | Check browser CSP, HTTPS context |
+| Wrong Nextcloud URL | Layer 2 or 3 fallback triggered | Inject `window.__LIBRESIGN_CONFIG__` in EuroOffice app |
+| Modal doesn't appear (Phase 2) | EuroOffice app not listening for postMessage | Add event listener in eurooffice app |
+| CORS error when signing | New tab navigated to wrong domain | Verify `?nc_url=` parameter or config object |
+
+### Testing Strategy
+
+**Unit testing** (Phase 1):
+- Mock window.open()
+- Test URL resolution with different configs
+- Verify message listeners registered
+
+**Integration testing** (Phase 2+):
+- Spin up Nextcloud + EuroOffice + LibreSign stack
+- Test real postMessage flow
+- Verify signature annotation appears in document
+
+**E2E testing** (Phase 3+):
+- Use Playwright to interact with full stack
+- Sign document end-to-end
+- Verify LibreSign sidebar updates correctly
+