From f1f40a18adac298f5ad0b0a47207c87e316aa84d Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 18 Mar 2026 16:08:33 +0000
Subject: [PATCH 1/5] Add RxDB Viewer plugin for remote database inspection via
 WebRTC

Adds a new viewer plugin that allows developers to connect to any running
RxDB database remotely via WebRTC and inspect its data in a browser-based UI.

Server-side plugin (src/plugins/viewer/):
- startRxDBViewer(database, options) sets up WebRTC listener on signaling server
- getDatabaseConnectionParams(database) returns JSON connection params
- Uses same signaling server protocol as the replication-webrtc plugin
- Handles viewer requests: getDbInfo, query, count, observeQuery, exportCollection,
  writeDocument, deleteDocument, getCollectionInfo, unobserveQuery

Single-file HTML viewer (viewer.html):
- Self-contained React app with all CSS inline
- Connects via WebRTC using simple-peer (loaded from CDN)
- Dark theme matching RxDB website style (colors, gradients, typography)
- Features: collection sidebar with doc counts, document table with sortable columns,
  Mango query bar, document detail panel with JSON syntax highlighting,
  live query observer, document CRUD (add/edit/delete), collection JSON export,
  schema viewer, connection status indicator

https://claude.ai/code/session_01E4LPySRrjXCCRdV9pVKJom
---
 package.json                           |    6 +
 src/plugins/dev-mode/error-messages.ts |    8 +
 src/plugins/viewer/index.ts            |   19 +
 src/plugins/viewer/viewer-server.ts    |  348 +++++
 src/plugins/viewer/viewer-types.ts     |   71 ++
 src/plugins/viewer/viewer.html         | 1610 ++++++++++++++++++++++++
 6 files changed, 2062 insertions(+)
 create mode 100644 src/plugins/viewer/index.ts
 create mode 100644 src/plugins/viewer/viewer-server.ts
 create mode 100644 src/plugins/viewer/viewer-types.ts
 create mode 100644 src/plugins/viewer/viewer.html

diff --git a/package.json b/package.json
index 370cf71a48d..d4188856836 100644
--- a/package.json
+++ b/package.json
@@ -294,6 +294,12 @@
       "import": "./dist/esm/plugins/webmcp/index.js",
       "default": "./dist/esm/plugins/webmcp/index.js"
     },
