@omochi-ui/cli 0.0.0-stage → 0.1.1

package/dist/hub/hub.js

@@ -0,0 +1,353 @@
+import { DashboardStore, dashboardEndpoints, presetEndpoints } from './dashboards.js';
+import { serveHubUi } from './static-ui.js';
+import process from 'node:process';
+import { A2uiSnapshot, FanOut, closeSocket, createServicesEndpoints, joinRouteId, parseClientFrame, prefixClientMessage, readdressServerMessage, routeClientMessage, splitRouteId, startWsEndpoint, webSocketClient, } from '@omochi-ui/core';
+import { connectGateway, createLocalLocator, createMdnsLocator, gatewaySocketPath, loadNodeIdentity, omochiRuntimeRoot, openTrustStore, mtlsClientOptions, } from '@omochi-ui/discovery';
+import { superviseLocalGateway } from './gateway-supervisor.js';
+const RECONNECT_MIN_MS = 100;
+const RECONNECT_MAX_MS = 5000;
+function surfaceIdsOf(snapshot) {
+    const ids = [];
+    for (const message of snapshot.messages()) {
+        if ('createSurface' in message)
+            ids.push(message.createSurface.surfaceId);
+    }
+    return ids;
+}
+/**
+ * Aggregates every reachable gateway into one A2UI stream.
+ *
+ * The hub knows nothing about manifests, runtime directories, or application sockets:
+ * a gateway owns all of that, and the hub only ever speaks the gateway contract. That is
+ * what lets a gateway on another machine join on exactly the same terms as the local one.
+ *
+ * Surfaces arrive namespaced by service id and are re-namespaced as
+ * `<nodeId>~<serviceId>/<surfaceId>`, so two machines running the same service stay
+ * distinct all the way out to the renderer.
+ */
+export async function startHub(options = {}) {
+    const host = options.host ?? '127.0.0.1';
+    const port = options.port ?? 5555;
+    const gatewaySocket = options.gatewaySocket ?? gatewaySocketPath(omochiRuntimeRoot());
+    const locators = [...(options.gateways ?? [createLocalLocator(gatewaySocket)])];
+    const nodes = new Map();
+    const byNodeId = new Map();
+    let supervisor = null;
+    let closed = false;
+    // Only a remote gateway needs either of these, so neither is created until one appears.
+    let identity = options.identity ?? null;
+    let trust = options.trust ?? null;
+    const trustSubscription = { close: null };
+    let subscribingTrust = null;
+    const remoteCredentials = async () => {
+        identity ??= await loadNodeIdentity({ root: options.configRoot });
+        trust ??= await openTrustStore(options.configRoot);
+        subscribingTrust ??= trust.subscribe(() => {
+            for (const node of nodes.values()) {
+                if (node.candidate.endpoint.kind !== 'tcp')
+                    continue;
+                // Re-authorize on every trust change, including replacement of a certificate.
+                if (node.retry)
+                    clearTimeout(node.retry);
+                node.retry = null;
+                node.authorization += 1;
+                const client = node.client;
+                node.client = null;
+                client?.close();
+                retractSurfaces(node);
+                node.status = 'disconnected';
+                node.services = [];
+                if (trust.get(node.candidate.nodeId ?? '')?.role === 'gateway')
+                    scheduleReconnect(node);
+            }
+            publish();
+        }).then(unsubscribe => { trustSubscription.close = unsubscribe; });
+        await subscribingTrust;
+        return { identity, trust };
+    };
+    const fanOut = new FanOut(function* () {
+        for (const node of nodes.values()) {
+            for (const message of node.snapshot.messages())
+                yield message;
+        }
+    });
+    const listServices = () => {
+        const rows = [];
+        for (const node of nodes.values()) {
+            if (node.nodeId === null)
+                continue;
+            const nodeView = {
+                id: node.nodeId,
+                name: node.nodeName ?? node.nodeId,
+                local: node.candidate.source === 'local',
+            };
+            for (const service of node.services) {
+                // A gateway that is down takes its whole list down with it, so the reason the
+                // node dropped is what the renderer shows rather than a stale per-service one.
+                const view = {
+                    id: joinRouteId(node.nodeId, service.id),
+                    name: service.name,
+                    status: node.status === 'connected' ? service.status : node.status,
+                    node: nodeView,
+                };
+                if (service.icon !== undefined)
+                    view.icon = service.icon;
+                const detail = node.status === 'connected' ? service.detail : node.detail;
+                if (detail !== undefined)
+                    view.detail = detail;
+                rows.push(view);
+            }
+        }
+        return rows;
+    };
+    const endpoints = createServicesEndpoints({ allowOrigins: options.allowOrigins, list: listServices });
+    const dashboards = dashboardEndpoints(new DashboardStore(options.configRoot), endpoints.isAllowedOrigin);
+    const presets = presetEndpoints(options.presets ?? [], endpoints.isAllowedOrigin);
+    const publish = () => endpoints.publish(listServices());
+    /** Retracts a node's surfaces so no renderer keeps a zombie surface around. */
+    const retractSurfaces = (node) => {
+        for (const surfaceId of surfaceIdsOf(node.snapshot)) {
+            fanOut.broadcast(JSON.stringify({ version: 'v0.9', deleteSurface: { surfaceId } }));
+        }
+        node.snapshot = new A2uiSnapshot();
+    };
+    const scheduleReconnect = (node) => {
+        if (closed || !nodes.has(node.candidate.key))
+            return;
+        const delay = Math.min(RECONNECT_MAX_MS, RECONNECT_MIN_MS * 2 ** node.attempt);
+        node.attempt += 1;
+        node.retry = setTimeout(() => {
+            node.retry = null;
+            connect(node);
+        }, delay + Math.random() * delay);
+        node.retry.unref();
+    };
+    const dropConnection = (node, status, detail) => {
+        const client = node.client;
+        if (!client)
+            return;
+        // Clearing the slot first makes the client's own close callback a no-op, so the
+        // reason recorded here survives instead of being overwritten by the teardown.
+        node.client = null;
+        client.close();
+        retractSurfaces(node);
+        node.status = status;
+        node.detail = detail;
+        publish();
+        scheduleReconnect(node);
+    };
+    /**
+     * Resolves the certificate pin that authenticates one remote gateway.
+     *
+     * The hub must know which node it is calling to select its certificate pin
+     * before it connects. An unpaired peer is reported and left alone rather than reached
+     * for without authentication.
+     */
+    const remoteTls = async (node) => {
+        const { identity: self, trust: store } = await remoteCredentials();
+        const expected = node.candidate.nodeId ?? null;
+        if (expected === null) {
+            throw new Error('name the node to reach it, as --gateway <nodeId>@host:port');
+        }
+        const peer = store.get(expected);
+        if (!peer)
+            throw new Error(`not paired with ${expected}; pair with it first`);
+        if (peer.role !== 'gateway')
+            throw new Error(`${expected} is paired as a ${peer.role}, not a gateway`);
+        return mtlsClientOptions(self, peer);
+    };
+    const attach = (node, tls) => {
+        if (closed)
+            return;
+        node.client = connectGateway(node.candidate.endpoint, {
+            onOpen(info) {
+                node.attempt = 0;
+                node.nodeId = info.nodeId;
+                node.nodeName = info.name;
+                node.status = 'connected';
+                delete node.detail;
+                byNodeId.set(info.nodeId, node);
+                publish();
+            },
+            onServices(services) {
+                node.services = services;
+                publish();
+            },
+            onMessage(message) {
+                if (node.nodeId === null)
+                    return;
+                const readdressed = readdressServerMessage(node.nodeId, message);
+                if (readdressed === null) {
+                    const detail = 'the gateway sent a surface id it had not namespaced';
+                    process.stderr.write(`[omochi-ui] node ${node.nodeId}: ${detail}\n`);
+                    dropConnection(node, 'error', detail);
+                    return;
+                }
+                try {
+                    node.snapshot.apply(readdressed);
+                }
+                catch (error) {
+                    const detail = error instanceof Error ? error.message : String(error);
+                    process.stderr.write(`[omochi-ui] node ${node.nodeId}: invalid A2UI message: ${detail}\n`);
+                    dropConnection(node, 'error', detail);
+                    return;
+                }
+                fanOut.broadcast(JSON.stringify(readdressed));
+            },
+            onClose(detail) {
+                dropConnection(node, 'disconnected', detail);
+            },
+        }, tls ? { tls, expectedNodeId: node.candidate.nodeId } : {});
+    };
+    const connect = (node) => {
+        if (closed)
+            return;
+        if (node.candidate.endpoint.kind === 'unix') {
+            attach(node);
+            return;
+        }
+        const authorization = node.authorization;
+        void remoteTls(node).then((tls) => {
+            if (authorization !== node.authorization || closed || !nodes.has(node.candidate.key))
+                return;
+            const peer = trust?.get(node.candidate.nodeId ?? '');
+            if (!peer || peer.role !== 'gateway' || peer.certificate !== tls.ca?.[0])
+                return;
+            attach(node, tls);
+        }, (error) => {
+            if (closed || authorization !== node.authorization || !nodes.has(node.candidate.key))
+                return;
+            node.status = 'error';
+            node.detail = error.message;
+            process.stderr.write(`[omochi-ui] ${node.candidate.key}: ${error.message}\n`);
+            publish();
+            if (trust?.get(node.candidate.nodeId ?? '')?.role === 'gateway')
+                scheduleReconnect(node);
+        });
+    };
+    const teardown = (node) => {
+        if (node.retry)
+            clearTimeout(node.retry);
+        node.retry = null;
+        node.authorization += 1;
+        const client = node.client;
+        node.client = null;
+        client?.close();
+        retractSurfaces(node);
+        if (node.nodeId !== null && byNodeId.get(node.nodeId) === node)
+            byNodeId.delete(node.nodeId);
+    };
+    const sink = {
+        found(candidate) {
+            if (closed || nodes.has(candidate.key))
+                return;
+            const node = {
+                candidate,
+                client: null,
+                nodeId: null,
+                nodeName: null,
+                snapshot: new A2uiSnapshot(),
+                services: [],
+                status: 'disconnected',
+                attempt: 0,
+                retry: null,
+                authorization: 0,
+            };
+            nodes.set(candidate.key, node);
+            connect(node);
+        },
+        lost(key) {
+            const node = nodes.get(key);
+            if (!node)
+                return;
+            teardown(node);
+            nodes.delete(key);
+            publish();
+        },
+    };
+    if (options.autoGateway !== false)
+        supervisor = await superviseLocalGateway(gatewaySocket);
+    if (options.discoverLan) {
+        // Knowing our own id keeps this machine's gateway from arriving twice: once through
+        // its unix socket, and once over the network as if it were somebody else.
+        const { identity: self } = await remoteCredentials();
+        locators.push(createMdnsLocator({ selfNodeId: self.nodeId }));
+    }
+    for (const locator of locators)
+        await locator.start(sink);
+    let endpoint;
+    try {
+        endpoint = await startWsEndpoint({
+            host,
+            port,
+            onRequest: (request, response) => {
+                if (!endpoints.isAllowedOrigin(request.headers.origin)) {
+                    response.writeHead(403).end('Forbidden origin');
+                    return true;
+                }
+                return endpoints.handleRequest(request, response) || dashboards(request, response) || presets(request, response) || serveHubUi(request, response);
+            },
+            // WebSocket upgrades are exempt from CORS, so any page the user has open could
+            // otherwise drive every discovered service. Restrict them the same way.
+            onUpgrade: (request) => endpoints.isAllowedOrigin(request.headers.origin)
+                ? { ok: true }
+                : { ok: false, status: 403, reason: 'Forbidden' },
+        });
+    }
+    catch (error) {
+        await trustSubscription.close?.();
+        endpoints.close();
+        for (const locator of locators)
+            await locator.close();
+        await supervisor?.close();
+        throw error;
+    }
+    endpoint.onConnection((socket) => {
+        const client = webSocketClient(socket);
+        fanOut.add(client);
+        socket.on('message', (data, isBinary) => {
+            const frame = parseClientFrame(data, isBinary);
+            if (!frame.ok) {
+                closeSocket(socket, frame.code, frame.reason);
+                return;
+            }
+            const routed = routeClientMessage(frame.value);
+            const route = routed ? splitRouteId(routed.channelId) : null;
+            if (!routed || !route) {
+                process.stderr.write('[omochi-ui] dropped a client message with no routable surface id\n');
+                return;
+            }
+            const node = byNodeId.get(route.nodeId);
+            if (!node?.client) {
+                process.stderr.write(`[omochi-ui] dropped a client message for unavailable node ${route.nodeId}\n`);
+                return;
+            }
+            // The gateway namespaces by bare service id, so hand it what a renderer attached
+            // straight to it would have sent.
+            node.client.send(prefixClientMessage(route.serviceId, routed.message));
+        });
+        socket.on('close', () => fanOut.remove(client));
+    });
+    return {
+        url: endpoint.url,
+        httpUrl: endpoint.httpUrl,
+        get nodeCount() {
+            return [...nodes.values()].filter((node) => node.status === 'connected').length;
+        },
+        async close() {
+            closed = true;
+            await subscribingTrust?.catch(() => { });
+            for (const node of nodes.values())
+                teardown(node);
+            await trustSubscription.close?.();
+            for (const locator of locators)
+                await locator.close();
+            nodes.clear();
+            byNodeId.clear();
+            fanOut.closeAll(1001, 'hub shutting down');
+            endpoints.close();
+            await endpoint.close();
+            await supervisor?.close();
+        },
+    };
+}

