lowlander 0.2.0

package/client/client.ts

@@ -0,0 +1,495 @@
+import type { Socket, ServerProxy, StreamTypeBase } from '../server/server.js';
+import A from 'aberdeen';
+import DataPack from 'edinburgh/datapack';
+import { SERVER_MESSAGES, CLIENT_MESSAGES } from '../server/protocol.js';
+import type { PromiseProxy } from 'aberdeen';
+
+/** Set to 1-3 for increasing verbosity. */
+export let logLevel = 0;
+
+// Sentinel key in commitIds entries: on initial creation, only DEFAULT_COMMIT is set
+// (applies to all keys). Per-key entries are added on subsequent updates and take
+// precedence. On deletion, DEFAULT_COMMIT guards against stale re-creates.
+const DEFAULT_COMMIT = Symbol();
+
+/**
+ * Transforms server-side `Socket<T>` arguments to client-side callback functions `(data: T) => void`.
+ * 
+ * @typeParam A - The server-side argument type
+ */
+type ClientProxyArg<A> = A extends Socket<infer U>
+    ? (data: U) => void
+    : A;
+
+/**
+ * Recursively transforms all server-side function arguments for client-side use.
+ * 
+ * @typeParam Args - Tuple of server-side argument types
+ */
+type ClientProxyArgs<Args extends any[]> = Args extends [infer A, ...infer Rest]
+    ? [ClientProxyArg<A>, ...ClientProxyArgs<Rest>]
+    : [];
+
+/**
+ * Transforms server-side return types for client-side use.
+ * 
+ * - Strips `Promise` wrappers
+ * - `ServerProxy<API, RETURN>` → `PromiseProxy<RETURN> & {serverProxy: ClientProxyObject<API>}`
+ * - Other types → `PromiseProxy<R>`
+ * 
+ * @typeParam R - The server-side return type
+ */
+type ClientProxyReturn<R> = R extends Promise<infer U>
+    ? ClientProxyReturn<U>
+    : R extends ServerProxy<infer API, infer RETURN>
+        ? PromiseProxy<RETURN> & {promise: Promise<RETURN>, serverProxy: ClientProxyObject<API>}
+        : R extends StreamTypeBase<infer T>
+            ? PromiseProxy<T> & {promise: Promise<T>}
+            : PromiseProxy<R> & {promise: Promise<R>};
+
+/**
+ * Transforms server-side function signatures for client-side proxy use.
+ * This type correctly handles function overloads by explicitly matching
+ * up to 8 signatures and creating an intersection of the transformed types.
+ *
+ * @typeParam T - The server-side function type, which may be overloaded.
+ */
+// Yeah, this is ugly beyond belief, but TypeScript doesn't have a
+// better way to handle function overloads in conditional types.
+// The non-ugly version would be:
+//
+// type ClientProxyFunction<T> = T extends (...args: infer Args) => infer Return
+//  ? (...args: ClientProxyArgs<Args>) => ClientProxyReturn<Return>
+//    : never;
+type ClientProxyFunction<T> = T extends {
+    (...args: infer A1): infer R1;
+    (...args: infer A2): infer R2;
+    (...args: infer A3): infer R3;
+    (...args: infer A4): infer R4;
+    (...args: infer A5): infer R5;
+    (...args: infer A6): infer R6;
+    (...args: infer A7): infer R7;
+    (...args: infer A8): infer R8;
+} ?
+    & ((...args: ClientProxyArgs<A1>) => ClientProxyReturn<R1>)
+    & ((...args: ClientProxyArgs<A2>) => ClientProxyReturn<R2>)
+    & ((...args: ClientProxyArgs<A3>) => ClientProxyReturn<R3>)
+    & ((...args: ClientProxyArgs<A4>) => ClientProxyReturn<R4>)
+    & ((...args: ClientProxyArgs<A5>) => ClientProxyReturn<R5>)
+    & ((...args: ClientProxyArgs<A6>) => ClientProxyReturn<R6>)
+    & ((...args: ClientProxyArgs<A7>) => ClientProxyReturn<R7>)
+    & ((...args: ClientProxyArgs<A8>) => ClientProxyReturn<R8>)
+: T extends {
+    (...args: infer A1): infer R1;
+    (...args: infer A2): infer R2;
+    (...args: infer A3): infer R3;
+    (...args: infer A4): infer R4;
+    (...args: infer A5): infer R5;
+    (...args: infer A6): infer R6;
+    (...args: infer A7): infer R7;
+} ?
+    & ((...args: ClientProxyArgs<A1>) => ClientProxyReturn<R1>)
+    & ((...args: ClientProxyArgs<A2>) => ClientProxyReturn<R2>)
+    & ((...args: ClientProxyArgs<A3>) => ClientProxyReturn<R3>)
+    & ((...args: ClientProxyArgs<A4>) => ClientProxyReturn<R4>)
+    & ((...args: ClientProxyArgs<A5>) => ClientProxyReturn<R5>)
+    & ((...args: ClientProxyArgs<A6>) => ClientProxyReturn<R6>)
+    & ((...args: ClientProxyArgs<A7>) => ClientProxyReturn<R7>)
+: T extends {
+    (...args: infer A1): infer R1;
+    (...args: infer A2): infer R2;
+    (...args: infer A3): infer R3;
+    (...args: infer A4): infer R4;
+    (...args: infer A5): infer R5;
+    (...args: infer A6): infer R6;
+} ?
+    & ((...args: ClientProxyArgs<A1>) => ClientProxyReturn<R1>)
+    & ((...args: ClientProxyArgs<A2>) => ClientProxyReturn<R2>)
+    & ((...args: ClientProxyArgs<A3>) => ClientProxyReturn<R3>)
+    & ((...args: ClientProxyArgs<A4>) => ClientProxyReturn<R4>)
+    & ((...args: ClientProxyArgs<A5>) => ClientProxyReturn<R5>)
+    & ((...args: ClientProxyArgs<A6>) => ClientProxyReturn<R6>)
+: T extends {
+    (...args: infer A1): infer R1;
+    (...args: infer A2): infer R2;
+    (...args: infer A3): infer R3;
+    (...args: infer A4): infer R4;
+    (...args: infer A5): infer R5;
+} ?
+    & ((...args: ClientProxyArgs<A1>) => ClientProxyReturn<R1>)
+    & ((...args: ClientProxyArgs<A2>) => ClientProxyReturn<R2>)
+    & ((...args: ClientProxyArgs<A3>) => ClientProxyReturn<R3>)
+    & ((...args: ClientProxyArgs<A4>) => ClientProxyReturn<R4>)
+    & ((...args: ClientProxyArgs<A5>) => ClientProxyReturn<R5>)
+: T extends {
+    (...args: infer A1): infer R1;
+    (...args: infer A2): infer R2;
+    (...args: infer A3): infer R3;
+    (...args: infer A4): infer R4;
+} ?
+    & ((...args: ClientProxyArgs<A1>) => ClientProxyReturn<R1>)
+    & ((...args: ClientProxyArgs<A2>) => ClientProxyReturn<R2>)
+    & ((...args: ClientProxyArgs<A3>) => ClientProxyReturn<R3>)
+    & ((...args: ClientProxyArgs<A4>) => ClientProxyReturn<R4>)
+: T extends {
+    (...args: infer A1): infer R1;
+    (...args: infer A2): infer R2;
+    (...args: infer A3): infer R3;
+} ?
+    & ((...args: ClientProxyArgs<A1>) => ClientProxyReturn<R1>)
+    & ((...args: ClientProxyArgs<A2>) => ClientProxyReturn<R2>)
+    & ((...args: ClientProxyArgs<A3>) => ClientProxyReturn<R3>)
+: T extends {
+    (...args: infer A1): infer R1;
+    (...args: infer A2): infer R2;
+} ?
+    & ((...args: ClientProxyArgs<A1>) => ClientProxyReturn<R1>)
+    & ((...args: ClientProxyArgs<A2>) => ClientProxyReturn<R2>)
+: T extends (...args: infer A) => infer R
+    ? (...args: ClientProxyArgs<A>) => ClientProxyReturn<R>
+    : never;
+
+/**
+ * Transforms server-side API objects to client-side proxy objects with type-safe RPC methods.
+ * 
+ * @typeParam T - The server-side API object type
+ */
+export type ClientProxyObject<T> = {
+    [K in keyof T]: ClientProxyFunction<T[K]>
+};
+
+
+/**
+ * WebSocket connection to a Lowlander server with type-safe RPC, automatic reconnection,
+ * and reactive updates.
+ * 
+ * @typeParam T - The server-side API type (import from your server API file)
+ * 
+ * @example
+ * ```ts
+ * import type * as API from './server/api.js';
+ * const conn = new Connection<typeof API>('ws://localhost:8080/');
+ * 
+ * // Simple RPC - returns PromiseProxy
+ * const sum = conn.api.add(1, 2);
+ * 
+ * // Server proxy for stateful APIs
+ * const auth = conn.api.authenticate('token');
+ * const secret = auth.serverProxy.getSecret();
+ * 
+ * // Streaming with callbacks
+ * conn.api.streamData(data => console.log(data));
+ * 
+ * // Use within Aberdeen reactive scopes
+ * $(() => {
+ *   dump(conn.isOnline());
+ *   dump(sum);
+ * });
+ * ```
+ */
+export class Connection<T> {
+    
+    private ws?: WebSocket;
+    private activeRequests = new Map<number, ActiveRequest>();
+    private requestCounter = 0;
+    private reconnectAttempts = 0;
+    /** @internal */
+    public _proxyCounter = 0;
+    private onlineProxy = A.proxy(false);
+
+    /**
+     * Type-safe proxy to the server-side API. Methods return `PromiseProxy` objects
+     * that work reactively in Aberdeen scopes. `ServerProxy` returns include a
+     * `.serverProxy` property for accessing stateful server APIs.
+     */
+    public api: ClientProxyObject<T>;
+
+    /**
+     * @param url - WebSocket URL (e.g., 'ws://localhost:8080/'), or a fake WebSocket object for testing
+     */
+    constructor(public url: string | (() => WebSocket)) {
+        this.api = new Proxy({connection: this, requestId: undefined} as ProxyTargetType, proxyHandlers);
+        this.connect();
+    }
+
+    /**
+     * Returns the current connection status. Reactive in Aberdeen scopes.
+     */
+    isOnline(): boolean { return this.onlineProxy.value; }
+
+    private connect() {
+        const ws: WebSocket = this.ws = typeof this.url === 'string'
+            ? new WebSocket(this.url)
+            : this.url();
+        ws.binaryType = "arraybuffer";
+        if (logLevel >= 1) console.log(`[lowlander] Connecting to WebSocket at ${typeof this.url === 'string' ? this.url : '[custom WebSocket]'}`);
+ 
+        ws.onopen = () => {
+            if (ws !== this.ws) return; // No longer the current connection
+            if (logLevel >= 1) console.log('[lowlander] WebSocket connected');
+            this.onlineProxy.value = true;
+            this.reconnectAttempts = 0;
+            for(const request of this.activeRequests.values()) {
+                request.resultProxy.busy = true;
+                this.ws!.send(request.requestBuffer);
+            }
+        };
+        
+        ws.onclose = () => {
+            if (ws !== this.ws) return; // No longer the current connection
+            if (logLevel >= 1) console.log('[lowlander] WebSocket disconnected');
+            this.reconnect();
+        };
+        
+        ws.onerror = (error: any) => {
+            if (ws !== this.ws) return; // No longer the current connection
+            console.error('WebSocket error:', error);
+            this.reconnect();
+        };
+        
+        ws.onmessage = (event: any) => {
+            if (ws !== this.ws) return; // No longer the current connection
+            const pack = new DataPack(new Uint8Array(event.data));
+            // console.log(`onmessage: ${pack}`);
+            const requestId = pack.readPositiveInt();
+
+            const request = this.activeRequests.get(requestId);
+            if (!request) return; // Raced
+            const result = A.unproxy(request.resultProxy);
+
+            const type = pack.read();
+            if (typeof type === 'number') {
+                // It's a callback invocation
+                const callback = request.callbacks?.[type];
+                const args: any[] = [];
+                while(pack.readAvailable()) {
+                    args.push(pack.read());
+                }
+                callback!(...args);
+                return;
+            }
+
+            // This packet type does not represent the result for a request
+            if (type === SERVER_MESSAGES.model_data) {
+                request.database ||= new Map();
+                request.commitIds ||= new Map();
+                const dbKeyHash = pack.readNumber();
+                const commitId = pack.readNumber();
+                const delta = pack.read({model: function(linkHash: number) {
+                    const linkedModel = request.database!.get(linkHash);
+                    if (!linkedModel) console.error('Unknown linked model hash ' + linkHash);
+                    return linkedModel;
+                }});
+                if (logLevel >= 3) console.log('[lowlander] incoming model_data', requestId, dbKeyHash, commitId, delta);
+                // Schedule cleanup: after 15s, all out-of-order messages for this commitId
+                // must have arrived, so we can prune tracking entries at or below it.
+                setTimeout(() => this.pruneCommitIds(request, commitId), 15000);
+                let prevCommitIds = request.commitIds.get(dbKeyHash);
+                if (!delta) {
+                    // Stale delete: some key was already updated past this commitId
+                    if (prevCommitIds && commitId < Math.max(...prevCommitIds.values())) return;
+                    request.database.delete(dbKeyHash);
+                    // Record delete's commitId so stale creates arriving later are rejected
+                    request.commitIds.set(dbKeyHash, new Map([[DEFAULT_COMMIT, commitId]]));
+                    return;
+                }
+                let org = request.database.get(dbKeyHash);
+                if (org) {
+                    // Update existing object
+                    if (!prevCommitIds) {
+                        prevCommitIds = new Map();
+                        request.commitIds.set(dbKeyHash, prevCommitIds);
+                    }
+                    for (const key of Object.keys(delta)) {
+                        if (commitId < (prevCommitIds.get(key) ?? prevCommitIds.get(DEFAULT_COMMIT) ?? -1)) continue;
+                        if (delta[key] && typeof delta[key] === 'object') {
+                            A.copy(org, key, delta[key]);
+                        } else {
+                            org[key] = delta[key];
+                        }
+                        prevCommitIds.set(key, commitId);
+                    }
+                } else {
+                    // Create new object
+                    if (prevCommitIds && commitId < (prevCommitIds.get(DEFAULT_COMMIT) ?? -1)) return; // Stale create
+                    request.database.set(dbKeyHash, A.proxy(delta));
+                    request.commitIds.set(dbKeyHash, new Map([[DEFAULT_COMMIT, commitId]]));
+                }
+                return;
+            }
+
+            // Each request should get one of these packet types as a response
+            if (type === SERVER_MESSAGES.error) {
+                const errorMessage = pack.readString();
+                request.resultProxy.error = new Error(errorMessage);
+                if (logLevel >= 2) console.log(`[lowlander] incoming error requestId=${requestId} message=${errorMessage}`);
+
+            } else if (type === SERVER_MESSAGES.response || type === SERVER_MESSAGES.response_proxy) {
+                request.resultProxy.value = pack.read();
+                request.virtualSocketIds = pack.read() as number[] | undefined;
+                request.hasServerProxy = type === SERVER_MESSAGES.response_proxy;
+                if (logLevel >= 2) console.log(`[lowlander] incoming response requestId=${requestId} value=${result.value} virtualSocketIds=${request.virtualSocketIds} hasServerProxy=${request.hasServerProxy}`);
+
+            } else if (type === SERVER_MESSAGES.response_model) {
+                request.virtualSocketIds = pack.read() as number[]; // There must be at least one, for the model stream
+                const dbKey = pack.readNumber();
+                const obj = request.database?.get(dbKey);
+                if (logLevel >= 2) console.log(`[lowlander] incoming response_model requestId=${requestId} dbKey=${dbKey} obj=${obj}`);
+                if (obj) {
+                    request.resultProxy.value = A.proxy(obj);
+                } else {
+                    request.resultProxy.error = new Error('Unknown database key ' + dbKey);
+                }
+
+            } else {
+                throw new Error('Unknown message type ' + type);
+            }
+
+            // Common cleanup for all response types
+
+            if (!request.hasServerProxy && !request.virtualSocketIds?.length) {
+                this.activeRequests.delete(requestId);
+            }
+
+            if (!request.hasServerProxy) {
+                delete (request.resultProxy as any).serverProxy;
+            }
+
+            request.resultProxy.busy = false;
+
+            if (request.resolve) {
+                // This does not happen on reconnect
+                if (result.error != null) {
+                    console.error(result.error);
+                    request.reject!(result.error);
+                } else {
+                    request.resolve(result.value);
+                }
+                delete request.resolve;
+                delete request.reject;
+            }
+        };
+    }
+
+    private reconnect() {
+        this.ws = undefined;
+
+        this.onlineProxy.value = false;
+
+        if (typeof this.url !== 'string') return; // No reconnect in test mode
+
+        // Reconnect with exponential backoff
+        const delay = Math.min(500 * Math.pow(2, this.reconnectAttempts), 20000);
+        this.reconnectAttempts++;
+        if (logLevel >= 1) console.log(`[lowlander] Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts})`);
+        setTimeout(this.connect.bind(this), delay);
+    }
+
+    private pruneCommitIds(request: ActiveRequest, maxCommitId: number) {
+        if (!request.commitIds) return;
+        for (const [hash, entry] of request.commitIds) {
+            for (const [key, cid] of entry) {
+                if (cid <= maxCommitId) entry.delete(key);
+            }
+            if (!entry.size) request.commitIds.delete(hash);
+        }
+    }
+
+    /** @internal */
+    public _createMethodStub(methodName: string, proxyId?: number) {
+        return (...params: any[]) => {
+            const result = {busy: true} as PromiseProxy<any> & {promise: Promise<any>} & {serverProxy: any};
+            const resultProxy = A.proxy(result);
+
+            const requestId = ++this.requestCounter;
+
+            const pack = new DataPack();
+            pack.write(requestId).write(CLIENT_MESSAGES.call).write(proxyId).write(methodName);
+
+            let callbacks;
+            pack.writeCollection("array", () => {
+                for(const param of params) {
+                    if (typeof param === 'function') {
+                        callbacks ||= [];
+                        pack.writeCustom('cb', callbacks.length);
+                        callbacks.push(param);
+                    } else {
+                        pack.write(param);
+                    }
+                }
+            });
+
+            const request: ActiveRequest = { resultProxy, requestBuffer: pack.toUint8Array(true), requestId, connection: this, callbacks };
+            result.serverProxy = new Proxy(request, proxyHandlers);
+            result.promise = new Promise((resolve, reject) => {
+                request.resolve = resolve;
+                request.reject = reject;
+            });
+
+            this.activeRequests.set(requestId, request);
+
+            if (logLevel >= 2) console.log(`[lowlander] outgoing call requestId=${requestId} method=${methodName} params=`, params);
+
+            if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+                this.ws.send(request.requestBuffer);
+            }
+
+            A.clean(() => {
+                this.activeRequests.delete(requestId);
+                if (request.virtualSocketIds?.length || request.hasServerProxy) {
+                    if (logLevel >= 2) console.log(`[lowlander] outgoing cancel requestId=${request.requestId} virtualSocketIds=${request.virtualSocketIds} hasServerProxy=${request.hasServerProxy}`);
+                    const data = DataPack.createUint8Array(
+                        ++this.requestCounter,
+                        CLIENT_MESSAGES.cancel,
+                        request.requestId,
+                        request.virtualSocketIds,
+                    );
+                    this.ws?.send(data);
+                }
+            });
+
+            return resultProxy;
+        }
+    }
+}
+
+const proxyHandlers: ProxyHandler<any> = {
+    get(target: ProxyTargetType, prop: string) {
+        if (target.serverProxyCache?.has(prop)) {
+            return target.serverProxyCache.get(prop);
+        }
+        if (prop === 'then' || prop === 'catch' || prop === 'finally') {
+            // When someone awaits the proxy, we should not treat it as a remote method call
+            return undefined;
+        }
+        if (prop === 'constructor') {
+            return {name: 'ServerProxy-' + target.requestId};
+        }
+        const result = target.connection._createMethodStub(prop, target.requestId);
+        if (!target.serverProxyCache) target.serverProxyCache = new Map();
+        target.serverProxyCache.set(prop, result);
+        return result;
+    },
+    has(_target: ProxyTargetType, prop: string | symbol) {
+        return typeof prop === 'string' || prop === A.NO_COPY;
+    }
+}
+
+interface ProxyTargetType {
+    connection: Connection<any>;
+    requestId: number | undefined;
+    serverProxyCache?: Map<string, () => PromiseProxy<any>>;
+}
+
+interface ActiveRequest extends ProxyTargetType {
+    resultProxy: PromiseProxy<any>;
+    callbacks?: ((...args: any[]) => void)[];
+    virtualSocketIds?: number[];
+    database?: Map<number, Record<any,any>>; // For model streams
+    commitIds?: Map<number, Map<string | symbol, number>>; // dbKeyHash -> (key|DEFAULT_COMMIT) -> commitId
+    requestBuffer: Uint8Array;
+    requestId: number; // Client-generated unique ID for this request
+    hasServerProxy?: boolean; // When true, the requestId has an object associated on the server side (which needs to be dropped on 'clean')
+    resolve?: (value: any) => void;
+    reject?: (error: any) => void;
+}