+    "./plugins/viewer": {
+      "types": "./dist/types/plugins/viewer/index.d.ts",
+      "require": "./dist/cjs/plugins/viewer/index.js",
+      "import": "./dist/esm/plugins/viewer/index.js",
+      "default": "./dist/esm/plugins/viewer/index.js"
+    },
     "./plugins/attachments-compression": {
       "types": "./dist/types/plugins/attachments-compression/index.d.ts",
       "require": "./dist/cjs/plugins/attachments-compression/index.js",
diff --git a/src/plugins/dev-mode/error-messages.ts b/src/plugins/dev-mode/error-messages.ts
index 3b625a5fcb6..26a7b7d8885 100644
--- a/src/plugins/dev-mode/error-messages.ts
+++ b/src/plugins/dev-mode/error-messages.ts
@@ -1355,6 +1355,14 @@ export const ERROR_MESSAGES = {
      * null checks etc. so you do not have to increase the
      * build size with error message strings.
      */
+    // plugins/viewer
+    VW1: {
+        message: 'getDatabaseConnectionParams() called but startRxDBViewer() was not called on this database before.',
+        cause: 'The viewer server was not started on the database before calling getDatabaseConnectionParams().',
+        fix: 'Call startRxDBViewer(database) before calling getDatabaseConnectionParams(database).',
+        docs: ''
+    },
+
     SNH: {
         message: 'This should never happen',
         cause: 'Should never be thrown. This error code is used for internal things like null-checks etc.',
diff --git a/src/plugins/viewer/index.ts b/src/plugins/viewer/index.ts
new file mode 100644
index 00000000000..8385f90aa3e
--- /dev/null
+++ b/src/plugins/viewer/index.ts
@@ -0,0 +1,19 @@
+export {
+    startRxDBViewer,
+    getDatabaseConnectionParams,
+    VIEWER_DEFAULT_SIGNALING_SERVER
+} from './viewer-server.ts';
+
+export type {
+    ViewerConnectionParams,
+    ViewerServerOptions,
+    ViewerState,
+    ViewerMethod,
+    ViewerRequest,
+    ViewerResponse,
+    ViewerPushMessage,
+    ViewerDbInfo,
+    ViewerCollectionInfo,
+    ViewerSignalingMessage,
+    ViewerPeerState
+} from './viewer-types.ts';
diff --git a/src/plugins/viewer/viewer-server.ts b/src/plugins/viewer/viewer-server.ts
new file mode 100644
index 00000000000..3f75629e919
--- /dev/null
+++ b/src/plugins/viewer/viewer-server.ts
@@ -0,0 +1,348 @@
+import type { Subscription } from 'rxjs';
+import type { RxCollection, RxDatabase } from '../../types/index.d.ts';
+import {
+    ensureNotFalsy,
+    randomToken
+} from '../../plugins/utils/index.ts';
+import { newRxError } from '../../rx-error.ts';
+import type {
+    ViewerConnectionParams,
+    ViewerRequest,
+    ViewerResponse,
+    ViewerServerOptions,
+    ViewerSignalingMessage,
+    ViewerState
+} from './viewer-types.ts';
+
+import type {
+    SimplePeer as PeerConstructor,
+    Instance as SimplePeerInstance,
+} from 'simple-peer';
+import {
+    default as _Peer
+    // @ts-ignore
+} from 'simple-peer/simplepeer.min.js';
+
+const Peer = _Peer as PeerConstructor;
+
+type ViewerPeer = SimplePeerInstance & { id: string; };
+
+export const VIEWER_DEFAULT_SIGNALING_SERVER = 'wss://signaling.rxdb.info/';
+const VIEWER_PING_INTERVAL = 1000 * 60 * 2;
+
+const VIEWER_STATE_BY_DATABASE = new WeakMap<RxDatabase, ViewerState>();
+
+function sendSocketMessage(ws: WebSocket, msg: ViewerSignalingMessage) {
+    ws.send(JSON.stringify(msg));
+}
+
+function sendToPeer(peer: ViewerPeer, msg: ViewerResponse | { type: string; observeId: string; data: any }) {
+    try {
+        peer.send(JSON.stringify(msg));
+    } catch (_e) {
+        // peer might be disconnected
+    }
+}
+
+async function handleViewerRequest(
+    database: RxDatabase,
+    peer: ViewerPeer,
+    request: ViewerRequest,
+    peerSubscriptions: Map<string, Map<string, Subscription>>
+): Promise<ViewerResponse> {
+    try {
+        switch (request.method) {
+            case 'getDbInfo': {
+                const collections = [];
+                for (const [name, col] of Object.entries(database.collections)) {
+                    const rxCol = col as RxCollection;
+                    const docCount = await rxCol.count().exec();
+                    collections.push({
+                        name,
+                        schema: rxCol.schema.jsonSchema,
+                        docCount
+                    });
+                }
+                return { id: request.id, result: { databaseName: database.name, collections } };
+            }
+
+            case 'getCollectionInfo': {
+                const colName = request.params.collection;
+                const col = (database.collections as any)[colName] as RxCollection;
+                if (!col) {
+                    return { id: request.id, error: 'Collection not found: ' + colName };
+                }
+                const schema = col.schema.jsonSchema;
+                const docCount = await col.count().exec();
+                const primaryKey = typeof schema.primaryKey === 'string'
+                    ? schema.primaryKey
+                    : (schema.primaryKey as any)?.key;
+                return {
+                    id: request.id,
+                    result: { name: colName, schema, docCount, primaryKey }
+                };
+            }
+
+            case 'query': {
+                const { collection, query } = request.params;
+                const col = (database.collections as any)[collection] as RxCollection;
+                if (!col) {
+                    return { id: request.id, error: 'Collection not found: ' + collection };
+                }
+                const docs = await col.find(query || {}).exec();
+                return { id: request.id, result: docs.map((d: any) => d.toJSON(true)) };
+            }
+
+            case 'count': {
+                const { collection, selector } = request.params;
+                const col = (database.collections as any)[collection] as RxCollection;
+                if (!col) {
+                    return { id: request.id, error: 'Collection not found: ' + collection };
+                }
+                const count = await col.count(selector ? { selector } : undefined).exec();
+                return { id: request.id, result: count };
+            }
+
+            case 'exportCollection': {
+                const { collection } = request.params;
+                const col = (database.collections as any)[collection] as RxCollection;
+                if (!col) {
+                    return { id: request.id, error: 'Collection not found: ' + collection };
+                }
+                const docs = await col.find().exec();
+                return { id: request.id, result: docs.map((d: any) => d.toJSON(true)) };
+            }
+
+            case 'observeQuery': {
+                const { observeId, collection, query } = request.params;
+                const col = (database.collections as any)[collection] as RxCollection;
+                if (!col) {
+                    return { id: request.id, error: 'Collection not found: ' + collection };
+                }
+
+                if (!peerSubscriptions.has(peer.id)) {
+                    peerSubscriptions.set(peer.id, new Map());
+                }
+                const peerSubs = ensureNotFalsy(peerSubscriptions.get(peer.id));
+
+                // Clean up existing subscription with same id
+                const existingSub = peerSubs.get(observeId);
+                if (existingSub) {
+                    existingSub.unsubscribe();
+                }
+
+                const sub = col.find(query || {}).$.subscribe((docs: any[]) => {
+                    sendToPeer(peer, {
+                        type: 'observeResult',
+                        observeId,
+                        data: docs.map((d: any) => d.toJSON(true))
+                    });
+                });
+                peerSubs.set(observeId, sub);
+                return { id: request.id, result: { observeId, started: true } };
+            }
+
+            case 'unobserveQuery': {
+                const { observeId } = request.params;
+                const peerSubs = peerSubscriptions.get(peer.id);
+                if (peerSubs) {
+                    const sub = peerSubs.get(observeId);
+                    if (sub) {
+                        sub.unsubscribe();
+                        peerSubs.delete(observeId);
+                    }
+                }
+                return { id: request.id, result: { observeId, stopped: true } };
+            }
+
+            case 'writeDocument': {
+                const { collection, document } = request.params;
+                const col = (database.collections as any)[collection] as RxCollection;
+                if (!col) {
+                    return { id: request.id, error: 'Collection not found: ' + collection };
+                }
+                const result = await col.upsert(document);
+                return { id: request.id, result: result.toJSON(true) };
+            }
+
+            case 'deleteDocument': {
+                const { collection, primaryKey } = request.params;
+                const col = (database.collections as any)[collection] as RxCollection;
+                if (!col) {
+                    return { id: request.id, error: 'Collection not found: ' + collection };
+                }
+                const doc = await col.findOne(primaryKey).exec();
+                if (doc) {
+                    await doc.remove();
+                    return { id: request.id, result: { deleted: true } };
+                }
+                return { id: request.id, error: 'Document not found' };
+            }
+
+            default:
+                return { id: request.id, error: 'Unknown method: ' + (request as any).method };
+        }
+    } catch (err: any) {
+        return { id: request.id, error: err.message || String(err) };
+    }
+}
+
+export async function startRxDBViewer(
+    database: RxDatabase,
+    options: ViewerServerOptions = {}
+): Promise<ViewerState> {
+    const topic = options.topic || 'rxdb-viewer-' + randomToken(12);
+    const signalingServerUrl = options.signalingServerUrl || VIEWER_DEFAULT_SIGNALING_SERVER;
+    const WebSocketConstructor = options.webSocketConstructor || WebSocket;
+
+    const peerSubscriptions = new Map<string, Map<string, Subscription>>();
+    const peers = new Map<string, ViewerPeer>();
+    let closed = false;
+    let ownPeerId = '';
+    let socket: WebSocket | undefined;
+
+    function createSocket() {
+        if (closed) {
+            return;
+        }
+        socket = new WebSocketConstructor(signalingServerUrl);
+        socket.onclose = () => createSocket();
+        socket.onopen = () => {
+            ensureNotFalsy(socket).onmessage = (msgEvent: any) => {
+                const msg: ViewerSignalingMessage = JSON.parse(msgEvent.data as any);
+                switch (msg.type) {
+                    case 'init':
+                        ownPeerId = msg.yourPeerId;
+                        sendSocketMessage(ensureNotFalsy(socket), {
+                            type: 'join',
+                            room: topic
+                        });
+                        break;
+                    case 'joined':
+                        msg.otherPeerIds.forEach(remotePeerId => {
+                            if (remotePeerId === ownPeerId || peers.has(remotePeerId)) {
+                                return;
+                            }
+                            createPeerConnection(remotePeerId);
+                        });
+                        break;
+                    case 'signal': {
+                        const peer = peers.get(msg.senderPeerId);
+                        if (peer) {
+                            peer.signal(msg.data);
+                        }
+                        break;
+                    }
+                }
+            };
+        };
+    }
+
+    function createPeerConnection(remotePeerId: string) {
+        let disconnected = false;
+        const newPeer: ViewerPeer = new (Peer as any)({
+            initiator: remotePeerId > ownPeerId,
+            trickle: true
+        });
+        newPeer.id = randomToken(10);
+        peers.set(remotePeerId, newPeer);
+
+        newPeer.on('signal', (signal: any) => {
+            sendSocketMessage(ensureNotFalsy(socket), {
+                type: 'signal',
+                senderPeerId: ownPeerId,
+                receiverPeerId: remotePeerId,
+                room: topic,
+                data: signal
+            });
+        });
+
+        newPeer.on('data', async (data: any) => {
+            const request: ViewerRequest = JSON.parse(data.toString());
+            const response = await handleViewerRequest(database, newPeer, request, peerSubscriptions);
+            sendToPeer(newPeer, response);
+        });
+
+        newPeer.on('error', () => {
+            if (!disconnected) {
+                disconnected = true;
+                cleanupPeer(remotePeerId, newPeer);
+            }
+        });
+
+        newPeer.on('connect', () => {
+            // viewer peer connected
+        });
+
+        newPeer.on('close', () => {
+            if (!disconnected) {
+                disconnected = true;
+                cleanupPeer(remotePeerId, newPeer);
+            }
+            createPeerConnection(remotePeerId);
+        });
+    }
+
+    function cleanupPeer(remotePeerId: string, peer: ViewerPeer) {
+        const peerSubs = peerSubscriptions.get(peer.id);
+        if (peerSubs) {
+            peerSubs.forEach(sub => sub.unsubscribe());
+            peerSubscriptions.delete(peer.id);
+        }
+        peers.delete(remotePeerId);
+    }
+
+    createSocket();
+
+    // Send ping to keep the signaling connection alive
+    const pingInterval = setInterval(() => {
+        if (closed) {
+            clearInterval(pingInterval);
+            return;
+        }
+        if (socket && socket.readyState === WebSocket.OPEN) {
+            sendSocketMessage(socket, { type: 'ping' });
+        }
+    }, VIEWER_PING_INTERVAL);
+
+    const connectionParams: ViewerConnectionParams = {
+        topic,
+        signalingServerUrl,
+        databaseName: database.name
+    };
+
+    const state: ViewerState = {
+        connectionParams,
+        async close() {
+            closed = true;
+            clearInterval(pingInterval);
+            peerSubscriptions.forEach(peerSubs => {
+                peerSubs.forEach(sub => sub.unsubscribe());
+            });
+            peerSubscriptions.clear();
+            peers.forEach(peer => {
+                try { peer.destroy(); } catch (_e) { /* */ }
+            });
+            peers.clear();
+            if (socket) {
+                try { socket.close(); } catch (_e) { /* */ }
+            }
+            VIEWER_STATE_BY_DATABASE.delete(database);
+        }
+    };
+
+    VIEWER_STATE_BY_DATABASE.set(database, state);
+    return state;
+}
+
+export function getDatabaseConnectionParams(
+    database: RxDatabase
+): ViewerConnectionParams {
+    const state = VIEWER_STATE_BY_DATABASE.get(database);
+    if (!state) {
+        throw newRxError('VW1', {
+            database: database.name
+        });
+    }
+    return state.connectionParams;
+}
diff --git a/src/plugins/viewer/viewer-types.ts b/src/plugins/viewer/viewer-types.ts
new file mode 100644
index 00000000000..1b5bdcf2742
--- /dev/null
+++ b/src/plugins/viewer/viewer-types.ts
@@ -0,0 +1,71 @@
+import type { Subscription } from 'rxjs';
+
+export type ViewerConnectionParams = {
+    topic: string;
+    signalingServerUrl: string;
+    databaseName: string;
+};
+
+export type ViewerServerOptions = {
+    signalingServerUrl?: string;
+    topic?: string;
+    webSocketConstructor?: { new(url: string): WebSocket; };
+};
+
+export type ViewerState = {
+    connectionParams: ViewerConnectionParams;
+    close: () => Promise<void>;
+};
+
+export type ViewerMethod =
+    | 'getDbInfo'
+    | 'getCollectionInfo'
+    | 'query'
+    | 'count'
+    | 'exportCollection'
+    | 'observeQuery'
+    | 'unobserveQuery'
+    | 'writeDocument'
+    | 'deleteDocument';
+
+export type ViewerRequest = {
+    id: string;
+    method: ViewerMethod;
+    params?: any;
+};
+
+export type ViewerResponse = {
+    id: string;
+    result?: any;
+    error?: string;
+};
+
+export type ViewerPushMessage = {
+    type: 'observeResult';
+    observeId: string;
+    data: any;
+};
+
+export type ViewerDbInfo = {
+    databaseName: string;
+    collections: ViewerCollectionInfo[];
+};
+
+export type ViewerCollectionInfo = {
+    name: string;
+    schema: any;
+    docCount: number;
+    primaryKey?: string;
+};
+
+export type ViewerSignalingMessage =
+    | { type: 'init'; yourPeerId: string; }
+    | { type: 'join'; room: string; }
+    | { type: 'joined'; otherPeerIds: string[]; }
+    | { type: 'signal'; room: string; senderPeerId: string; receiverPeerId: string; data: any; }
+    | { type: 'ping'; };
+
+export type ViewerPeerState = {
+    peerId: string;
+    observeSubscriptions: Map<string, Subscription>;
+};
diff --git a/src/plugins/viewer/viewer.html b/src/plugins/viewer/viewer.html
new file mode 100644
index 00000000000..b36502c350f
--- /dev/null
+++ b/src/plugins/viewer/viewer.html
@@ -0,0 +1,1610 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>RxDB Viewer</title>
+    <script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
+    <script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
+    <script src="https://unpkg.com/simple-peer@9/simplepeer.min.js"></script>
+    <style>
+        :root {
+            --bg-primary: #20293C;
+            --bg-secondary: #0D0F18;
+            --bg-tertiary: #282330;
+            --bg-input: #1a2235;
+            --color-primary: #ED168F;
+            --color-primary-hover: #ff2da6;
+            --color-accent: #29d5b0;
+            --color-text: #ffffff;
+            --color-text-secondary: #a0aec0;
+            --color-text-dim: #6272A4;
+            --color-border: #2d3748;
+            --color-error: #fc8181;
+            --color-success: #68d391;
+            --color-warning: #f6e05e;
+            --color-purple: #BD93F9;
+            --color-green: #50FA7B;
+            --color-yellow: #F1FA8C;
+            --color-cyan: #8BE9FD;
+            --color-orange: #FFB86C;
+            --radius: 6px;
+            --radius-sm: 4px;
+            --transition: all 0.15s ease-in-out;
+        }
+
+        * { margin: 0; padding: 0; box-sizing: border-box; }
+
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            background: var(--bg-primary);
+            color: var(--color-text);
+            height: 100vh;
+            overflow: hidden;
+        }
+
+        #root { height: 100vh; display: flex; flex-direction: column; }
+
+        /* Header */
+        .header {
+            background: var(--bg-secondary);
+            border-bottom: 1px solid var(--color-border);
+            padding: 0 20px;
+            height: 52px;
+            display: flex;
+            align-items: center;
+            justify-content: space-between;
+            flex-shrink: 0;
+        }
+        .header-left { display: flex; align-items: center; gap: 12px; }
+        .header-logo {
+            font-size: 18px;
+            font-weight: 800;
+            background: linear-gradient(90deg, var(--color-primary), #b2218b);
+            -webkit-background-clip: text;
+            -webkit-text-fill-color: transparent;
+            background-clip: text;
+        }
+        .header-db-name {
+            color: var(--color-text-secondary);
+            font-size: 14px;
+            padding: 4px 10px;
+            background: var(--bg-primary);
+            border-radius: var(--radius-sm);
+        }
+        .header-right { display: flex; align-items: center; gap: 12px; }
+        .connection-status {
+            display: flex;
+            align-items: center;
+            gap: 6px;
+            font-size: 13px;
+            color: var(--color-text-secondary);
+        }
+        .status-dot {
+            width: 8px;
+            height: 8px;
+            border-radius: 50%;
+        }
+        .status-dot.connected { background: var(--color-success); }
+        .status-dot.connecting { background: var(--color-warning); animation: pulse 1s infinite; }
+        .status-dot.disconnected { background: var(--color-error); }
+
+        @keyframes pulse {
+            0%, 100% { opacity: 1; }
+            50% { opacity: 0.4; }
+        }
+
+        /* Main layout */
+        .main-layout {
+            display: flex;
+            flex: 1;
+            overflow: hidden;
+        }
+
+        /* Sidebar */
+        .sidebar {
+            width: 240px;
+            min-width: 240px;
+            background: var(--bg-secondary);
+            border-right: 1px solid var(--color-border);
+            display: flex;
+            flex-direction: column;
+            overflow: hidden;
+        }
+        .sidebar-header {
+            padding: 14px 16px 10px;
+            font-size: 11px;
+            font-weight: 700;
+            text-transform: uppercase;
+            letter-spacing: 1px;
+            color: var(--color-text-dim);
+        }
+        .collection-list {
+            flex: 1;
+            overflow-y: auto;
+            padding: 0 8px;
+        }
+        .collection-item {
+            display: flex;
+            align-items: center;
+            justify-content: space-between;
+            padding: 8px 12px;
+            border-radius: var(--radius-sm);
+            cursor: pointer;
+            transition: var(--transition);
+            font-size: 14px;
+            margin-bottom: 2px;
+        }
+        .collection-item:hover { background: rgba(255,255,255,0.05); }
+        .collection-item.active {
+            background: linear-gradient(90deg, rgba(237,22,143,0.15), rgba(178,33,139,0.1));
+            color: var(--color-primary);
+        }
+        .collection-item .doc-count {
+            font-size: 12px;
+            color: var(--color-text-dim);
+            background: rgba(255,255,255,0.05);
+            padding: 2px 8px;
+            border-radius: 10px;
+        }
+        .collection-item.active .doc-count {
+            background: rgba(237,22,143,0.2);
+            color: var(--color-primary);
+        }
+
+        /* Schema panel in sidebar */
+        .sidebar-schema {
+            border-top: 1px solid var(--color-border);
+            max-height: 300px;
+            overflow-y: auto;
+        }
+        .sidebar-schema-header {
+            padding: 10px 16px;
+            font-size: 11px;
+            font-weight: 700;
+            text-transform: uppercase;
+            letter-spacing: 1px;
+            color: var(--color-text-dim);
+            cursor: pointer;
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+        }
+        .sidebar-schema-content {
+            padding: 0 12px 12px;
+        }
+        .schema-json {
+            font-family: 'Courier New', monospace;
+            font-size: 12px;
+            line-height: 1.5;
+            color: var(--color-text-secondary);
+            background: var(--bg-primary);
+            padding: 10px;
+            border-radius: var(--radius-sm);
+            overflow-x: auto;
+            white-space: pre-wrap;
+            word-break: break-all;
+            max-height: 220px;
+            overflow-y: auto;
+        }
+
+        /* Content area */
+        .content {
+            flex: 1;
+            display: flex;
+            flex-direction: column;
+            overflow: hidden;
+        }
+
+        /* Toolbar */
+        .toolbar {
+            display: flex;
+            align-items: center;
+            gap: 10px;
+            padding: 10px 16px;
+            border-bottom: 1px solid var(--color-border);
+            background: var(--bg-secondary);
+            flex-shrink: 0;
+        }
+        .query-input {
+            flex: 1;
+            background: var(--bg-input);
+            border: 1px solid var(--color-border);
+            border-radius: var(--radius-sm);
+            color: var(--color-text);
+            padding: 8px 12px;
+            font-family: 'Courier New', monospace;
+            font-size: 13px;
+            outline: none;
+            transition: var(--transition);
+        }
+        .query-input:focus {
+            border-color: var(--color-primary);
+            box-shadow: 0 0 0 2px rgba(237,22,143,0.15);
+        }
+        .query-input::placeholder { color: var(--color-text-dim); }
+
+        /* Tabs */
+        .tabs {
+            display: flex;
+            gap: 0;
+            background: var(--bg-secondary);
+            border-bottom: 1px solid var(--color-border);
+            padding: 0 16px;
+            flex-shrink: 0;
+        }
+        .tab {
+            padding: 8px 16px;
+            font-size: 13px;
+            cursor: pointer;
+            color: var(--color-text-secondary);
+            border-bottom: 2px solid transparent;
+            transition: var(--transition);
+        }
+        .tab:hover { color: var(--color-text); }
+        .tab.active {
+            color: var(--color-primary);
+            border-bottom-color: var(--color-primary);
+        }
+
+        /* Buttons */
+        .btn {
+            padding: 7px 14px;
+            border-radius: var(--radius-sm);
+            border: none;
+            cursor: pointer;
+            font-size: 13px;
+            font-weight: 600;
+            transition: var(--transition);
+            display: inline-flex;
+            align-items: center;
+            gap: 6px;
+        }
+        .btn-primary {
+            background: linear-gradient(90deg, var(--color-primary), #b2218b);
+            color: white;
+        }
+        .btn-primary:hover {
+            box-shadow: 0 0 6px rgba(237,22,143,0.4);
+        }
+        .btn-secondary {
+            background: transparent;
+            border: 1px solid var(--color-border);
+            color: var(--color-text-secondary);
+        }
+        .btn-secondary:hover {
+            background: rgba(255,255,255,0.05);
+            color: var(--color-text);
+        }
+        .btn-danger {
+            background: transparent;
+            border: 1px solid rgba(252,129,129,0.3);
+            color: var(--color-error);
+        }
+        .btn-danger:hover {
+            background: rgba(252,129,129,0.1);
+        }
+        .btn-sm {
+            padding: 4px 10px;
+            font-size: 12px;
+        }
+        .btn:disabled {
+            opacity: 0.5;
+            cursor: not-allowed;
+        }
+
+        /* Document table */
+        .table-container {
+            flex: 1;
+            overflow: auto;
+        }
+        .doc-table {
+            width: 100%;
+            border-collapse: collapse;
+            font-size: 13px;
+        }
+        .doc-table th {
+            position: sticky;
+            top: 0;
+            background: var(--bg-secondary);
+            padding: 10px 14px;
+            text-align: left;
+            font-weight: 600;
+            font-size: 12px;
+            text-transform: uppercase;
+            letter-spacing: 0.5px;
+            color: var(--color-text-dim);
+            border-bottom: 1px solid var(--color-border);
+            cursor: pointer;
+            user-select: none;
+            white-space: nowrap;
+            z-index: 1;
+        }
+        .doc-table th:hover { color: var(--color-text-secondary); }
+        .doc-table th.sorted { color: var(--color-primary); }
+        .doc-table td {
+            padding: 8px 14px;
+            border-bottom: 1px solid rgba(45,55,72,0.5);
+            max-width: 300px;
+            overflow: hidden;
+            text-overflow: ellipsis;
+            white-space: nowrap;
+            color: var(--color-text-secondary);
+            font-family: 'Courier New', monospace;
+            font-size: 12px;
+        }
+        .doc-table tr { transition: var(--transition); }
+        .doc-table tr:hover { background: rgba(255,255,255,0.02); }
+        .doc-table tr.selected {
+            background: rgba(237,22,143,0.08);
+        }
+        .doc-table tr.selected td { color: var(--color-text); }
+        .cell-string { color: var(--color-yellow); }
+        .cell-number { color: var(--color-purple); }
+        .cell-boolean { color: var(--color-orange); }
+        .cell-null { color: var(--color-text-dim); font-style: italic; }
+        .cell-object { color: var(--color-cyan); }
+
+        /* Document detail panel */
+        .detail-panel {
+            width: 400px;
+            min-width: 400px;
+            border-left: 1px solid var(--color-border);
+            background: var(--bg-secondary);
+            display: flex;
+            flex-direction: column;
+            overflow: hidden;
+        }
+        .detail-header {
+            padding: 12px 16px;
+            border-bottom: 1px solid var(--color-border);
+            display: flex;
+            align-items: center;
+            justify-content: space-between;
+            font-size: 13px;
+            font-weight: 600;
+            flex-shrink: 0;
+        }
+        .detail-body {
+            flex: 1;
+            overflow-y: auto;
+            padding: 12px;
+        }
+        .json-viewer {
+            font-family: 'Courier New', monospace;
+            font-size: 12px;
+            line-height: 1.6;
+            white-space: pre-wrap;
+            word-break: break-all;
+        }
+        .json-key { color: var(--color-cyan); }
+        .json-string { color: var(--color-yellow); }
+        .json-number { color: var(--color-purple); }
+        .json-boolean { color: var(--color-orange); }
+        .json-null { color: var(--color-text-dim); }
+        .json-brace { color: var(--color-text-secondary); }
+
+        .detail-actions {
+            padding: 10px 16px;
+            border-top: 1px solid var(--color-border);
+            display: flex;
+            gap: 8px;
+            flex-shrink: 0;
+        }
+
+        /* Connect panel */
+        .connect-panel {
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            flex: 1;
+            padding: 40px;
+        }
+        .connect-card {
+            background: var(--bg-secondary);
+            border: 1px solid var(--color-border);
+            border-radius: var(--radius);
+            padding: 40px;
+            max-width: 560px;
+            width: 100%;
+        }
+        .connect-title {
+            font-size: 24px;
+            font-weight: 800;
+            margin-bottom: 8px;
+            background: linear-gradient(90deg, var(--color-primary), #b2218b);
+            -webkit-background-clip: text;
+            -webkit-text-fill-color: transparent;
+            background-clip: text;
+        }
+        .connect-subtitle {
+            color: var(--color-text-secondary);
+            font-size: 14px;
+            margin-bottom: 24px;
+            line-height: 1.5;
+        }
+        .connect-label {
+            font-size: 13px;
+            font-weight: 600;
+            margin-bottom: 8px;
+            display: block;
+            color: var(--color-text-secondary);
+        }
+        .connect-textarea {
+            width: 100%;
+            height: 120px;
+            background: var(--bg-input);
+            border: 1px solid var(--color-border);
+            border-radius: var(--radius-sm);
+            color: var(--color-text);
+            padding: 12px;
+            font-family: 'Courier New', monospace;
+            font-size: 13px;
+            resize: vertical;
+            outline: none;
+            margin-bottom: 16px;
+            transition: var(--transition);
+        }
+        .connect-textarea:focus {
+            border-color: var(--color-primary);
+            box-shadow: 0 0 0 2px rgba(237,22,143,0.15);
+        }
+        .connect-error {
+            color: var(--color-error);
+            font-size: 13px;
+            margin-bottom: 12px;
+            padding: 8px 12px;
+            background: rgba(252,129,129,0.1);
+            border-radius: var(--radius-sm);
+        }
+
+        /* Query Observer panel */
+        .observer-panel {
+            border-top: 1px solid var(--color-border);
+            background: var(--bg-secondary);
+            max-height: 280px;
+            display: flex;
+            flex-direction: column;
+            flex-shrink: 0;
+        }
+        .observer-header {
+            padding: 8px 16px;
+            display: flex;
+            align-items: center;
+            justify-content: space-between;
+            border-bottom: 1px solid var(--color-border);
+            font-size: 13px;
+            font-weight: 600;
+            cursor: pointer;
+            flex-shrink: 0;
+        }
+        .observer-body {
+            flex: 1;
+            overflow-y: auto;
+            padding: 8px;
+        }
+        .observer-item {
+            padding: 8px 12px;
+            background: var(--bg-primary);
+            border-radius: var(--radius-sm);
+            margin-bottom: 6px;
+            font-size: 12px;
+        }
+        .observer-item-header {
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            margin-bottom: 4px;
+        }
+        .observer-item-query {
+            font-family: 'Courier New', monospace;
+            color: var(--color-text-secondary);
+            font-size: 11px;
+        }
+        .observer-item-meta {
+            color: var(--color-text-dim);
+            font-size: 11px;
+            display: flex;
+            gap: 12px;
+            align-items: center;
+        }
+        .observer-badge {
+            display: inline-flex;
+            align-items: center;
+            gap: 4px;
+            padding: 2px 8px;
+            border-radius: 10px;
+            font-size: 11px;
+            font-weight: 600;
+        }
+        .observer-badge.live {
+            background: rgba(104,211,145,0.15);
+            color: var(--color-success);
+        }
+
+        /* Empty state */
+        .empty-state {
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            justify-content: center;
+            flex: 1;
+            color: var(--color-text-dim);
+            font-size: 14px;
+            gap: 8px;
+        }
+
+        /* Edit modal */
+        .modal-overlay {
+            position: fixed;
+            top: 0;
+            left: 0;
+            right: 0;
+            bottom: 0;
+            background: rgba(0,0,0,0.6);
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            z-index: 100;
+        }
+        .modal {
+            background: var(--bg-secondary);
+            border: 1px solid var(--color-border);
+            border-radius: var(--radius);
+            padding: 24px;
+            width: 600px;
+            max-height: 80vh;
+            display: flex;
+            flex-direction: column;
+        }
+        .modal-title {
+            font-size: 16px;
+            font-weight: 700;
+            margin-bottom: 16px;
+        }
+        .modal-body { flex: 1; overflow-y: auto; }
+        .modal textarea {
+            width: 100%;
+            min-height: 300px;
+            background: var(--bg-input);
+            border: 1px solid var(--color-border);
+            border-radius: var(--radius-sm);
+            color: var(--color-text);
+            padding: 12px;
+            font-family: 'Courier New', monospace;
+            font-size: 13px;
+            resize: vertical;
+            outline: none;
+        }
+        .modal textarea:focus {
+            border-color: var(--color-primary);
+        }
+        .modal-actions {
+            display: flex;
+            justify-content: flex-end;
+            gap: 8px;
+            margin-top: 16px;
+        }
+        .modal-error {
+            color: var(--color-error);
+            font-size: 13px;
+            margin-top: 8px;
+        }
+
+        /* Toast notification */
+        .toast {
+            position: fixed;
+            bottom: 20px;
+            right: 20px;
+            padding: 10px 18px;
+            border-radius: var(--radius-sm);
+            font-size: 13px;
+            z-index: 200;
+            animation: slideIn 0.2s ease-out;
+        }
+        .toast.success { background: rgba(104,211,145,0.2); color: var(--color-success); border: 1px solid rgba(104,211,145,0.3); }
+        .toast.error { background: rgba(252,129,129,0.2); color: var(--color-error); border: 1px solid rgba(252,129,129,0.3); }
+
+        @keyframes slideIn {
+            from { transform: translateY(20px); opacity: 0; }
+            to { transform: translateY(0); opacity: 1; }
+        }
+
+        /* Scrollbar styling */
+        ::-webkit-scrollbar { width: 6px; height: 6px; }
+        ::-webkit-scrollbar-track { background: transparent; }
+        ::-webkit-scrollbar-thumb { background: var(--color-border); border-radius: 3px; }
+        ::-webkit-scrollbar-thumb:hover { background: var(--color-text-dim); }
+
+        /* Status bar */
+        .status-bar {
+            height: 26px;
+            background: var(--bg-secondary);
+            border-top: 1px solid var(--color-border);
+            padding: 0 16px;
+            display: flex;
+            align-items: center;
+            justify-content: space-between;
+            font-size: 11px;
+            color: var(--color-text-dim);
+            flex-shrink: 0;
+        }
+    </style>
+</head>
+<body>
+<div id="root"></div>
+<script>
+// process.nextTick polyfill for simple-peer
+if (typeof process === 'undefined') {
+    window.process = { nextTick: function(fn) { Promise.resolve().then(fn); } };
+} else if (typeof process.nextTick !== 'function') {
+    process.nextTick = function(fn) { Promise.resolve().then(fn); };
+}
+
+var h = React.createElement;
+var useState = React.useState;
+var useEffect = React.useEffect;
+var useRef = React.useRef;
+var useCallback = React.useCallback;
+var useMemo = React.useMemo;
+
+// ========== WebRTC Connection Layer ==========
+function createViewerConnection(params, callbacks) {
+    var topic = params.topic;
+    var signalingServerUrl = params.signalingServerUrl;
+    var peer = null;
+    var ownPeerId = '';
+    var peers = {};
+    var closed = false;
+    var socket = null;
+    var pendingRequests = {};
+    var requestCounter = 0;
+    var pingInterval = null;
+
+    function sendSocketMsg(ws, msg) {
+        if (ws && ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify(msg));
+        }
+    }
+
+    function createSocket() {
+        if (closed) return;
+        socket = new WebSocket(signalingServerUrl);
+        socket.onclose = function() {
+            if (!closed) {
+                callbacks.onStatusChange('connecting');
+                setTimeout(function() { createSocket(); }, 2000);
+            }
+        };
+        socket.onerror = function() {};
+        socket.onopen = function() {
+            socket.onmessage = function(ev) {
+                var msg = JSON.parse(ev.data);
+                switch (msg.type) {
+                    case 'init':
+                        ownPeerId = msg.yourPeerId;
+                        sendSocketMsg(socket, { type: 'join', room: topic });
+                        break;
+                    case 'joined':
+                        msg.otherPeerIds.forEach(function(remotePeerId) {
+                            if (remotePeerId === ownPeerId || peers[remotePeerId]) return;
+                            createPeerConnection(remotePeerId);
+                        });
+                        break;
+                    case 'signal':
+                        var p = peers[msg.senderPeerId];
+                        if (p) p.signal(msg.data);
+                        break;
+                }
+            };
+        };
+    }
+
+    function createPeerConnection(remotePeerId) {
+        var disconnected = false;
+        var sp = new SimplePeer({
+            initiator: remotePeerId > ownPeerId,
+            trickle: true
+        });
+        peers[remotePeerId] = sp;
+
+        sp.on('signal', function(signal) {
+            sendSocketMsg(socket, {
+                type: 'signal',
+                senderPeerId: ownPeerId,
+                receiverPeerId: remotePeerId,
+                room: topic,
+                data: signal
+            });
+        });
+
+        sp.on('data', function(data) {
+            var msg = JSON.parse(data.toString());
+            if (msg.type === 'observeResult') {
+                callbacks.onObserveResult(msg.observeId, msg.data);
+            } else if (msg.id && pendingRequests[msg.id]) {
+                pendingRequests[msg.id](msg);
+                delete pendingRequests[msg.id];
+            }
+        });
+
+        sp.on('connect', function() {
+            peer = sp;
+            callbacks.onStatusChange('connected');
+        });
+
+        sp.on('error', function() {
+            if (!disconnected) {
+                disconnected = true;
+                delete peers[remotePeerId];
+                if (peer === sp) {
+                    peer = null;
+                    callbacks.onStatusChange('connecting');
+                }
+            }
+        });
+
+        sp.on('close', function() {
+            if (!disconnected) {
+                disconnected = true;
+                delete peers[remotePeerId];
+                if (peer === sp) {
+                    peer = null;
+                    callbacks.onStatusChange('connecting');
+                }
+            }
+            if (!closed) {
+                createPeerConnection(remotePeerId);
+            }
+        });
+    }
+
+    createSocket();
+    pingInterval = setInterval(function() {
+        if (closed) { clearInterval(pingInterval); return; }
+        sendSocketMsg(socket, { type: 'ping' });
+    }, 120000);
+
+    return {
+        sendRequest: function(method, params) {
+            return new Promise(function(resolve, reject) {
+                if (!peer) {
+                    reject(new Error('Not connected'));
+                    return;
+                }
+                var id = 'vr-' + (++requestCounter) + '-' + Date.now();
+                var timeout = setTimeout(function() {
+                    delete pendingRequests[id];
+                    reject(new Error('Request timeout'));
+                }, 30000);
+                pendingRequests[id] = function(response) {
+                    clearTimeout(timeout);
+                    if (response.error) {
+                        reject(new Error(response.error));
+                    } else {
+                        resolve(response.result);
+                    }
+                };
+                try {
+                    peer.send(JSON.stringify({ id: id, method: method, params: params || {} }));
+                } catch (e) {
+                    clearTimeout(timeout);
+                    delete pendingRequests[id];
+                    reject(e);
+                }
+            });
+        },
+        close: function() {
+            closed = true;
+            clearInterval(pingInterval);
+            Object.keys(peers).forEach(function(k) {
+                try { peers[k].destroy(); } catch(e) {}
+            });
+            peers = {};
+            peer = null;
+            if (socket) {
+                try { socket.close(); } catch(e) {}
+            }
+        }
+    };
+}
+
+// ========== JSON Syntax Highlighting ==========
+function syntaxHighlight(json) {
+    if (typeof json !== 'string') json = JSON.stringify(json, null, 2);
+    json = json.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    return json.replace(
+        /("(\\u[a-zA-Z0-9]{4}|\\[^u]|[^\\"])*"(\s*:)?|\b(true|false|null)\b|-?\d+(?:\.\d*)?(?:[eE][+\-]?\d+)?)/g,
+        function(match) {
+            var cls = 'json-number';
+            if (/^"/.test(match)) {
+                if (/:$/.test(match)) {
+                    cls = 'json-key';
+                    match = match.slice(0, -1);
+                    return '<span class="' + cls + '">' + match + '</span>:';
+                } else {
+                    cls = 'json-string';
+                }
+            } else if (/true|false/.test(match)) {
+                cls = 'json-boolean';
+            } else if (/null/.test(match)) {
+                cls = 'json-null';
+            }
+            return '<span class="' + cls + '">' + match + '</span>';
+        }
+    );
+}
+
+function getCellClass(val) {
+    if (val === null || val === undefined) return 'cell-null';
+    if (typeof val === 'string') return 'cell-string';
+    if (typeof val === 'number') return 'cell-number';
+    if (typeof val === 'boolean') return 'cell-boolean';
+    if (typeof val === 'object') return 'cell-object';
+    return '';
+}
+
+function formatCellValue(val) {
+    if (val === null || val === undefined) return 'null';
+    if (typeof val === 'object') return JSON.stringify(val);
+    return String(val);
+}
+
+// ========== React Components ==========
+
+function ConnectPanel(props) {
+    var paramsText = props.paramsText;
+    var setParamsText = props.setParamsText;
+    var onConnect = props.onConnect;
+    var error = props.error;
+    var connecting = props.connecting;
+
+    return h('div', { className: 'connect-panel' },
+        h('div', { className: 'connect-card' },
+            h('div', { className: 'connect-title' }, 'RxDB Viewer'),
+            h('div', { className: 'connect-subtitle' },
+                'Connect to any RxDB database remotely via WebRTC. Paste the connection parameters JSON below to get started.'
+            ),
+            h('label', { className: 'connect-label' }, 'Connection Parameters (JSON)'),
+            h('textarea', {
+                className: 'connect-textarea',
+                value: paramsText,
+                onChange: function(e) { setParamsText(e.target.value); },
+                placeholder: '{\n  "topic": "rxdb-viewer-...",\n  "signalingServerUrl": "wss://signaling.rxdb.info/",\n  "databaseName": "mydb"\n}',
+                spellCheck: false
+            }),
+            error ? h('div', { className: 'connect-error' }, error) : null,
+            h('button', {
+                className: 'btn btn-primary',
+                onClick: onConnect,
+                disabled: connecting,
+                style: { width: '100%', justifyContent: 'center', height: 42 }
+            }, connecting ? 'Connecting...' : 'Connect')
+        )
+    );
+}
+
+function DocumentTable(props) {
+    var documents = props.documents;
+    var columns = props.columns;
+    var selectedDoc = props.selectedDoc;
+    var onSelectDoc = props.onSelectDoc;
+    var sortField = props.sortField;
+    var sortDir = props.sortDir;
+    var onSort = props.onSort;
+
+    if (!documents.length) {
+        return h('div', { className: 'empty-state' },
+            h('div', { style: { fontSize: 32, marginBottom: 8 } }, '\u{1F4C4}'),
+            'No documents found'
+        );
+    }
+
+    return h('div', { className: 'table-container' },
+        h('table', { className: 'doc-table' },
+            h('thead', null,
+                h('tr', null,
+                    columns.map(function(col) {
+                        var isSorted = sortField === col;
+                        return h('th', {
+                            key: col,
+                            className: isSorted ? 'sorted' : '',
+                            onClick: function() { onSort(col); }
+                        }, col + (isSorted ? (sortDir === 'asc' ? ' \u2191' : ' \u2193') : ''));
+                    })
+                )
+            ),
+            h('tbody', null,
+                documents.map(function(doc, idx) {
+                    var primaryVal = JSON.stringify(doc[columns[0]]);
+                    var isSelected = selectedDoc && JSON.stringify(selectedDoc[columns[0]]) === primaryVal;
+                    return h('tr', {
+                        key: primaryVal || idx,
+                        className: isSelected ? 'selected' : '',
+                        onClick: function() { onSelectDoc(doc); }
+                    },
+                        columns.map(function(col) {
+                            var val = doc[col];
+                            return h('td', {
+                                key: col,
+                                className: getCellClass(val),
+                                title: formatCellValue(val)
+                            }, formatCellValue(val));
+                        })
+                    );
+                })
+            )
+        )
+    );
+}
+
+function DetailPanel(props) {
+    var doc = props.doc;
+    var onClose = props.onClose;
+    var onEdit = props.onEdit;
+    var onDelete = props.onDelete;
+
+    if (!doc) return null;
+
+    return h('div', { className: 'detail-panel' },
+        h('div', { className: 'detail-header' },
+            h('span', null, 'Document Detail'),
+            h('button', { className: 'btn btn-secondary btn-sm', onClick: onClose }, '\u2715')
+        ),
+        h('div', { className: 'detail-body' },
+            h('div', {
+                className: 'json-viewer',
+                dangerouslySetInnerHTML: { __html: syntaxHighlight(doc) }
+            })
+        ),
+        h('div', { className: 'detail-actions' },
+            h('button', { className: 'btn btn-secondary btn-sm', onClick: function() { onEdit(doc); } }, 'Edit'),
+            h('button', { className: 'btn btn-danger btn-sm', onClick: function() { onDelete(doc); } }, 'Delete'),
+            h('button', { className: 'btn btn-secondary btn-sm', onClick: function() {
+                navigator.clipboard.writeText(JSON.stringify(doc, null, 2));
+            }}, 'Copy JSON')
+        )
+    );
+}
+
+function EditModal(props) {
+    var isOpen = props.isOpen;
+    var title = props.title;
+    var initialValue = props.initialValue;
+    var onSave = props.onSave;
+    var onCancel = props.onCancel;
+    var error = props.error;
+    var textRef = useRef(null);
+    var currentText = useRef(initialValue || '');
+
+    useEffect(function() {
+        currentText.current = initialValue || '';
+        if (textRef.current) {
+            textRef.current.value = initialValue || '';
+        }
+    }, [initialValue, isOpen]);
+
+    if (!isOpen) return null;
+
+    return h('div', { className: 'modal-overlay', onClick: function(e) {
+        if (e.target === e.currentTarget) onCancel();
+    }},
+        h('div', { className: 'modal' },
+            h('div', { className: 'modal-title' }, title),
+            h('div', { className: 'modal-body' },
+                h('textarea', {
+                    ref: textRef,
+                    defaultValue: initialValue,
+                    onChange: function(e) { currentText.current = e.target.value; },
+                    spellCheck: false
+                })
+            ),
+            error ? h('div', { className: 'modal-error' }, error) : null,
+            h('div', { className: 'modal-actions' },
+                h('button', { className: 'btn btn-secondary', onClick: onCancel }, 'Cancel'),
+                h('button', { className: 'btn btn-primary', onClick: function() {
+                    onSave(currentText.current);
+                }}, 'Save')
+            )
+        )
+    );
+}
+
+function QueryObserverPanel(props) {
+    var queries = props.queries;
+    var onRemove = props.onRemove;
+    var isOpen = props.isOpen;
+    var onToggle = props.onToggle;
+    var onViewResults = props.onViewResults;
+
+    return h('div', { className: 'observer-panel', style: isOpen ? {} : { maxHeight: 36 } },
+        h('div', { className: 'observer-header', onClick: onToggle },
+            h('span', null, 'Query Observer (' + queries.length + ')'),
+            h('span', null, isOpen ? '\u25BC' : '\u25B2')
+        ),
+        isOpen ? h('div', { className: 'observer-body' },
+            queries.length === 0 ?
+                h('div', { style: { color: 'var(--color-text-dim)', fontSize: 12, padding: 12, textAlign: 'center' } },
+                    'No observed queries. Use the toolbar to observe a query.'
+                ) :
+                queries.map(function(q) {
+                    return h('div', { key: q.id, className: 'observer-item' },
+                        h('div', { className: 'observer-item-header' },
+                            h('span', null,
+                                h('span', { style: { color: 'var(--color-accent)', fontWeight: 600 } }, q.collection),
+                                h('span', { className: 'observer-badge live', style: { marginLeft: 8 } }, '\u25CF Live')
+                            ),
+                            h('div', { style: { display: 'flex', gap: 6 } },
+                                h('button', { className: 'btn btn-secondary btn-sm', onClick: function() { onViewResults(q); } },
+                                    q.resultCount + ' docs'
+                                ),
+                                h('button', { className: 'btn btn-danger btn-sm', onClick: function() { onRemove(q.id); } }, '\u2715')
+                            )
+                        ),
+                        h('div', { className: 'observer-item-query' }, JSON.stringify(q.query || {})),
+                        h('div', { className: 'observer-item-meta' },
+                            q.lastUpdated ? 'Updated ' + new Date(q.lastUpdated).toLocaleTimeString() : 'Waiting...'
+                        )
+                    );
+                })
+        ) : null
+    );
+}
+
+function SchemaView(props) {
+    var schema = props.schema;
+    if (!schema) {
+        return h('div', { className: 'empty-state' }, 'Select a collection to view its schema');
+    }
+    return h('div', { style: { padding: 16, flex: 1, overflow: 'auto' } },
+        h('div', {
+            className: 'json-viewer',
+            dangerouslySetInnerHTML: { __html: syntaxHighlight(schema) }
+        })
+    );
+}
+
+// ========== Main App ==========
+function App() {
+    var _connState = useState('disconnected');
+    var connectionState = _connState[0], setConnectionState = _connState[1];
+
+    var _paramsText = useState('');
+    var paramsText = _paramsText[0], setParamsText = _paramsText[1];
+
+    var _connError = useState(null);
+    var connError = _connError[0], setConnError = _connError[1];
+
+    var _dbInfo = useState(null);
+    var dbInfo = _dbInfo[0], setDbInfo = _dbInfo[1];
+
+    var _selectedCollection = useState(null);
+    var selectedCollection = _selectedCollection[0], setSelectedCollection = _selectedCollection[1];
+
+    var _collectionInfo = useState(null);
+    var collectionInfo = _collectionInfo[0], setCollectionInfo = _collectionInfo[1];
+
+    var _documents = useState([]);
+    var documents = _documents[0], setDocuments = _documents[1];
+
+    var _selectedDoc = useState(null);
+    var selectedDoc = _selectedDoc[0], setSelectedDoc = _selectedDoc[1];
+
+    var _queryText = useState('{}');
+    var queryText = _queryText[0], setQueryText = _queryText[1];
+
+    var _sortField = useState(null);
+    var sortField = _sortField[0], setSortField = _sortField[1];
+
+    var _sortDir = useState('asc');
+    var sortDir = _sortDir[0], setSortDir = _sortDir[1];
+
+    var _activeTab = useState('data');
+    var activeTab = _activeTab[0], setActiveTab = _activeTab[1];
+
+    var _showObserver = useState(false);
+    var showObserver = _showObserver[0], setShowObserver = _showObserver[1];
+
+    var _observedQueries = useState([]);
+    var observedQueries = _observedQueries[0], setObservedQueries = _observedQueries[1];
+
+    var _editModal = useState({ open: false, title: '', value: '', error: null, mode: null });
+    var editModal = _editModal[0], setEditModal = _editModal[1];
+
+    var _toast = useState(null);
+    var toast = _toast[0], setToast = _toast[1];
+
+    var _showSchema = useState(true);
+    var showSchema = _showSchema[0], setShowSchema = _showSchema[1];
+
+    var _loading = useState(false);
+    var loading = _loading[0], setLoading = _loading[1];
+
+    var connectionRef = useRef(null);
+
+    function showToast(msg, type) {
+        setToast({ msg: msg, type: type || 'success' });
+        setTimeout(function() { setToast(null); }, 3000);
+    }
+
+    function handleConnect() {
+        setConnError(null);
+        var params;
+        try {
+            params = JSON.parse(paramsText);
+        } catch (e) {
+            setConnError('Invalid JSON. Please paste valid connection parameters.');
+            return;
+        }
+        if (!params.topic || !params.signalingServerUrl) {
+            setConnError('Missing required fields: topic and signalingServerUrl');
+            return;
+        }
+
+        setConnectionState('connecting');
+
+        if (connectionRef.current) {
+            connectionRef.current.close();
+        }
+
+        connectionRef.current = createViewerConnection(params, {
+            onStatusChange: function(status) {
+                setConnectionState(status);
+                if (status === 'connected') {
+                    loadDbInfo();
+                }
+            },
+            onObserveResult: function(observeId, data) {
+                setObservedQueries(function(prev) {
+                    return prev.map(function(q) {
+                        if (q.id === observeId) {
+                            return Object.assign({}, q, { results: data, resultCount: data.length, lastUpdated: Date.now() });
+                        }
+                        return q;
+                    });
+                });
+            }
+        });
+    }
+
+    function loadDbInfo() {
+        if (!connectionRef.current) return;
+        connectionRef.current.sendRequest('getDbInfo').then(function(info) {
+            setDbInfo(info);
+            if (info.collections.length > 0 && !selectedCollection) {
+                selectCollection(info.collections[0].name);
+            }
+        }).catch(function(err) {
+            showToast('Failed to load database info: ' + err.message, 'error');
+        });
+    }
+
+    function selectCollection(name) {
+        setSelectedCollection(name);
+        setSelectedDoc(null);
+        setDocuments([]);
+        setSortField(null);
+        setQueryText('{}');
+        setActiveTab('data');
+        loadCollectionInfo(name);
+        runQuery(name, {});
+    }
+
+    function loadCollectionInfo(name) {
+        if (!connectionRef.current) return;
+        connectionRef.current.sendRequest('getCollectionInfo', { collection: name }).then(function(info) {
+            setCollectionInfo(info);
+        }).catch(function(err) {
+            showToast('Failed to load collection info: ' + err.message, 'error');
+        });
+    }
+
+    function runQuery(collName, query) {
+        if (!connectionRef.current) return;
+        var col = collName || selectedCollection;
+        if (!col) return;
+        setLoading(true);
+        connectionRef.current.sendRequest('query', { collection: col, query: query }).then(function(docs) {
+            setDocuments(docs);
+            setLoading(false);
+        }).catch(function(err) {
+            showToast('Query error: ' + err.message, 'error');
+            setLoading(false);
+        });
+    }
+
+    function handleRunQuery() {
+        try {
+            var query = JSON.parse(queryText);
+            runQuery(selectedCollection, query);
+        } catch (e) {
+            showToast('Invalid query JSON', 'error');
+        }
+    }
+
+    function handleSort(field) {
+        var newDir = sortField === field && sortDir === 'asc' ? 'desc' : 'asc';
+        setSortField(field);
+        setSortDir(newDir);
+
+        try {
+            var query = JSON.parse(queryText);
+            var sortObj = {};
+            sortObj[field] = newDir;
+            query.sort = [sortObj];
+            setQueryText(JSON.stringify(query));
+            runQuery(selectedCollection, query);
+        } catch(e) {
+            // sort client-side as fallback
+            var sorted = documents.slice().sort(function(a, b) {
+                var va = a[field], vb = b[field];
+                if (va < vb) return newDir === 'asc' ? -1 : 1;
+                if (va > vb) return newDir === 'asc' ? 1 : -1;
+                return 0;
+            });
+            setDocuments(sorted);
+        }
+    }
+
+    function handleObserveQuery() {
+        if (!connectionRef.current || !selectedCollection) return;
+        var query;
+        try {
+            query = JSON.parse(queryText);
+        } catch(e) {
+            showToast('Invalid query JSON', 'error');
+            return;
+        }
+        var observeId = 'obs-' + Date.now() + '-' + Math.random().toString(36).substr(2, 6);
+        connectionRef.current.sendRequest('observeQuery', {
+            observeId: observeId,
+            collection: selectedCollection,
+            query: query
+        }).then(function() {
+            setObservedQueries(function(prev) {
+                return prev.concat([{
+                    id: observeId,
+                    collection: selectedCollection,
+                    query: query,
+                    results: [],
+                    resultCount: 0,
+                    lastUpdated: null
+                }]);
+            });
+            setShowObserver(true);
+            showToast('Query observation started');
+        }).catch(function(err) {
+            showToast('Failed to observe: ' + err.message, 'error');
+        });
+    }
+
+    function handleUnobserve(observeId) {
+        if (!connectionRef.current) return;
+        connectionRef.current.sendRequest('unobserveQuery', { observeId: observeId }).then(function() {
+            setObservedQueries(function(prev) { return prev.filter(function(q) { return q.id !== observeId; }); });
+        }).catch(function() {});
+    }
+
+    function handleViewObservedResults(q) {
+        if (q.results && q.results.length > 0) {
+            setDocuments(q.results);
+            setSelectedCollection(q.collection);
+            setActiveTab('data');
+        }
+    }
+
+    function handleEditDoc(doc) {
+        // Remove internal fields for editing
+        var editDoc = Object.assign({}, doc);
+        delete editDoc._rev;
+        delete editDoc._meta;
+        delete editDoc._deleted;
+        delete editDoc._attachments;
+        setEditModal({
+            open: true,
+            title: 'Edit Document',
+            value: JSON.stringify(editDoc, null, 2),
+            error: null,
+            mode: 'edit'
+        });
+    }
+
+    function handleAddDoc() {
+        if (!collectionInfo || !collectionInfo.schema) return;
+        var template = {};
+        var schema = collectionInfo.schema;
+        if (schema.properties) {
+            Object.keys(schema.properties).forEach(function(key) {
+                if (key.startsWith('_')) return;
+                var prop = schema.properties[key];
+                if (prop.type === 'string') template[key] = '';
+                else if (prop.type === 'number' || prop.type === 'integer') template[key] = 0;
+                else if (prop.type === 'boolean') template[key] = false;
+                else if (prop.type === 'array') template[key] = [];
+                else if (prop.type === 'object') template[key] = {};
+                else template[key] = null;
+            });
+        }
+        setEditModal({
+            open: true,
+            title: 'Add Document',
+            value: JSON.stringify(template, null, 2),
+            error: null,
+            mode: 'add'
+        });
+    }
+
+    function handleSaveDoc(text) {
+        if (!connectionRef.current || !selectedCollection) return;
+        var doc;
+        try {
+            doc = JSON.parse(text);
+        } catch(e) {
+            setEditModal(function(prev) { return Object.assign({}, prev, { error: 'Invalid JSON' }); });
+            return;
+        }
+        connectionRef.current.sendRequest('writeDocument', {
+            collection: selectedCollection,
+            document: doc
+        }).then(function() {
+            setEditModal({ open: false, title: '', value: '', error: null, mode: null });
+            showToast(editModal.mode === 'add' ? 'Document added' : 'Document updated');
+            runQuery(selectedCollection, JSON.parse(queryText || '{}'));
+            loadCollectionInfo(selectedCollection);
+        }).catch(function(err) {
+            setEditModal(function(prev) { return Object.assign({}, prev, { error: err.message }); });
+        });
+    }
+
+    function handleDeleteDoc(doc) {
+        if (!connectionRef.current || !selectedCollection || !collectionInfo) return;
+        var pk = collectionInfo.primaryKey;
+        if (!pk || !doc[pk]) {
+            showToast('Cannot determine primary key', 'error');
+            return;
+        }
+        if (!confirm('Delete document "' + doc[pk] + '"?')) return;
+        connectionRef.current.sendRequest('deleteDocument', {
+            collection: selectedCollection,
+            primaryKey: doc[pk]
+        }).then(function() {
+            showToast('Document deleted');
+            setSelectedDoc(null);
+            runQuery(selectedCollection, JSON.parse(queryText || '{}'));
+            loadCollectionInfo(selectedCollection);
+        }).catch(function(err) {
+            showToast('Delete failed: ' + err.message, 'error');
+        });
+    }
+
+    function handleExport() {
+        if (!connectionRef.current || !selectedCollection) return;
+        connectionRef.current.sendRequest('exportCollection', { collection: selectedCollection }).then(function(docs) {
+            var blob = new Blob([JSON.stringify(docs, null, 2)], { type: 'application/json' });
+            var a = document.createElement('a');
+            a.href = URL.createObjectURL(blob);
+            a.download = selectedCollection + '.json';
+            a.click();
+            URL.revokeObjectURL(a.href);
+            showToast('Exported ' + docs.length + ' documents');
+        }).catch(function(err) {
+            showToast('Export failed: ' + err.message, 'error');
+        });
+    }
+
+    function handleRefresh() {
+        if (selectedCollection) {
+            try {
+                runQuery(selectedCollection, JSON.parse(queryText || '{}'));
+                loadCollectionInfo(selectedCollection);
+                loadDbInfo();
+            } catch(e) {
+                runQuery(selectedCollection, {});
+            }
+        }
+    }
+
+    function handleDisconnect() {
+        if (connectionRef.current) {
+            connectionRef.current.close();
+            connectionRef.current = null;
+        }
+        setConnectionState('disconnected');
+        setDbInfo(null);
+        setSelectedCollection(null);
+        setCollectionInfo(null);
+        setDocuments([]);
+        setSelectedDoc(null);
+        setObservedQueries([]);
+    }
+
+    // Get columns from documents
+    var columns = useMemo(function() {
+        if (!documents.length) return [];
+        var colSet = {};
+        // Put primary key first
+        var pk = collectionInfo && collectionInfo.primaryKey;
+        if (pk) colSet[pk] = true;
+        documents.forEach(function(doc) {
+            Object.keys(doc).forEach(function(k) { colSet[k] = true; });
+        });
+        return Object.keys(colSet);
+    }, [documents, collectionInfo]);
+
+    // Disconnected state
+    if (connectionState === 'disconnected') {
+        return h('div', { id: 'app', style: { display: 'flex', flexDirection: 'column', height: '100vh' } },
+            h('div', { className: 'header' },
+                h('div', { className: 'header-left' },
+                    h('span', { className: 'header-logo' }, 'RxDB Viewer')
+                ),
+                h('div', { className: 'header-right' },
+                    h('span', { className: 'connection-status' },
+                        h('span', { className: 'status-dot disconnected' }),
+                        'Disconnected'
+                    )
+                )
+            ),
+            h(ConnectPanel, {
+                paramsText: paramsText,
+                setParamsText: setParamsText,
+                onConnect: handleConnect,
+                error: connError,
+                connecting: connectionState === 'connecting'
+            })
+        );
+    }
+
+    // Connected / connecting state
+    return h('div', { id: 'app', style: { display: 'flex', flexDirection: 'column', height: '100vh' } },
+        h('div', { className: 'header' },
+            h('div', { className: 'header-left' },
+                h('span', { className: 'header-logo' }, 'RxDB Viewer'),
+                dbInfo ? h('span', { className: 'header-db-name' }, dbInfo.databaseName) : null
+            ),
+            h('div', { className: 'header-right' },
+                h('span', { className: 'connection-status' },
+                    h('span', { className: 'status-dot ' + connectionState }),
+                    connectionState === 'connected' ? 'Connected' : 'Connecting...'
+                ),
+                h('button', { className: 'btn btn-secondary btn-sm', onClick: handleDisconnect }, 'Disconnect')
+            )
+        ),
+
+        h('div', { className: 'main-layout' },
+            // Sidebar
+            dbInfo ? h('div', { className: 'sidebar' },
+                h('div', { className: 'sidebar-header' }, 'Collections (' + dbInfo.collections.length + ')'),
+                h('div', { className: 'collection-list' },
+                    dbInfo.collections.map(function(col) {
+                        return h('div', {
+                            key: col.name,
+                            className: 'collection-item' + (selectedCollection === col.name ? ' active' : ''),
+                            onClick: function() { selectCollection(col.name); }
+                        },
+                            h('span', null, col.name),
+                            h('span', { className: 'doc-count' }, col.docCount)
+                        );
+                    })
+                ),
+                // Schema panel in sidebar
+                selectedCollection && collectionInfo ? h('div', { className: 'sidebar-schema' },
+                    h('div', { className: 'sidebar-schema-header', onClick: function() { setShowSchema(!showSchema); } },
+                        h('span', null, 'Schema'),
+                        h('span', null, showSchema ? '\u25BC' : '\u25B6')
+                    ),
+                    showSchema ? h('div', { className: 'sidebar-schema-content' },
+                        h('div', {
+                            className: 'schema-json',
+                            dangerouslySetInnerHTML: { __html: syntaxHighlight(collectionInfo.schema) }
+                        })
+                    ) : null
+                ) : null
+            ) : null,
+
+            // Content
+            h('div', { className: 'content' },
+                selectedCollection ? h(React.Fragment, null,
+                    // Tabs
+                    h('div', { className: 'tabs' },
+                        h('div', {
+                            className: 'tab' + (activeTab === 'data' ? ' active' : ''),
+                            onClick: function() { setActiveTab('data'); }
+                        }, 'Data'),
+                        h('div', {
+                            className: 'tab' + (activeTab === 'schema' ? ' active' : ''),
+                            onClick: function() { setActiveTab('schema'); }
+                        }, 'Schema')
+                    ),
+
+                    activeTab === 'data' ? h(React.Fragment, null,
+                        // Toolbar
+                        h('div', { className: 'toolbar' },
+                            h('input', {
+                                className: 'query-input',
+                                value: queryText,
+                                onChange: function(e) { setQueryText(e.target.value); },
+                                onKeyDown: function(e) { if (e.key === 'Enter') handleRunQuery(); },
+                                placeholder: 'Mango query: { "selector": { "field": "value" } }'
+                            }),
+                            h('button', { className: 'btn btn-primary btn-sm', onClick: handleRunQuery, disabled: loading }, loading ? '...' : 'Run'),
+                            h('button', { className: 'btn btn-secondary btn-sm', onClick: handleObserveQuery, title: 'Observe this query for live updates' }, 'Observe'),
+                            h('button', { className: 'btn btn-secondary btn-sm', onClick: handleRefresh, title: 'Refresh' }, '\u21BB'),
+                            h('button', { className: 'btn btn-secondary btn-sm', onClick: handleAddDoc, title: 'Add document' }, '+ Add'),
+                            h('button', { className: 'btn btn-secondary btn-sm', onClick: handleExport, title: 'Export collection as JSON' }, 'Export')
+                        ),
+
+                        // Table + Detail
+                        h('div', { style: { display: 'flex', flex: 1, overflow: 'hidden' } },
+                            h(DocumentTable, {
+                                documents: documents,
+                                columns: columns,
+                                selectedDoc: selectedDoc,
+                                onSelectDoc: function(doc) { setSelectedDoc(doc); },
+                                sortField: sortField,
+                                sortDir: sortDir,
+                                onSort: handleSort
+                            }),
+                            selectedDoc ? h(DetailPanel, {
+                                doc: selectedDoc,
+                                onClose: function() { setSelectedDoc(null); },
+                                onEdit: handleEditDoc,
+                                onDelete: handleDeleteDoc
+                            }) : null
+                        )
+                    ) : null,
+
+                    activeTab === 'schema' ? h(SchemaView, {
+                        schema: collectionInfo ? collectionInfo.schema : null
+                    }) : null
+                ) : h('div', { className: 'empty-state' },
+                    connectionState === 'connecting' ?
+                        h('div', null,
+                            h('div', { style: { fontSize: 32, marginBottom: 8 } }, '\u231B'),
+                            'Connecting to database...'
+                        ) :
+                        h('div', null,
+                            h('div', { style: { fontSize: 32, marginBottom: 8 } }, '\u{1F4E6}'),
+                            'Select a collection from the sidebar'
+                        )
+                ),
+
+                // Query Observer Panel
+                observedQueries.length > 0 || showObserver ? h(QueryObserverPanel, {
+                    queries: observedQueries,
+                    onRemove: handleUnobserve,
+                    isOpen: showObserver,
+                    onToggle: function() { setShowObserver(!showObserver); },
+                    onViewResults: handleViewObservedResults
+                }) : null
+            )
+        ),
+
+        // Status bar
+        h('div', { className: 'status-bar' },
+            h('span', null, selectedCollection ?
+                selectedCollection + ' \u2022 ' + documents.length + ' documents' + (collectionInfo ? ' / ' + collectionInfo.docCount + ' total' : '') :
+                'No collection selected'
+            ),
+            h('span', null, dbInfo ? dbInfo.databaseName : '')
+        ),
+
+        // Edit modal
+        h(EditModal, {
+            isOpen: editModal.open,
+            title: editModal.title,
+            initialValue: editModal.value,
+            error: editModal.error,
+            onSave: handleSaveDoc,
+            onCancel: function() { setEditModal({ open: false, title: '', value: '', error: null, mode: null }); }
+        }),
+
+        // Toast
+        toast ? h('div', { className: 'toast ' + toast.type }, toast.msg) : null
+    );
+}
+
+ReactDOM.createRoot(document.getElementById('root')).render(h(App));
+</script>
+</body>
+</html>

From 0561f3a28de64eb06ae9344459d509cbaa84f396 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 18 Mar 2026 19:51:38 +0000
Subject: [PATCH 2/5] Reuse docs-src component patterns in viewer UI

Align viewer.html with docs-src design system:
- CSS variables now reference docs-src tokens (--color-top, --color-middle,
  --color-bottom, --bg-color, --bg-color-dark, --bg-color-code)
- Button styles match docs-src Button component (gradient primary, border
  secondary with white inversion on hover)
- Added ViewerButton React component mirroring button.tsx behavior including
  mouse-following radial gradient on primary hover
- Tab active indicator uses gradient border-image matching side-tabs pattern
- Collection sidebar active state uses gradient left-border indicator from
  docs-src side-tabs__tab--active
- Modal matches docs-src Modal component (no border-radius, bg-color
  background, close button styling)
- Badge/pill shapes use border-radius: 20px matching docs-src Tag component
- Transition timing updated to 0.2s matching docs-src standard

https://claude.ai/code/session_01E4LPySRrjXCCRdV9pVKJom
---
 src/plugins/viewer/viewer.html | 244 +++++++++++++++++++++++++--------
 1 file changed, 186 insertions(+), 58 deletions(-)

diff --git a/src/plugins/viewer/viewer.html b/src/plugins/viewer/viewer.html
index b36502c350f..59e6300ddc9 100644
--- a/src/plugins/viewer/viewer.html
+++ b/src/plugins/viewer/viewer.html
@@ -9,11 +9,21 @@
     <script src="https://unpkg.com/simple-peer@9/simplepeer.min.js"></script>
     <style>
         :root {
-            --bg-primary: #20293C;
-            --bg-secondary: #0D0F18;
-            --bg-tertiary: #282330;
+            /* Match docs-src/src/css/custom.css design tokens */
+            --color-top: #ED168F;
+            --color-middle: #b2218b;
+            --color-bottom: #752a8a;
+            --bg-color: #20293C;
+            --bg-color-dark: #0D0F18;
+            --bg-color-darkest: #0D0F18;
+            --bg-color-code: #282330;
+
+            /* Viewer-specific aliases using docs-src tokens */
+            --bg-primary: var(--bg-color);
+            --bg-secondary: var(--bg-color-dark);
+            --bg-tertiary: var(--bg-color-code);
             --bg-input: #1a2235;
-            --color-primary: #ED168F;
+            --color-primary: var(--color-top);
             --color-primary-hover: #ff2da6;
             --color-accent: #29d5b0;
             --color-text: #ffffff;
@@ -30,7 +40,7 @@
             --color-orange: #FFB86C;
             --radius: 6px;
             --radius-sm: 4px;
-            --transition: all 0.15s ease-in-out;
+            --transition: all 0.2s ease-in-out;
         }
 
         * { margin: 0; padding: 0; box-sizing: border-box; }
@@ -60,7 +70,7 @@
         .header-logo {
             font-size: 18px;
             font-weight: 800;
-            background: linear-gradient(90deg, var(--color-primary), #b2218b);
+            background: linear-gradient(90deg, var(--color-top), var(--color-middle));
             -webkit-background-clip: text;
             -webkit-text-fill-color: transparent;
             background-clip: text;
@@ -101,7 +111,7 @@
             overflow: hidden;
         }
 
-        /* Sidebar */
+        /* Sidebar - matches docs-src side-tabs pattern */
         .sidebar {
             width: 240px;
             min-width: 240px;
@@ -133,12 +143,26 @@
             cursor: pointer;
             transition: var(--transition);
             font-size: 14px;
+            font-weight: 500;
             margin-bottom: 2px;
+            position: relative;
         }
         .collection-item:hover { background: rgba(255,255,255,0.05); }
+        /* Active state uses gradient indicator like docs-src side-tabs__tab--active */
         .collection-item.active {
             background: linear-gradient(90deg, rgba(237,22,143,0.15), rgba(178,33,139,0.1));
-            color: var(--color-primary);
+            color: var(--color-top);
+            font-weight: 800;
+        }
+        .collection-item.active::before {
+            content: '';
+            position: absolute;
+            left: 0;
+            top: 4px;
+            bottom: 4px;
+            width: 3px;
+            background: linear-gradient(180deg, var(--color-top), var(--color-middle));
+            border-radius: 0 2px 2px 0;
         }
         .collection-item .doc-count {
             font-size: 12px;
@@ -149,7 +173,7 @@
         }
         .collection-item.active .doc-count {
             background: rgba(237,22,143,0.2);
-            color: var(--color-primary);
+            color: var(--color-top);
         }
 
         /* Schema panel in sidebar */
@@ -219,12 +243,12 @@
             transition: var(--transition);
         }
         .query-input:focus {
-            border-color: var(--color-primary);
+            border-color: var(--color-top);
             box-shadow: 0 0 0 2px rgba(237,22,143,0.15);
         }
         .query-input::placeholder { color: var(--color-text-dim); }
 
-        /* Tabs */
+        /* Tabs - matches docs-src side-tabs horizontal style with gradient indicator */
         .tabs {
             display: flex;
             gap: 0;
@@ -234,47 +258,63 @@
             flex-shrink: 0;
         }
         .tab {
-            padding: 8px 16px;
-            font-size: 13px;
+            padding: 10px 16px;
+            font-size: 14px;
+            font-weight: 500;
             cursor: pointer;
             color: var(--color-text-secondary);
-            border-bottom: 2px solid transparent;
+            border-bottom: 3px solid transparent;
             transition: var(--transition);
+            user-select: none;
         }
         .tab:hover { color: var(--color-text); }
         .tab.active {
-            color: var(--color-primary);
-            border-bottom-color: var(--color-primary);
+            color: var(--color-text);
+            font-weight: 800;
+            border-image: linear-gradient(90deg, var(--color-top), var(--color-middle)) 1;
+            border-bottom-width: 3px;
+            border-bottom-style: solid;
         }
 
-        /* Buttons */
+        /* Buttons - matches docs-src Button component (button.tsx) */
         .btn {
-            padding: 7px 14px;
+            display: inline-flex;
+            height: 36px;
+            align-items: center;
+            justify-content: center;
+            gap: 6px;
+            padding: 0 14px;
             border-radius: var(--radius-sm);
             border: none;
             cursor: pointer;
             font-size: 13px;
             font-weight: 600;
             transition: var(--transition);
-            display: inline-flex;
-            align-items: center;
-            gap: 6px;
+            text-decoration: none;
+            position: relative;
+            overflow: hidden;
+            user-select: none;
+            line-height: initial;
         }
+        /* Primary: gradient from --color-top to --color-middle (matches button.tsx primary) */
         .btn-primary {
-            background: linear-gradient(90deg, var(--color-primary), #b2218b);
+            background: linear-gradient(90deg, var(--color-top) 0%, var(--color-middle) 100%);
             color: white;
+            font-weight: 800;
         }
         .btn-primary:hover {
-            box-shadow: 0 0 6px rgba(237,22,143,0.4);
+            box-shadow: 0 0 8px rgba(237,22,143,0.4);
         }
+        /* Secondary: transparent with border, inverts on hover (matches button.tsx secondary) */
         .btn-secondary {
             background: transparent;
             border: 1px solid var(--color-border);
             color: var(--color-text-secondary);
         }
         .btn-secondary:hover {
-            background: rgba(255,255,255,0.05);
-            color: var(--color-text);
+            background: #fff;
+            color: var(--bg-color-dark);
+            border-color: #fff;
         }
         .btn-danger {
             background: transparent;
@@ -285,7 +325,8 @@
             background: rgba(252,129,129,0.1);
         }
         .btn-sm {
-            padding: 4px 10px;
+            height: 30px;
+            padding: 0 10px;
             font-size: 12px;
         }
         .btn:disabled {
@@ -321,7 +362,7 @@
             z-index: 1;
         }
         .doc-table th:hover { color: var(--color-text-secondary); }
-        .doc-table th.sorted { color: var(--color-primary); }
+        .doc-table th.sorted { color: var(--color-top); }
         .doc-table td {
             padding: 8px 14px;
             border-bottom: 1px solid rgba(45,55,72,0.5);
@@ -412,7 +453,7 @@
             font-size: 24px;
             font-weight: 800;
             margin-bottom: 8px;
-            background: linear-gradient(90deg, var(--color-primary), #b2218b);
+            background: linear-gradient(90deg, var(--color-top), var(--color-middle));
             -webkit-background-clip: text;
             -webkit-text-fill-color: transparent;
             background-clip: text;
@@ -446,7 +487,7 @@
             transition: var(--transition);
         }
         .connect-textarea:focus {
-            border-color: var(--color-primary);
+            border-color: var(--color-top);
             box-shadow: 0 0 0 2px rgba(237,22,143,0.15);
         }
         .connect-error {
@@ -508,14 +549,17 @@
             gap: 12px;
             align-items: center;
         }
+        /* Badge - matches docs-src Tag component (pill shape, border-radius: 20px) */
         .observer-badge {
             display: inline-flex;
             align-items: center;
             gap: 4px;
-            padding: 2px 8px;
-            border-radius: 10px;
+            padding: 2px 10px;
+            border-radius: 20px;
             font-size: 11px;
             font-weight: 600;
+            user-select: none;
+            transition: var(--transition);
         }
         .observer-badge.live {
             background: rgba(104,211,145,0.15);
@@ -534,7 +578,7 @@
             gap: 8px;
         }
 
-        /* Edit modal */
+        /* Modal - matches docs-src Modal component (no border-radius, bg-color bg) */
         .modal-overlay {
             position: fixed;
             top: 0;
@@ -548,21 +592,29 @@
             z-index: 100;
         }
         .modal {
-            background: var(--bg-secondary);
+            background: var(--bg-color);
             border: 1px solid var(--color-border);
-            border-radius: var(--radius);
-            padding: 24px;
+            border-radius: 0;
+            padding: 0;
             width: 600px;
+            max-width: 90vw;
             max-height: 80vh;
             display: flex;
             flex-direction: column;
+            color: white;
+            font-weight: 700;
         }
         .modal-title {
             font-size: 16px;
             font-weight: 700;
-            margin-bottom: 16px;
+            padding: 16px 20px;
+            border-bottom: 1px solid var(--color-border);
+        }
+        .modal-body {
+            flex: 1;
+            overflow-y: auto;
+            padding: 16px;
         }
-        .modal-body { flex: 1; overflow-y: auto; }
         .modal textarea {
             width: 100%;
             min-height: 300px;
@@ -577,18 +629,38 @@
             outline: none;
         }
         .modal textarea:focus {
-            border-color: var(--color-primary);
+            border-color: var(--color-top);
         }
         .modal-actions {
             display: flex;
             justify-content: flex-end;
             gap: 8px;
-            margin-top: 16px;
+            padding: 16px;
+            border-top: 1px solid var(--color-border);
         }
         .modal-error {
             color: var(--color-error);
             font-size: 13px;
-            margin-top: 8px;
+            padding: 8px 16px;
+        }
+        /* Close button - matches docs-src Modal close icon style */
+        .modal-close {
+            display: inline-flex;
+            align-items: center;
+            justify-content: center;
+            width: 28px;
+            height: 28px;
+            border-radius: 8px;
+            cursor: pointer;
+            transition: var(--transition);
+            color: var(--color-text-secondary);
+            background: transparent;
+            border: none;
+            font-size: 16px;
+        }
+        .modal-close:hover {
+            background: rgba(255,255,255,0.1);
+            color: var(--color-text);
         }
 
         /* Toast notification */
@@ -850,6 +922,59 @@
     return String(val);
 }
 
+// ========== Reusable Button Component ==========
+// Mirrors docs-src/src/components/button.tsx behavior:
+// - Primary: gradient background, mouse-following radial gradient on hover
+// - Secondary: transparent with border, inverts to white bg on hover
+function ViewerButton(props) {
+    var _hovered = useState(false);
+    var hovered = _hovered[0], setHovered = _hovered[1];
+    var _mousePos = useState(null);
+    var mousePos = _mousePos[0], setMousePos = _mousePos[1];
+
+    var isPrimary = props.variant === 'primary';
+    var isDanger = props.variant === 'danger';
+    var isSmall = props.small;
+
+    var baseStyle = {};
+
+    // Primary hover: radial gradient following mouse (from button.tsx)
+    if (isPrimary && hovered && mousePos) {
+        baseStyle.background = 'radial-gradient(circle at ' + mousePos.x + 'px ' + mousePos.y + 'px, var(--color-middle), var(--color-top))';
+    }
+    // Secondary hover: invert to white (from button.tsx)
+    if (!isPrimary && !isDanger && hovered) {
+        baseStyle.background = '#fff';
+        baseStyle.color = 'var(--bg-color-dark)';
+        baseStyle.borderColor = '#fff';
+    }
+
+    Object.assign(baseStyle, props.style || {});
+
+    var className = 'btn';
+    if (isPrimary) className += ' btn-primary';
+    else if (isDanger) className += ' btn-danger';
+    else className += ' btn-secondary';
+    if (isSmall) className += ' btn-sm';
+    if (props.className) className += ' ' + props.className;
+
+    return h('button', {
+        className: className,
+        style: baseStyle,
+        onClick: props.onClick,
+        disabled: props.disabled,
+        title: props.title,
+        onMouseEnter: function() { setHovered(true); },
+        onMouseLeave: function() { setHovered(false); setMousePos(null); },
+        onMouseMove: function(e) {
+            if (isPrimary) {
+                var rect = e.currentTarget.getBoundingClientRect();
+                setMousePos({ x: e.clientX - rect.left, y: e.clientY - rect.top });
+            }
+        }
+    }, props.children);
+}
+
 // ========== React Components ==========
 
 function ConnectPanel(props) {
@@ -874,11 +999,11 @@
                 spellCheck: false
             }),
             error ? h('div', { className: 'connect-error' }, error) : null,
-            h('button', {
-                className: 'btn btn-primary',
+            h(ViewerButton, {
+                variant: 'primary',
                 onClick: onConnect,
                 disabled: connecting,
-                style: { width: '100%', justifyContent: 'center', height: 42 }
+                style: { width: '100%', justifyContent: 'center', height: 45 }
             }, connecting ? 'Connecting...' : 'Connect')
         )
     );
@@ -949,7 +1074,7 @@
     return h('div', { className: 'detail-panel' },
         h('div', { className: 'detail-header' },
             h('span', null, 'Document Detail'),
-            h('button', { className: 'btn btn-secondary btn-sm', onClick: onClose }, '\u2715')
+            h('button', { className: 'modal-close', onClick: onClose }, '\u2715')
         ),
         h('div', { className: 'detail-body' },
             h('div', {
@@ -958,9 +1083,9 @@
             })
         ),
         h('div', { className: 'detail-actions' },
-            h('button', { className: 'btn btn-secondary btn-sm', onClick: function() { onEdit(doc); } }, 'Edit'),
-            h('button', { className: 'btn btn-danger btn-sm', onClick: function() { onDelete(doc); } }, 'Delete'),
-            h('button', { className: 'btn btn-secondary btn-sm', onClick: function() {
+            h(ViewerButton, { variant: 'secondary', small: true, onClick: function() { onEdit(doc); } }, 'Edit'),
+            h(ViewerButton, { variant: 'danger', small: true, onClick: function() { onDelete(doc); } }, 'Delete'),
+            h(ViewerButton, { variant: 'secondary', small: true, onClick: function() {
                 navigator.clipboard.writeText(JSON.stringify(doc, null, 2));
             }}, 'Copy JSON')
         )
@@ -990,7 +1115,10 @@
         if (e.target === e.currentTarget) onCancel();
     }},
         h('div', { className: 'modal' },
-            h('div', { className: 'modal-title' }, title),
+            h('div', { style: { display: 'flex', alignItems: 'center', justifyContent: 'space-between' } },
+                h('div', { className: 'modal-title' }, title),
+                h('button', { className: 'modal-close', onClick: onCancel }, '\u2715')
+            ),
             h('div', { className: 'modal-body' },
                 h('textarea', {
                     ref: textRef,
@@ -1001,8 +1129,8 @@
             ),
             error ? h('div', { className: 'modal-error' }, error) : null,
             h('div', { className: 'modal-actions' },
-                h('button', { className: 'btn btn-secondary', onClick: onCancel }, 'Cancel'),
-                h('button', { className: 'btn btn-primary', onClick: function() {
+                h(ViewerButton, { variant: 'secondary', onClick: onCancel }, 'Cancel'),
+                h(ViewerButton, { variant: 'primary', onClick: function() {
                     onSave(currentText.current);
                 }}, 'Save')
             )
@@ -1035,10 +1163,10 @@
                                 h('span', { className: 'observer-badge live', style: { marginLeft: 8 } }, '\u25CF Live')
                             ),
                             h('div', { style: { display: 'flex', gap: 6 } },
-                                h('button', { className: 'btn btn-secondary btn-sm', onClick: function() { onViewResults(q); } },
+                                h(ViewerButton, { variant: 'secondary', small: true, onClick: function() { onViewResults(q); } },
                                     q.resultCount + ' docs'
                                 ),
-                                h('button', { className: 'btn btn-danger btn-sm', onClick: function() { onRemove(q.id); } }, '\u2715')
+                                h(ViewerButton, { variant: 'danger', small: true, onClick: function() { onRemove(q.id); } }, '\u2715')
                             )
                         ),
                         h('div', { className: 'observer-item-query' }, JSON.stringify(q.query || {})),
@@ -1467,7 +1595,7 @@
                     h('span', { className: 'status-dot ' + connectionState }),
                     connectionState === 'connected' ? 'Connected' : 'Connecting...'
                 ),
-                h('button', { className: 'btn btn-secondary btn-sm', onClick: handleDisconnect }, 'Disconnect')
+                h(ViewerButton, { variant: 'secondary', small: true, onClick: handleDisconnect }, 'Disconnect')
             )
         ),
 
@@ -1527,11 +1655,11 @@
                                 onKeyDown: function(e) { if (e.key === 'Enter') handleRunQuery(); },
                                 placeholder: 'Mango query: { "selector": { "field": "value" } }'
                             }),
-                            h('button', { className: 'btn btn-primary btn-sm', onClick: handleRunQuery, disabled: loading }, loading ? '...' : 'Run'),
-                            h('button', { className: 'btn btn-secondary btn-sm', onClick: handleObserveQuery, title: 'Observe this query for live updates' }, 'Observe'),
-                            h('button', { className: 'btn btn-secondary btn-sm', onClick: handleRefresh, title: 'Refresh' }, '\u21BB'),
-                            h('button', { className: 'btn btn-secondary btn-sm', onClick: handleAddDoc, title: 'Add document' }, '+ Add'),
-                            h('button', { className: 'btn btn-secondary btn-sm', onClick: handleExport, title: 'Export collection as JSON' }, 'Export')
+                            h(ViewerButton, { variant: 'primary', small: true, onClick: handleRunQuery, disabled: loading }, loading ? '...' : 'Run'),
+                            h(ViewerButton, { variant: 'secondary', small: true, onClick: handleObserveQuery, title: 'Observe this query for live updates' }, 'Observe'),
+                            h(ViewerButton, { variant: 'secondary', small: true, onClick: handleRefresh, title: 'Refresh' }, '\u21BB'),
+                            h(ViewerButton, { variant: 'secondary', small: true, onClick: handleAddDoc, title: 'Add document' }, '+ Add'),
+                            h(ViewerButton, { variant: 'secondary', small: true, onClick: handleExport, title: 'Export collection as JSON' }, 'Export')
                         ),
 
                         // Table + Detail

From 135fa7ba605c2f3d10d5ad5c13e50dc458746beb Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 18 Mar 2026 21:29:32 +0000
Subject: [PATCH 3/5] Lazily start viewer server from
 getDatabaseConnectionParams

- getDatabaseConnectionParams() now creates the viewer server on first
  call and caches it per database, removing the need to call
  startRxDBViewer() beforehand
- Viewer server auto-closes when the database closes via database.onClose
- Removed VW1 error code and newRxError import since the function no
  longer throws when no server exists
- startRxDBViewer() still available but now also reuses cached state
- Made startViewerServer() a private function since the public API is
  getDatabaseConnectionParams() and startRxDBViewer()

https://claude.ai/code/session_01E4LPySRrjXCCRdV9pVKJom
---
 src/plugins/viewer/viewer-server.ts | 40 +++++++++++++++++++++++------
 1 file changed, 32 insertions(+), 8 deletions(-)

diff --git a/src/plugins/viewer/viewer-server.ts b/src/plugins/viewer/viewer-server.ts
index 3f75629e919..91aa1d15187 100644
--- a/src/plugins/viewer/viewer-server.ts
+++ b/src/plugins/viewer/viewer-server.ts
@@ -4,7 +4,6 @@ import {
     ensureNotFalsy,
     randomToken
 } from '../../plugins/utils/index.ts';
-import { newRxError } from '../../rx-error.ts';
 import type {
     ViewerConnectionParams,
     ViewerRequest,
@@ -187,10 +186,10 @@ async function handleViewerRequest(
     }
 }
 
-export async function startRxDBViewer(
+function startViewerServer(
     database: RxDatabase,
     options: ViewerServerOptions = {}
-): Promise<ViewerState> {
+): ViewerState {
     const topic = options.topic || 'rxdb-viewer-' + randomToken(12);
     const signalingServerUrl = options.signalingServerUrl || VIEWER_DEFAULT_SIGNALING_SERVER;
     const WebSocketConstructor = options.webSocketConstructor || WebSocket;
@@ -332,17 +331,42 @@ export async function startRxDBViewer(
     };
 
     VIEWER_STATE_BY_DATABASE.set(database, state);
+
+    // Auto-close when the database closes
+    database.onClose.push(() => state.close());
+
     return state;
 }
 
+/**
+ * Get the connection parameters for a database's viewer server.
+ * Lazily starts the viewer server on first call and caches it.
+ * The server is automatically closed when the database is closed.
+ */
 export function getDatabaseConnectionParams(
-    database: RxDatabase
+    database: RxDatabase,
+    options?: ViewerServerOptions
 ): ViewerConnectionParams {
-    const state = VIEWER_STATE_BY_DATABASE.get(database);
+    let state = VIEWER_STATE_BY_DATABASE.get(database);
     if (!state) {
-        throw newRxError('VW1', {
-            database: database.name
-        });
+        state = startViewerServer(database, options);
     }
     return state.connectionParams;
 }
+
+/**
+ * Start the viewer server explicitly.
+ * Prefer using getDatabaseConnectionParams() which handles
+ * lazy initialization and caching automatically.
+ */
+export async function startRxDBViewer(
+    database: RxDatabase,
+    options: ViewerServerOptions = {}
+): Promise<ViewerState> {
+    let state = VIEWER_STATE_BY_DATABASE.get(database);
+    if (state) {
+        return state;
+    }
+    state = startViewerServer(database, options);
+    return state;
+}

From 8d0cbfd98dc9b59b2ed08e05b75f1dd1a24ee594 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 18 Mar 2026 21:41:28 +0000
Subject: [PATCH 4/5] Add viewer plugin documentation and tests

- Add docs-src/docs/viewer.md with usage guide covering lazy init,
  options, lifecycle, query examples, and security notes
- Add viewer to sidebar under Advanced Features in sidebars.js
- Add test/unit/viewer.test.ts with 12 tests covering:
  - getDatabaseConnectionParams() lazy creation, caching, custom options
  - startRxDBViewer() state management, shared state with getParams
  - Auto-close on database close
  - VIEWER_DEFAULT_SIGNALING_SERVER export
- Fix WebSocket cleanup in viewer-server.ts: handle async errors from
  ws.terminate() via error listener, guard onclose/peer-close reconnect
  with closed flag, add idempotent close()

https://claude.ai/code/session_01E4LPySRrjXCCRdV9pVKJom
---
 docs-src/docs/viewer.md             | 139 +++++++++++++++++++
 docs-src/sidebars.js                |   5 +
 src/plugins/viewer/viewer-server.ts |  47 ++++++-
 test/unit.test.ts                   |   1 +
 test/unit/viewer.test.ts            | 199 ++++++++++++++++++++++++++++
 5 files changed, 386 insertions(+), 5 deletions(-)
 create mode 100644 docs-src/docs/viewer.md
 create mode 100644 test/unit/viewer.test.ts

diff --git a/docs-src/docs/viewer.md b/docs-src/docs/viewer.md
new file mode 100644
index 00000000000..4fc8f68004e
--- /dev/null
+++ b/docs-src/docs/viewer.md
@@ -0,0 +1,139 @@
+---
+title: RxDB Viewer - Remote Database Inspection
+slug: viewer.html
+description: Inspect and manage your RxDB database remotely with the Viewer plugin. Browse collections, run queries, edit documents and observe live changes through a WebRTC connection.
+---
+
+import {Steps} from '@site/src/components/steps';
+
+# RxDB Viewer
+
+The RxDB Viewer plugin provides a browser-based UI to inspect and manage any RxDB database remotely. It connects to your running application over WebRTC, so no additional server infrastructure is required. Data flows directly between your app and the viewer in a peer-to-peer connection.
+
+## Features
+
+- Browse all collections with document counts
+- View collection schemas
+- Run Mango queries with sorting
+- Observe queries for live-updating results via RxDB's reactive system
+- Create, edit and delete documents
+- Export collections as JSON
+- Syntax-highlighted JSON document viewer
+
+## How it Works
+
+The viewer plugin starts a lightweight WebRTC signaling process inside your application. When you open the viewer HTML page in a browser and paste the connection parameters, a direct peer-to-peer connection is established. All database operations (queries, writes, deletes) are sent as messages over this WebRTC data channel.
+
+Because it uses WebRTC, the viewer works across different machines on the same network, across the internet (via the signaling server), and even between different JavaScript runtimes (Node.js, browser, React Native).
+
+## Installation
+
+```ts
+import {
+    getDatabaseConnectionParams
+} from 'rxdb/plugins/viewer';
+```
+
+## Usage
+
+<Steps>
+
+## Get connection parameters
+
+Call `getDatabaseConnectionParams()` with your database instance. The viewer server starts lazily on the first call and is cached for subsequent calls.
+
+```ts
+import { getDatabaseConnectionParams } from 'rxdb/plugins/viewer';
+
+const connectionParams = getDatabaseConnectionParams(myRxDatabase);
+console.log(JSON.stringify(connectionParams, null, 2));
+// {
+//   "topic": "rxdb-viewer-abc123...",
+//   "signalingServerUrl": "wss://signaling.rxdb.info/",
+//   "databaseName": "mydb"
+// }
+```
+
+You can pass options to customize the signaling server or topic:
+
+```ts
+const connectionParams = getDatabaseConnectionParams(myRxDatabase, {
+    signalingServerUrl: 'wss://my-signaling-server.com/',
+    topic: 'my-custom-topic'
+});
+```
+
+## Open the viewer
+
+The viewer is a standalone HTML page bundled with the plugin. You can serve it from your application or open it directly. It is located at `node_modules/rxdb/dist/plugins/viewer/viewer.html`.
+
+## Connect
+
+Paste the connection parameters JSON into the viewer's connection form and click **Connect**. The viewer establishes a WebRTC peer-to-peer connection to your application and loads the database structure.
+
+</Steps>
+
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `signalingServerUrl` | `string` | `wss://signaling.rxdb.info/` | WebSocket URL of the signaling server used to establish the WebRTC connection |
+| `topic` | `string` | Auto-generated | A unique room identifier. Both sides must use the same topic to connect. |
+| `webSocketConstructor` | `WebSocket` constructor | Global `WebSocket` | Custom WebSocket implementation, useful in Node.js environments. |
+
+## Automatic Lifecycle
+
+The viewer server is managed automatically:
+
+- **Lazy start**: The server is created on the first call to `getDatabaseConnectionParams()` and cached per database.
+- **Auto-close**: When the database is closed (via `database.close()`), the viewer server shuts down automatically, closing all WebRTC connections and cleaning up subscriptions.
+- **Shared instance**: Multiple calls to `getDatabaseConnectionParams()` for the same database return the same connection parameters.
+
+## Using `startRxDBViewer()` directly
+
+If you need access to the `ViewerState` object (for example, to manually close the viewer before the database closes), you can use `startRxDBViewer()`:
+
+```ts
+import { startRxDBViewer } from 'rxdb/plugins/viewer';
+
+const viewerState = await startRxDBViewer(myRxDatabase, {
+    signalingServerUrl: 'wss://signaling.rxdb.info/'
+});
+
+// The connection params are available on the state
+console.log(viewerState.connectionParams);
+
+// Manually close the viewer
+await viewerState.close();
+```
+
+## Viewer Capabilities
+
+Once connected, the viewer UI supports these operations:
+
+**Browsing**: The left sidebar lists all collections with document counts. Click a collection to load its documents in a table view. Click any row to see the full document JSON in the detail panel.
+
+**Querying**: Enter a [Mango query](./rx-query.md) in the query bar and press Run. Click column headers to sort. Example queries:
+
+```json
+{ "selector": { "age": { "$gt": 18 } } }
+```
+
+```json
+{ "selector": { "name": { "$regex": "^A" } }, "limit": 10 }
+```
+
+**Observing**: Click **Observe** to start a live query subscription. The Query Observer panel at the bottom shows all active subscriptions with their result counts and last update times. Results update in real-time as documents change in the database.
+
+**Editing**: Click **+ Add** to create a new document (pre-filled from the collection schema). Select a document and click **Edit** to modify it. Click **Delete** to remove it.
+
+**Exporting**: Click **Export** to download all documents in the current collection as a JSON file.
+
+## Security Considerations
+
+The viewer grants full read and write access to the connected database. Keep the connection parameters private. Anyone with the topic and signaling server URL can connect to your database.
+
+For production use, consider:
+- Using a private signaling server instead of the default public one
+- Generating unique topics per session
+- Only enabling the viewer in development or debug builds
diff --git a/docs-src/sidebars.js b/docs-src/sidebars.js
index 5b9ad80d47f..c5fee855289 100644
--- a/docs-src/sidebars.js
+++ b/docs-src/sidebars.js
@@ -487,6 +487,11 @@ const sidebars = {
           id: 'webmcp',
           label: 'WebMCP'
         },
+        {
+          type: 'doc',
+          id: 'viewer',
+          label: 'Viewer'
+        },
         {
           type: 'doc',
           id: 'third-party-plugins',
diff --git a/src/plugins/viewer/viewer-server.ts b/src/plugins/viewer/viewer-server.ts
index 91aa1d15187..4007ffc7764 100644
--- a/src/plugins/viewer/viewer-server.ts
+++ b/src/plugins/viewer/viewer-server.ts
@@ -186,6 +186,31 @@ async function handleViewerRequest(
     }
 }
 
+function closeSocket(ws: WebSocket | undefined) {
+    if (!ws) {
+        return;
+    }
+    // Remove handlers to prevent reconnection, but keep onerror
+    // as a no-op to catch async errors emitted by ws.terminate()
+    ws.onclose = null;
+    ws.onopen = null;
+    ws.onmessage = null;
+    ws.onerror = () => { /* absorb async errors from terminate/close */ };
+    if (typeof (ws as any).removeAllListeners === 'function') {
+        (ws as any).removeAllListeners('error');
+        (ws as any).on('error', () => { /* absorb */ });
+    }
+    try {
+        if (typeof (ws as any).terminate === 'function') {
+            (ws as any).terminate();
+        } else {
+            ws.close();
+        }
+    } catch (_e) {
+        // Socket may already be closed or in an invalid state
+    }
+}
+
 function startViewerServer(
     database: RxDatabase,
     options: ViewerServerOptions = {}
@@ -205,7 +230,12 @@ function startViewerServer(
             return;
         }
         socket = new WebSocketConstructor(signalingServerUrl);
-        socket.onclose = () => createSocket();
+        socket.onerror = () => { /* handled */ };
+        socket.onclose = () => {
+            if (!closed) {
+                createSocket();
+            }
+        };
         socket.onopen = () => {
             ensureNotFalsy(socket).onmessage = (msgEvent: any) => {
                 const msg: ViewerSignalingMessage = JSON.parse(msgEvent.data as any);
@@ -238,6 +268,9 @@ function startViewerServer(
     }
 
     function createPeerConnection(remotePeerId: string) {
+        if (closed) {
+            return;
+        }
         let disconnected = false;
         const newPeer: ViewerPeer = new (Peer as any)({
             initiator: remotePeerId > ownPeerId,
@@ -278,7 +311,9 @@ function startViewerServer(
                 disconnected = true;
                 cleanupPeer(remotePeerId, newPeer);
             }
-            createPeerConnection(remotePeerId);
+            if (!closed) {
+                createPeerConnection(remotePeerId);
+            }
         });
     }
 
@@ -313,6 +348,9 @@ function startViewerServer(
     const state: ViewerState = {
         connectionParams,
         async close() {
+            if (closed) {
+                return;
+            }
             closed = true;
             clearInterval(pingInterval);
             peerSubscriptions.forEach(peerSubs => {
@@ -323,9 +361,8 @@ function startViewerServer(
                 try { peer.destroy(); } catch (_e) { /* */ }
             });
             peers.clear();
-            if (socket) {
-                try { socket.close(); } catch (_e) { /* */ }
-            }
+            closeSocket(socket);
+            socket = undefined;
             VIEWER_STATE_BY_DATABASE.delete(database);
         }
     };
diff --git a/test/unit.test.ts b/test/unit.test.ts
index d5ab0bc7f4d..a9516c0d544 100644
--- a/test/unit.test.ts
+++ b/test/unit.test.ts
@@ -63,6 +63,7 @@ import './unit/attachments.test.ts';
 import './unit/attachments-compression.test.ts';
 import './unit/migration-storage.test.ts';
 import './unit/webmcp.test.ts';
+import './unit/viewer.test.ts';
 import './unit/crdt.test.ts';
 import './unit/population.test.ts';
 import './unit/leader-election.test.ts';
diff --git a/test/unit/viewer.test.ts b/test/unit/viewer.test.ts
new file mode 100644
index 00000000000..3aed65c1fd8
--- /dev/null
+++ b/test/unit/viewer.test.ts
@@ -0,0 +1,199 @@
+import assert from 'assert';
+import {
+    createRxDatabase,
+    randomToken,
+} from '../../plugins/core/index.mjs';
+import {
+    getDatabaseConnectionParams,
+    startRxDBViewer,
+    VIEWER_DEFAULT_SIGNALING_SERVER,
+} from '../../plugins/viewer/index.mjs';
+import type {
+    ViewerConnectionParams,
+    ViewerState
+} from '../../plugins/viewer/index.mjs';
+import config from './config.ts';
+import {
+    schemaObjects,
+    schemas,
+    isNode,
+    isDeno
+} from '../../plugins/test-utils/index.mjs';
+
+describe('viewer.test.ts', function () {
+    this.timeout(1000 * 20);
+
+    if (isDeno) {
+        // WebRTC/WebSocket polyfills not available in Deno
+        return;
+    }
+
+    let webSocketConstructor: any;
+    describe('init', () => {
+        it('import WebSocket polyfill on Node.js', async () => {
+            if (isNode) {
+                const wsModule = await import('ws');
+                webSocketConstructor = wsModule.WebSocket;
+            }
+        });
+    });
+
+    function getOptions() {
+        return webSocketConstructor
+            ? { webSocketConstructor, signalingServerUrl: 'ws://localhost:18006' }
+            : { signalingServerUrl: 'ws://localhost:18006' };
+    }
+
+    async function createTestDatabase() {
+        const db = await createRxDatabase({
+            name: randomToken(10),
+            storage: config.storage.getStorage(),
+        });
+        await db.addCollections({
+            humans: {
+                schema: schemas.human,
+            },
+        });
+        return db;
+    }
+
+    describe('getDatabaseConnectionParams()', () => {
+        it('should lazily create a viewer server and return connection params', async () => {
+            const db = await createTestDatabase();
+            const params = getDatabaseConnectionParams(db, getOptions());
+
+            assert.ok(params);
+            assert.ok(typeof params.topic === 'string');
+            assert.ok(params.topic.length > 0);
+            assert.ok(typeof params.signalingServerUrl === 'string');
+            assert.strictEqual(params.databaseName, db.name);
+
+            await db.close();
+        });
+
+        it('should return the same params on subsequent calls (cached)', async () => {
+            const db = await createTestDatabase();
+            const params1 = getDatabaseConnectionParams(db, getOptions());
+            const params2 = getDatabaseConnectionParams(db, getOptions());
+
+            assert.strictEqual(params1.topic, params2.topic);
+            assert.strictEqual(params1.signalingServerUrl, params2.signalingServerUrl);
+            assert.strictEqual(params1.databaseName, params2.databaseName);
+
+            await db.close();
+        });
+
+        it('should use custom signaling server URL when provided', async () => {
+            const db = await createTestDatabase();
+            const customUrl = 'ws://localhost:18006';
+            const params = getDatabaseConnectionParams(db, {
+                ...getOptions(),
+                signalingServerUrl: customUrl,
+            });
+
+            assert.strictEqual(params.signalingServerUrl, customUrl);
+
+            await db.close();
+        });
+
+        it('should use custom topic when provided', async () => {
+            const db = await createTestDatabase();
+            const customTopic = 'my-custom-topic-' + randomToken(6);
+            const params = getDatabaseConnectionParams(db, {
+                ...getOptions(),
+                topic: customTopic,
+            });
+
+            assert.strictEqual(params.topic, customTopic);
+
+            await db.close();
+        });
+
+        it('should create different topics for different databases', async () => {
+            const db1 = await createTestDatabase();
+            const db2 = await createTestDatabase();
+
+            const params1 = getDatabaseConnectionParams(db1, getOptions());
+            const params2 = getDatabaseConnectionParams(db2, getOptions());
+
+            assert.notStrictEqual(params1.topic, params2.topic);
+
+            await db1.close();
+            await db2.close();
+        });
+    });
+
+    describe('startRxDBViewer()', () => {
+        it('should return a ViewerState with connectionParams and close()', async () => {
+            const db = await createTestDatabase();
+            const state = await startRxDBViewer(db, getOptions());
+
+            assert.ok(state);
+            assert.ok(state.connectionParams);
+            assert.ok(typeof state.connectionParams.topic === 'string');
+            assert.ok(typeof state.close === 'function');
+
+            await db.close();
+        });
+
+        it('should return the same state if called multiple times', async () => {
+            const db = await createTestDatabase();
+            const state1 = await startRxDBViewer(db, getOptions());
+            const state2 = await startRxDBViewer(db, getOptions());
+
+            assert.strictEqual(state1.connectionParams.topic, state2.connectionParams.topic);
+
+            await db.close();
+        });
+
+        it('should share state with getDatabaseConnectionParams()', async () => {
+            const db = await createTestDatabase();
+            const state = await startRxDBViewer(db, getOptions());
+            const params = getDatabaseConnectionParams(db);
+
+            assert.strictEqual(state.connectionParams.topic, params.topic);
+
+            await db.close();
+        });
+
+        it('should be closable manually', async () => {
+            const db = await createTestDatabase();
+            const state = await startRxDBViewer(db, getOptions());
+
+            // Close the viewer manually
+            await state.close();
+
+            // After closing, getDatabaseConnectionParams creates a new server
+            const newParams = getDatabaseConnectionParams(db, getOptions());
+            assert.notStrictEqual(state.connectionParams.topic, newParams.topic);
+
+            await db.close();
+        });
+    });
+
+    describe('auto-close on database close', () => {
+        it('should clean up viewer when database is closed', async () => {
+            const db = await createTestDatabase();
+            const params = getDatabaseConnectionParams(db, getOptions());
+
+            assert.ok(params.topic);
+
+            // Close the database - this should auto-close the viewer
+            await db.close();
+
+            // Create a new database and verify a new viewer would get new params
+            const db2 = await createTestDatabase();
+            const params2 = getDatabaseConnectionParams(db2, getOptions());
+            assert.notStrictEqual(params.topic, params2.topic);
+
+            await db2.close();
+        });
+    });
+
+    describe('VIEWER_DEFAULT_SIGNALING_SERVER', () => {
+        it('should export the default signaling server URL', () => {
+            assert.ok(typeof VIEWER_DEFAULT_SIGNALING_SERVER === 'string');
+            assert.ok(VIEWER_DEFAULT_SIGNALING_SERVER.startsWith('wss://'));
+        });
+    });
+});

From b937e30c46ccdd05b264aa87befc0c248f489b7f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 18 Mar 2026 21:50:16 +0000
Subject: [PATCH 5/5] Add viewer plugin tests to CI workflow

Add a dedicated test-viewer job to main.yml that builds and runs the
viewer plugin unit tests with the memory storage backend. Fix lint
errors in viewer test (unused imports) and pre-existing docs-src files.

https://claude.ai/code/session_01E4LPySRrjXCCRdV9pVKJom
---
 .github/workflows/main.yml                    | 31 +++++++++++++++++++
 docs-src/refactor-charts.js                   |  8 ++---
 docs-src/replace-charts.js                    |  4 +--
 .../src/components/performance-chart-impl.tsx |  2 +-
 docs-src/src/components/performance-chart.tsx |  4 +--
 docs-src/src/components/performance-node.tsx  | 16 +++++-----
 docs-src/update-colors.js                     |  4 +--
 test/unit/viewer.test.ts                      |  5 ---
 8 files changed, 50 insertions(+), 24 deletions(-)

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 67c15a8458a..a268fb441c4 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -849,6 +849,37 @@ jobs:
   #           flutter config --enable-linux-desktop
   #           flutter test integration_test/basics_test.dart -d linux
 
+  test-viewer:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set node version
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: ".nvmrc"
+
+      - name: Reuse npm cache folder
+        uses: actions/cache@v5
+        env:
+          cache-name: cache-node-modules
+        with:
+          path: |
+            ~/.npm
+            ./node_modules
+          key: ${{ runner.os }}-npm-viewer-x4-${{ hashFiles('**/package.json') }}
+          restore-keys: |
+            ${{ runner.os }}-npm-viewer-x4-
+
+      - name: install npm dependencies
+        run: npm install
+
+      - name: build
+        run: npm run build
+
+      - name: test viewer plugin
+        run: npm run transpile && cross-env DEFAULT_STORAGE=memory mocha --config ./config/.mocharc.cjs ./test_tmp/unit/viewer.test.js --timeout 20000
+
   test-tutorials:
     runs-on: ubuntu-22.04
     timeout-minutes: 30
diff --git a/docs-src/refactor-charts.js b/docs-src/refactor-charts.js
index e1209456ddc..35bbe33307b 100644
--- a/docs-src/refactor-charts.js
+++ b/docs-src/refactor-charts.js
@@ -3,8 +3,8 @@ const path = require('path');
 
 function walkDir(dir, callback) {
     fs.readdirSync(dir).forEach(f => {
-        let dirPath = path.join(dir, f);
-        let isDirectory = fs.statSync(dirPath).isDirectory();
+        const dirPath = path.join(dir, f);
+        const isDirectory = fs.statSync(dirPath).isDirectory();
         if (isDirectory) {
             walkDir(dirPath, callback);
         } else if (f.endsWith('.md') || f.endsWith('.mdx')) {
@@ -42,10 +42,10 @@ walkDir(path.join(__dirname, 'docs'), (filePath) => {
         // Prepare new imports
         let newImports = '';
         if (needsBrowser) {
-            newImports += "import PerformanceBrowser from '@site/src/components/performance-browser';\n";
+            newImports += 'import PerformanceBrowser from \'@site/src/components/performance-browser\';\n';
         }
         if (needsNode) {
-            newImports += "import PerformanceNode from '@site/src/components/performance-node';\n";
+            newImports += 'import PerformanceNode from \'@site/src/components/performance-node\';\n';
         }
 
         // Insert new imports after frontmatter
diff --git a/docs-src/replace-charts.js b/docs-src/replace-charts.js
index 9c671b3e5a6..d47b4fcfc71 100644
--- a/docs-src/replace-charts.js
+++ b/docs-src/replace-charts.js
@@ -67,8 +67,8 @@ const nData = `
 
 function walkDir(dir, callback) {
     fs.readdirSync(dir).forEach(f => {
-        let dirPath = path.join(dir, f);
-        let isDirectory = fs.statSync(dirPath).isDirectory();
+        const dirPath = path.join(dir, f);
+        const isDirectory = fs.statSync(dirPath).isDirectory();
         if (isDirectory) {
             walkDir(dirPath, callback);
         } else if (f.endsWith('.md')) {
diff --git a/docs-src/src/components/performance-chart-impl.tsx b/docs-src/src/components/performance-chart-impl.tsx
index 3ce764c1edd..5e97c8dfa26 100644
--- a/docs-src/src/components/performance-chart-impl.tsx
+++ b/docs-src/src/components/performance-chart-impl.tsx
@@ -17,7 +17,7 @@ type PerformanceDataPoint = {
 
 type PerformanceChartImplProps = {
     data: PerformanceDataPoint[];
-    metrics: { key: string; name: string; color: string }[];
+    metrics: { key: string; name: string; color: string; }[];
     title?: string;
 };
 
diff --git a/docs-src/src/components/performance-chart.tsx b/docs-src/src/components/performance-chart.tsx
index 1bff9ab376c..5937daeafdc 100644
--- a/docs-src/src/components/performance-chart.tsx
+++ b/docs-src/src/components/performance-chart.tsx
@@ -1,6 +1,6 @@
 import React, { Suspense } from 'react';
 import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
-import { PERFORMANCE_METRICS, PERFORMANCE_DATA_BROWSER, PERFORMANCE_DATA_NODE } from './performance-data';
+// performance-data exports available: PERFORMANCE_METRICS, PERFORMANCE_DATA_BROWSER, PERFORMANCE_DATA_NODE
 
 // Lazy load the chart implementation so recharts isn't in the main bundle
 const PerformanceChartImpl = React.lazy(() => import('./performance-chart-impl'));
@@ -12,7 +12,7 @@ type PerformanceDataPoint = {
 
 type PerformanceChartProps = {
     data: PerformanceDataPoint[];
-    metrics?: { key: string; name: string; color: string }[];
+    metrics?: { key: string; name: string; color: string; }[];
     title?: string;
 };
 
diff --git a/docs-src/src/components/performance-node.tsx b/docs-src/src/components/performance-node.tsx
index 04b2b7252ef..4b03c3f8c3e 100644
--- a/docs-src/src/components/performance-node.tsx
+++ b/docs-src/src/components/performance-node.tsx
@@ -6,14 +6,14 @@ import { browserMetrics, PerformanceData } from './performance-browser';
 const nodeData: PerformanceData[] = [
     {
         name: 'MongoDB',
-        "time-to-first-insert": 276.906,
-        "insert-documents-500": 47.497,
-        "find-by-ids-3000": 57.31,
-        "serial-inserts-50": 209.467,
-        "serial-find-by-id-50": 23.09,
-        "find-by-query": 42.315,
-        "find-by-query-parallel-4": 38.854,
-        "4x-count": 6.898
+        'time-to-first-insert': 276.906,
+        'insert-documents-500': 47.497,
+        'find-by-ids-3000': 57.31,
+        'serial-inserts-50': 209.467,
+        'serial-find-by-id-50': 23.09,
+        'find-by-query': 42.315,
+        'find-by-query-parallel-4': 38.854,
+        '4x-count': 6.898
     },
     {
         name: 'Memory',
diff --git a/docs-src/update-colors.js b/docs-src/update-colors.js
index fb6e847669a..23994ae2d5a 100644
--- a/docs-src/update-colors.js
+++ b/docs-src/update-colors.js
@@ -3,8 +3,8 @@ const path = require('path');
 
 function walkDir(dir, callback) {
     fs.readdirSync(dir).forEach(f => {
-        let dirPath = path.join(dir, f);
-        let isDirectory = fs.statSync(dirPath).isDirectory();
+        const dirPath = path.join(dir, f);
+        const isDirectory = fs.statSync(dirPath).isDirectory();
         if (isDirectory) {
             walkDir(dirPath, callback);
         } else if (f.endsWith('.md')) {
diff --git a/test/unit/viewer.test.ts b/test/unit/viewer.test.ts
index 3aed65c1fd8..35e6128b5a5 100644
--- a/test/unit/viewer.test.ts
+++ b/test/unit/viewer.test.ts
@@ -8,13 +8,8 @@ import {
     startRxDBViewer,
     VIEWER_DEFAULT_SIGNALING_SERVER,
 } from '../../plugins/viewer/index.mjs';
-import type {
-    ViewerConnectionParams,
-    ViewerState
-} from '../../plugins/viewer/index.mjs';
 import config from './config.ts';
 import {
-    schemaObjects,
     schemas,
     isNode,
     isDeno