package/dist/hub/ssh-gateway.d.ts

@@ -0,0 +1,16 @@
+export declare function validateSshTarget(host: string, socket?: string): void;
+export interface SshGateway {
+    readonly socketPath: string;
+    /** Resolves even if SSH exits before the caller starts watching it. */
+    readonly exited: Promise<Error>;
+    close(): Promise<void>;
+}
+export interface SshGatewayOptions {
+    host: string;
+    remoteSocket?: string;
+    signal?: AbortSignal;
+    /** Injectable executable for tests. */
+    command?: string[];
+    startTimeoutMs?: number;
+}
+export declare function startSshGateway(options: SshGatewayOptions): Promise<SshGateway>;

package/dist/hub/ssh-gateway.js

@@ -0,0 +1,110 @@
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { probeGateway } from '@omochi-ui/discovery';
+// Fixed shell program: no user input is interpolated into a remote command.
+const RESOLVE_SOCKET = 'if [ -n "$XDG_RUNTIME_DIR" ]; then printf "%s/omochi/gateway.sock\\n" "${XDG_RUNTIME_DIR%/}"; else printf "%s/omochi-%s/omochi/gateway.sock\\n" "${TMPDIR:-${TMP:-${TEMP:-/tmp}}}" "$(id -u)"; fi';
+export function validateSshTarget(host, socket) {
+    if (!host || host.startsWith('-') || /[\s\x00-\x1f\x7f]/.test(host)) {
+        throw new Error('SSH target must be a host alias or user@host, not SSH options');
+    }
+    if (socket !== undefined && (!socket.startsWith('/') || /[:\x00-\x1f\x7f]/.test(socket))) {
+        throw new Error('SSH socket must be an absolute path without colons or control characters');
+    }
+}
+export async function startSshGateway(options) {
+    validateSshTarget(options.host, options.remoteSocket);
+    options.signal?.throwIfAborted();
+    const directory = await mkdtemp(path.join(tmpdir(), 'omochi-ssh-'));
+    const socketPath = path.join(directory, 'gateway.sock');
+    const command = options.command ?? ['ssh'];
+    let child;
+    let finished = Promise.resolve(new Error('SSH not started'));
+    let failure;
+    let closing;
+    const close = () => closing ??= (async () => {
+        options.signal?.removeEventListener('abort', abort);
+        if (child && child.exitCode === null && child.signalCode === null) {
+            child.kill('SIGTERM');
+            const timer = setTimeout(() => child?.kill('SIGKILL'), 1000);
+            await finished;
+            clearTimeout(timer);
+        }
+        await rm(directory, { recursive: true, force: true });
+    })();
+    const abort = () => { void close(); };
+    options.signal?.addEventListener('abort', abort, { once: true });
+    const launch = (args, capture) => {
+        options.signal?.throwIfAborted();
+        failure = undefined;
+        child = spawn(command[0], [...command.slice(1), ...args], {
+            stdio: ['inherit', capture ? 'pipe' : 'ignore', 'inherit'],
+        });
+        finished = new Promise((resolve) => {
+            child.once('error', (error) => { failure = error; resolve(error); });
+            child.once('close', (code, signal) => {
+                const error = new Error(`SSH to ${options.host} exited (${signal ?? code})`);
+                failure = error;
+                resolve(error);
+            });
+        });
+        return child;
+    };
+    try {
+        let remoteSocket = options.remoteSocket;
+        if (remoteSocket === undefined) {
+            const resolver = launch(['-T', '-o', 'ControlMaster=no', options.host, `sh -c '${RESOLVE_SOCKET}'`], true);
+            let output = '';
+            resolver.stdout.setEncoding('utf8').on('data', (data) => {
+                output += data;
+                if (output.length > 16384)
+                    resolver.kill('SIGTERM');
+            });
+            const error = await finished;
+            options.signal?.throwIfAborted();
+            if (resolver.exitCode !== 0)
+                throw error;
+            remoteSocket = output.trimEnd();
+            validateSshTarget(options.host, remoteSocket);
+        }
+        launch([
+            '-N', '-T', '-o', 'ControlMaster=no', '-o', 'ControlPath=none',
+            '-o', 'ExitOnForwardFailure=yes', '-o', 'ServerAliveInterval=15',
+            '-o', 'ServerAliveCountMax=3', '-L', `${socketPath}:${remoteSocket}`, options.host,
+        ], false);
+        // OpenSSH creates the listener after authentication; do not time out a prompt.
+        while (!(await stat(socketPath).catch(() => null))?.isSocket()) {
+            options.signal?.throwIfAborted();
+            if (failure)
+                throw failure;
+            await delay(50);
+        }
+        const deadline = Date.now() + (options.startTimeoutMs ?? 10000);
+        while (true) {
+            options.signal?.throwIfAborted();
+            if (failure)
+                throw failure;
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                throw new Error(`gateway at ${options.host}:${remoteSocket} did not answer within the connection timeout`);
+            let timer;
+            const ready = await Promise.race([
+                probeGateway({ kind: 'unix', socketPath }),
+                new Promise((resolve) => { timer = setTimeout(() => resolve(null), remaining); }),
+            ]).finally(() => clearTimeout(timer));
+            if (ready)
+                break;
+            await delay(50);
+        }
+        options.signal?.throwIfAborted();
+        if (failure)
+            throw failure;
+        return { socketPath, exited: finished, close };
+    }
+    catch (error) {
+        await close();
+        throw error;
+    }
+}