package/examples/helloworld/client/assets/style.css

@@ -0,0 +1,45 @@
+html,
+body {
+    box-sizing: border-box;
+}
+body {
+    background-color: #0a0f0a;
+    background-image: 
+    linear-gradient(rgba(0, 120, 0, 0.1) 1px, transparent 1px),
+    linear-gradient(90deg, rgba(0, 120, 0, 0.1) 1px, transparent 1px);
+    background-size: 20px 20px;
+    color: #00ff00;
+    font-family: 'Courier New', Courier, monospace;
+    min-height: 100vh;
+    padding: 20px;
+}
+h2 {
+    border-bottom: 1px solid rgba(0, 255, 0, 0.3);
+    padding-bottom: 5px;
+    margin-top: 25px;
+}
+ul {
+    list-style-type: none;
+    padding-left: 20px;
+}
+input, button {
+    border: 1px solid #00ff00;
+    padding: 8px 12px;
+    color: #00ff00;
+    font-family: inherit;
+    background-color: rgba(0, 255, 0, 0.1);
+}
+input:focus, button:hover {
+    outline: none;
+}
+button {
+    cursor: pointer;
+    background-color: green;
+    color: white;
+}
+
+.busy {
+    cursor: default;
+    pointer-events: none;
+    opacity: 0.6;
+}