package/dist/hub/static-ui.d.ts

@@ -0,0 +1,2 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare function serveHubUi(request: IncomingMessage, response: ServerResponse): boolean;

package/dist/hub/static-ui.js

@@ -0,0 +1,30 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const root = path.dirname(fileURLToPath(import.meta.resolve('@omochi-ui/hub-ui/assets')));
+const types = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8', '.svg': 'image/svg+xml', '.png': 'image/png', '.woff2': 'font/woff2' };
+export function serveHubUi(request, response) {
+    const pathname = new URL(request.url ?? '/', 'http://localhost').pathname;
+    if (pathname !== '/' && pathname !== '/index.html' && !pathname.startsWith('/assets/'))
+        return false;
+    if (request.method !== 'GET' && request.method !== 'HEAD') {
+        response.writeHead(405).end();
+        return true;
+    }
+    let filename;
+    try {
+        filename = path.resolve(root, '.' + (pathname === '/' ? '/index.html' : decodeURIComponent(pathname)));
+        if (!filename.startsWith(root + path.sep))
+            throw new Error();
+    }
+    catch {
+        response.writeHead(400).end();
+        return true;
+    }
+    void readFile(filename).then(data => {
+        response.writeHead(200, { 'Content-Type': types[path.extname(filename)] ?? 'application/octet-stream',
+            'X-Content-Type-Options': 'nosniff', 'Cache-Control': 'no-cache' });
+        response.end(request.method === 'HEAD' ? undefined : data);
+    }).catch(() => response.writeHead(404).end('Hub UI not found; run bun run build.'));
+    return true;
+}

package/dist/stdio-websocket-bridge.d.ts

@@ -0,0 +1,17 @@
+import type { ChildProcessWithoutNullStreams } from 'node:child_process';
+export interface StdioWebSocketBridgeOptions {
+    command: string[];
+    host?: string;
+    port?: number;
+}
+export interface StdioWebSocketBridgeHandle {
+    readonly url: string;
+    readonly child: ChildProcessWithoutNullStreams;
+    readonly exited: Promise<number>;
+    close(): Promise<void>;
+}
+/**
+ * Hosts one child application for every connected renderer. The hub generalizes this
+ * to many backends; this entry point stays single-session and never rewrites surface ids.
+ */
+export declare function startStdioWebSocketBridge(options: StdioWebSocketBridgeOptions): Promise<StdioWebSocketBridgeHandle>;

package/dist/stdio-websocket-bridge.js

@@ -0,0 +1,78 @@
+import process from 'node:process';
+import { A2uiSnapshot, FanOut, closeSocket, parseClientFrame, readJsonlMessages, spawnChildSession, startWsEndpoint, webSocketClient, } from '@omochi-ui/core';
+/**
+ * Hosts one child application for every connected renderer. The hub generalizes this
+ * to many backends; this entry point stays single-session and never rewrites surface ids.
+ */
+export async function startStdioWebSocketBridge(options) {
+    if (!options.command.length)
+        throw new Error('a child command is required after --');
+    const host = options.host ?? '127.0.0.1';
+    const port = options.port ?? 5555;
+    const snapshot = new A2uiSnapshot();
+    const fanOut = new FanOut(() => snapshot.messages());
+    let endpoint = null;
+    let childProtocolFailed = false;
+    const closeEndpoint = () => {
+        if (endpoint?.httpServer.listening)
+            endpoint.httpServer.close();
+    };
+    const session = spawnChildSession(options.command, {
+        onExit(exitCode) {
+            if (!childProtocolFailed) {
+                fanOut.closeAll(exitCode === 0 ? 1000 : 1011, `child process exited with code ${exitCode}`);
+            }
+            closeEndpoint();
+        },
+        onError(error) {
+            fanOut.closeAll(1011, `failed to start child: ${error.message}`);
+            closeEndpoint();
+        },
+    });
+    readJsonlMessages({
+        input: session.child.stdout,
+        onMessage(value, raw) {
+            snapshot.apply(value);
+            fanOut.broadcast(raw);
+        },
+        onInvalid(detail, lineNumber) {
+            childProtocolFailed = true;
+            const message = `child stdout line ${lineNumber}: invalid A2UI JSON: ${detail}`;
+            process.stderr.write(`[omochi-ui] ${message}\n`);
+            fanOut.closeAll(1002, message);
+            session.kill('SIGTERM');
+        },
+    });
+    try {
+        endpoint = await startWsEndpoint({ host, port });
+    }
+    catch (error) {
+        session.kill('SIGTERM');
+        throw error;
+    }
+    endpoint.onConnection((socket) => {
+        const client = webSocketClient(socket);
+        fanOut.add(client);
+        socket.on('message', (data, isBinary) => {
+            const frame = parseClientFrame(data, isBinary);
+            if (!frame.ok) {
+                closeSocket(socket, frame.code, frame.reason);
+                return;
+            }
+            session.writeLine(frame.value);
+        });
+        socket.on('close', () => fanOut.remove(client));
+    });
+    if (session.finished)
+        closeEndpoint();
+    return {
+        url: endpoint.url,
+        child: session.child,
+        exited: session.exited,
+        async close() {
+            fanOut.closeAll(1001, 'bridge shutting down');
+            session.kill('SIGTERM');
+            await endpoint.close();
+        },
+    };
+}

package/dist/up.d.ts

@@ -0,0 +1,21 @@
+import type { DashboardPreset } from '@omochi-ui/hub-ui/contracts';
+export interface CompositionService {
+    id: string;
+    command: string[];
+    cwd: string;
+    env: Record<string, string>;
+}
+export interface Composition {
+    id: string;
+    services: CompositionService[];
+    preset: DashboardPreset;
+}
+/** Parse a composition and resolve its semantic rows onto the hub's twelve-column grid. */
+export declare function parseComposition(source: string, file: string, nodeId: string): Composition;
+export declare function loadComposition(file: string, nodeId: string): Promise<Composition>;
+export interface ServiceSupervisor {
+    close(): Promise<void>;
+}
+export declare function startCompositionServices(services: readonly CompositionService[]): ServiceSupervisor;
+/** Best-effort desktop opener; the hub remains running when no desktop is available. */
+export declare function openBrowser(url: string): void;