package/examples/helloworld/client/index.html

@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="en" dir="ltr" class="mdui-theme-dark">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Lowlander Hello World Example</title>
+    <meta
+      name="viewport"
+      content="viewport-fit=cover, width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no"
+    />
+    <meta name="format-detection" content="telephone=no" />
+    <meta name="msapplication-tap-highlight" content="no" />
+    <meta name="theme-color" content="#31d53d" />
+    <link
+      href="https://fonts.googleapis.com/icon?family=Material+Icons"
+      rel="stylesheet"
+    />
+  </head>
+  <body>
+    <script src="./js/base.ts" type="module"></script>
+  </body>
+  
+</html>

package/examples/helloworld/client/js/admin.ts

@@ -0,0 +1,94 @@
+import 'mdui/mdui.css';
+import 'mdui/components/button.js';
+import 'mdui/components/dialog.js';
+import 'mdui/components/tabs.js';
+import 'mdui/components/tab.js';
+import 'mdui/components/tab-panel.js';
+import type { Dialog } from 'mdui/components/dialog.js';
+
+import A from "aberdeen";
+import { ClientProxyObject } from 'lowlander/client';
+import type * as ServerAPI from '../../server/api.js';
+type API = ClientProxyObject<typeof ServerAPI>;
+
+const TOPICS = ['sockets', 'channels', 'workers', 'kv'] as const;
+
+function formatDecodedBytes(value: Uint8Array) {
+    let text = '';
+    for (const byte of value) {
+        const codePoint = byte;
+        const char = String.fromCodePoint(codePoint);
+        const printableAscii = codePoint >= 0x20 && codePoint <= 0x7e;
+        const whitespace = codePoint === 0x09 || codePoint === 0x0a || codePoint === 0x0d;
+        text += printableAscii || whitespace ? char : `<${codePoint}>`;
+    }
+    return text;
+}
+
+const tableStyle = A.insertCss({
+    '&': 'border-collapse:collapse text-align:left box-shadow: 0 0 20px rgba(0, 0, 0, 0.15);',
+    'tr:nth-child(even)': 'background-color:#0002;',
+    'td,th': 'padding: $1 $2; border-left: 1px solid #0002;',
+    'td:first-child,th:first-child': 'border-left:none',
+})
+
+export function showAdminModal(api: API) {
+
+    const refreshes = A.proxy(0);
+    const closed = A.proxy(false);
+    A.mount(document.body, () => {
+        if (A.peek(closed, 'value') || closed.value) return;
+        A('mdui-dialog open= close-on-overlay-click= close-on-esc= headline="Lowlander Admin panel" closed=', () => closed.value = true, () => {
+            A('span slot=description mdui-tabs value=', TOPICS[0], () => {
+                for(const topic of TOPICS) {
+                    A('mdui-tab value=',topic, 'text=',topic);
+                }
+
+                for(const topic of TOPICS) {
+                    A('mdui-tab-panel slot=panel value=', topic, () => {
+                        const sockets = api.getDebugState(topic as any);
+                        refreshes.value;
+                        A(() => {
+                                const data = A.unproxy(sockets.value) as undefined | Record<string, Record<string, any>> | Record<string, any>[];
+                                if (!data) return;
+                                const keySet = new Set<string>();
+                                for (const [, obj] of Object.entries(data)) {
+                                    if (obj && typeof obj === 'object' && !(obj instanceof Uint8Array))
+                                        for (const k of Object.keys(obj)) keySet.add(k);
+                                }
+                                const cols = [...keySet];
+                                A('table', tableStyle, () => {
+                                    A('tr', () => {
+                                        A('th text=#');
+                                        for (const k of cols) A('th text=', k);
+                                    });
+                                    for (const [idx, obj] of Object.entries(data)) {
+                                        A('tr', () => {
+                                            A('td text=', idx);
+                                            for (const k of cols) {
+                                                const value = obj?.[k];
+                                                let text = '';
+                                                if (value instanceof Uint8Array) {
+                                                    text = formatDecodedBytes(value);
+                                                }
+                                                else if (value !== null && value !== undefined) {
+                                                    text = typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
+                                                        ? String(value)
+                                                        : JSON.stringify(value);
+                                                }
+                                                A('td text=', text);
+                                            }
+                                        });
+                                    }
+                                });
+                            });
+                    });
+                }
+            });
+
+            const dialog = A() as Dialog;
+            A('mdui-button slot=action variant=text text=Update click=', () => refreshes.value++);
+            A('mdui-button slot=action variant=text text=Close click=', () => dialog.open = false);
+        })
+    })
+}