@harness-fe/runtime 3.0.1

package/dist/client.js

@@ -0,0 +1,364 @@
+/**
+ * Runtime client core. Connects to the MCP server over WS, executes
+ * commands dispatched by the server, and forwards page events back.
+ *
+ * Started lazily by `auto-start.ts` when the script is imported.
+ */
+import { COMMAND, DEFAULT_WS_PORT, EVENT_NAME, frameSchema, } from '@harness-fe/protocol';
+import { getCaptureStore } from './capture.js';
+import { commandHandlers } from './commands.js';
+import { Outbox } from './outbox.js';
+import { RrwebRecorder } from './recording.js';
+import { chunkHasFullSnapshot } from './rrweb-types.js';
+import { collectPageLoadSnapshot } from './snapshot.js';
+import { collectEnv, getOrCreateVisitorId, publishVisitorIdToWindow, tryInheritVisitorFromParent, } from './visitor.js';
+const TAB_ID_KEY = '__hfe_tab_id__';
+function getOrCreateTabId() {
+    try {
+        const existing = sessionStorage.getItem(TAB_ID_KEY);
+        if (existing)
+            return existing;
+        const id = `${Date.now().toString(36)}-${crypto.randomUUID().slice(0, 8)}`;
+        sessionStorage.setItem(TAB_ID_KEY, id);
+        return id;
+    }
+    catch {
+        return `${Date.now().toString(36)}-${crypto.randomUUID().slice(0, 8)}`;
+    }
+}
+/**
+ * Generate a fresh sessionId for this page load. Intentionally NOT persisted
+ * to sessionStorage — a refresh MUST yield a new id. WebSocket reconnects
+ * within the same page load reuse this in-memory value.
+ *
+ * (Previously called `loadId`; renamed to align with the narrative model
+ *  where one page-load = one "session" of user activity.)
+ */
+function generateSessionId() {
+    try {
+        return crypto.randomUUID();
+    }
+    catch {
+        return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+    }
+}
+/**
+ * Attempt to read a server-generated sessionId from `window.__HARNESS_FE_SEED__`
+ * or from `window.__HARNESS_FE__.sessionId` (both written by `<HarnessScript>`).
+ *
+ * When found, the client adopts that id instead of generating its own. This
+ * ensures server-side events emitted by `@harness-fe/node-runtime` during
+ * the same request and client-side events all land in the same
+ * `sessions/{sessionId}/timeline.jsonl` on the daemon.
+ *
+ * Returns `undefined` when no seed is present (e.g. app doesn't use
+ * `<HarnessScript>` or running outside a browser).
+ */
+function tryAdoptServerSeed() {
+    if (typeof window === 'undefined')
+        return undefined;
+    const w = window;
+    return w.__HARNESS_FE_SEED__?.sessionId ?? w.__HARNESS_FE__?.sessionId;
+}
+// Re-export inheritance helper. Implementation lives in parent-inherit.ts
+// so its unit tests can import it without dragging the rrweb-dependent
+// recorder module into the test runtime.
+export { tryInheritFromParent } from './parent-inherit.js';
+import { tryInheritFromParent as _tryInheritFromParent } from './parent-inherit.js';
+export class RuntimeClient {
+    opts;
+    ws;
+    tabId;
+    sessionId;
+    visitorId;
+    parentProjectId;
+    /** Read-only accessors exposed for the in-page info panel. */
+    get projectId() { return this.opts.projectId; }
+    get buildId() { return this.opts.buildId; }
+    get displayName() { return this.opts.displayName; }
+    get userId() { return this.opts.userId; }
+    get mcpUrl() { return this.opts.mcpUrl; }
+    /** WebSocket state: 'connecting' | 'open' | 'closed'. */
+    getConnectionState() {
+        if (!this.ws)
+            return 'closed';
+        switch (this.ws.readyState) {
+            case WebSocket.OPEN: return 'open';
+            case WebSocket.CONNECTING: return 'connecting';
+            default: return 'closed';
+        }
+    }
+    pageLoadSent = false;
+    ctx = { capture: getCaptureStore() };
+    recorder = new RrwebRecorder((chunk) => this.sendEvent(EVENT_NAME.RRWEB, chunk));
+    reconnectAttempts = 0;
+    closed = false;
+    static MAX_OUTBOX_FRAMES = 500;
+    static MAX_OUTBOX_BYTES = 8 * 1024 * 1024;
+    outbox = new Outbox(RuntimeClient.MAX_OUTBOX_FRAMES, RuntimeClient.MAX_OUTBOX_BYTES);
+    constructor(opts) {
+        this.opts = opts;
+        const inherited = _tryInheritFromParent();
+        this.tabId = inherited.tabId ?? getOrCreateTabId();
+        // Priority: iframe parent seed > server seed > fresh generation.
+        this.sessionId = inherited.sessionId ?? tryAdoptServerSeed() ?? generateSessionId();
+        // Explicit option wins over runtime auto-detection.
+        this.parentProjectId = opts.parentProjectId ?? inherited.parentProjectId;
+        // Same-origin iframes share a visitorId so the journey stitches across
+        // micro-frontends. Cross-origin children fall back to their own.
+        const inheritedVisitor = tryInheritVisitorFromParent();
+        this.visitorId = inheritedVisitor ?? getOrCreateVisitorId();
+        publishVisitorIdToWindow(this.visitorId);
+    }
+    start() {
+        this.ctx.capture.install((name, payload) => this.sendEvent(name, payload));
+        this.recorder.start();
+        this.connect();
+    }
+    stop() {
+        this.closed = true;
+        this.recorder.stop();
+        this.ws?.close();
+    }
+    connect() {
+        const url = this.opts.mcpUrl ?? `ws://127.0.0.1:${DEFAULT_WS_PORT}`;
+        try {
+            this.ws = new WebSocket(url);
+        }
+        catch (err) {
+            console.warn('[morphix-dev-bridge] failed to construct WebSocket', err);
+            return;
+        }
+        this.ws.addEventListener('open', () => this.onOpen());
+        this.ws.addEventListener('message', (ev) => this.onMessage(ev));
+        this.ws.addEventListener('close', () => this.onClose());
+        this.ws.addEventListener('error', () => {
+            /* close will follow */
+        });
+    }
+    onOpen() {
+        this.reconnectAttempts = 0;
+        const hello = {
+            type: 'hello',
+            id: crypto.randomUUID(),
+            role: 'runtime-client',
+            projectId: this.opts.projectId,
+            parentProjectId: this.parentProjectId,
+            displayName: this.opts.displayName,
+            buildId: this.opts.buildId,
+            tabId: this.tabId,
+            sessionId: this.sessionId,
+            visitorId: this.visitorId,
+            userId: this.opts.userId,
+            env: collectEnv(),
+            page: {
+                url: location.href,
+                title: document.title,
+                userAgent: navigator.userAgent,
+            },
+        };
+        this.send(hello);
+        // Any pre-OPEN frames (rrweb chunk 1 with the Meta+FullSnapshot
+        // baseline is the canonical example) get flushed *after* hello, so
+        // the daemon has a registered peer before they arrive.
+        this.drainOutbox();
+    }
+    onClose() {
+        if (this.closed)
+            return;
+        const delay = Math.min(15_000, 500 * 2 ** Math.min(this.reconnectAttempts, 5));
+        this.reconnectAttempts++;
+        setTimeout(() => {
+            if (!this.closed)
+                this.connect();
+        }, delay);
+    }
+    onMessage(ev) {
+        let parsed;
+        try {
+            parsed = JSON.parse(String(ev.data));
+        }
+        catch {
+            return;
+        }
+        const result = frameSchema.safeParse(parsed);
+        if (!result.success)
+            return;
+        const frame = result.data;
+        if (frame.type === 'command')
+            this.handleCommand(frame);
+        else if (frame.type === 'hello.ack')
+            this.onHelloAck(frame);
+        else if (frame.type === 'query.response')
+            this.onQueryResponse(frame);
+    }
+    onQueryResponse(frame) {
+        const pending = this.pendingQueries.get(frame.id);
+        if (!pending)
+            return;
+        this.pendingQueries.delete(frame.id);
+        if (frame.ok) {
+            pending.resolve(frame.result);
+        }
+        else {
+            pending.reject(new Error(frame.error?.message ?? 'query failed'));
+        }
+    }
+    onHelloAck(frame) {
+        if (frame.error) {
+            // Bridge rejected this hello — do not send PAGE_LOAD.
+            return;
+        }
+        // Force a fresh rrweb FullSnapshot on every ack — including reconnects
+        // after daemon restart, network blips, or page-recovery from sleep.
+        // Without this, the only baseline for the session is whatever rrweb
+        // emitted at start(); if that chunk was evicted from the outbox
+        // (FIFO overflow during a long disconnect) or the daemon was down at
+        // the critical moment, the session is unreplayable forever.
+        // Safe to call on every ack: rrweb emits another type:2, replay
+        // engines treat additional baselines as a checkpoint reset.
+        this.recorder.takeFullSnapshot();
+        // Send the page-load snapshot exactly once per load. The reconnect
+        // path also lands here; emit only on the first ack of this load.
+        if (this.pageLoadSent)
+            return;
+        this.pageLoadSent = true;
+        try {
+            const payload = collectPageLoadSnapshot(this.sessionId);
+            this.sendEvent(EVENT_NAME.PAGE_LOAD, payload);
+        }
+        catch {
+            /* snapshot failures must not propagate */
+        }
+    }
+    async handleCommand(frame) {
+        const handler = commandHandlers[frame.command];
+        if (!handler) {
+            this.send({
+                type: 'response',
+                id: frame.id,
+                ok: false,
+                error: { code: 'UNKNOWN_COMMAND', message: `no handler for "${frame.command}"` },
+            });
+            return;
+        }
+        try {
+            const result = await handler(frame.args ?? {}, this.ctx);
+            this.send({
+                type: 'response',
+                id: frame.id,
+                ok: true,
+                result,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this.send({
+                type: 'response',
+                id: frame.id,
+                ok: false,
+                error: { message },
+            });
+        }
+    }
+    sendEvent(name, payload) {
+        const event = {
+            type: 'event',
+            id: crypto.randomUUID(),
+            tabId: this.tabId,
+            projectId: this.opts.projectId,
+            // v0.2: stamp every event with sessionId + buildId so cross-project
+            // queries (`session.timeline`, `build.timeline`) can filter without
+            // extra lookups. v0.5 also stamps visitorId so visitor-scoped
+            // filtering ("show me everything from this user") is row-level too.
+            sessionId: this.sessionId,
+            buildId: this.opts.buildId,
+            visitorId: this.visitorId,
+            name,
+            ts: Date.now(),
+            payload,
+        };
+        this.send(event);
+    }
+    /**
+     * Request/reply RPC to the daemon. Currently used by the in-page
+     * overlay to fetch / mutate the visitor's own tasks. Resolves with the
+     * remote `result`, rejects with the remote `error.message` (or a
+     * timeout after 10 s).
+     */
+    query(method, args, timeoutMs = 10_000) {
+        const id = crypto.randomUUID();
+        const frame = { type: 'query', id, method, args };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingQueries.delete(id);
+                reject(new Error(`harness-fe query "${method}" timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pendingQueries.set(id, {
+                resolve: (v) => { clearTimeout(timer); resolve(v); },
+                reject: (e) => { clearTimeout(timer); reject(e); },
+            });
+            this.send(frame);
+        });
+    }
+    pendingQueries = new Map();
+    send(frame) {
+        let payload;
+        try {
+            payload = JSON.stringify(frame);
+        }
+        catch {
+            return; // unserializable; drop
+        }
+        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+            try {
+                this.ws.send(payload);
+                return;
+            }
+            catch {
+                // write failed mid-stream — fall through and buffer for retry
+            }
+        }
+        this.outbox.enqueue(payload, isStickyFrame(frame));
+    }
+    drainOutbox() {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        this.outbox.flush((payload) => {
+            this.ws.send(payload);
+        });
+    }
+}
+/**
+ * Decide whether an outgoing frame must survive outbox eviction.
+ *
+ * Today: any rrweb chunk that contains a FullSnapshot (type:2). Without
+ * this, the FullSnapshot — being the *first* rrweb frame emitted at
+ * recorder start — was always the oldest in the outbox and the FIFO
+ * evictor dropped it first when the daemon was unreachable. That left the
+ * session unreplayable for its entire life.
+ */
+function isStickyFrame(frame) {
+    if (frame.type !== 'event')
+        return false;
+    if (frame.name !== EVENT_NAME.RRWEB)
+        return false;
+    const payload = frame.payload;
+    if (!payload || !Array.isArray(payload.events))
+        return false;
+    return chunkHasFullSnapshot(payload);
+}
+/** Pull the well-known config object planted by the Vite plugin on window. */
+export function readInjectedConfig() {
+    const w = window;
+    return {
+        projectId: w.__HARNESS_FE__?.projectId ?? 'unknown-project',
+        mcpUrl: w.__HARNESS_FE__?.mcpUrl,
+        buildId: w.__HARNESS_FE__?.buildId,
+        parentProjectId: w.__HARNESS_FE__?.parentProjectId,
+        displayName: w.__HARNESS_FE__?.displayName,
+        userId: w.__HARNESS_FE__?.userId,
+    };
+}
+/** Re-export command names for outside callers. */
+export { COMMAND };

package/dist/commands.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Built-in command handlers run in the page. Each receives parsed args and
+ * returns a serializable result that gets shipped back in a ResponseFrame.
+ */
+import type { CaptureStore } from './capture.js';
+export interface CommandContext {
+    capture: CaptureStore;
+}
+export type CommandHandler = (args: unknown, ctx: CommandContext) => Promise<unknown>;
+export declare const commandHandlers: Record<string, CommandHandler>;

package/dist/commands.js

@@ -0,0 +1,304 @@
+/**
+ * Built-in command handlers run in the page. Each receives parsed args and
+ * returns a serializable result that gets shipped back in a ResponseFrame.
+ */
+import { COMMAND, } from '@harness-fe/protocol';
+import { snapdom } from '@zumer/snapdom';
+import { resolveSelector } from './selectors.js';
+const HTML_TRUNCATE = 4000;
+function describeNoMatch(selector) {
+    const fields = Object.entries(selector)
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+        .join(' ');
+    return `no element matched selector: ${fields}`;
+}
+export const commandHandlers = {
+    [COMMAND.PAGE_CLICK]: async (raw) => {
+        const args = raw;
+        const result = resolveSelector(args.selector);
+        if (!result.element)
+            throw new Error(describeNoMatch(args.selector));
+        const target = result.element;
+        // When the resolved element is not itself an <a>, walk up to find the
+        // nearest anchor ancestor. This handles the common case where a text
+        // selector matches a child <span> inside a React Router <Link>, which
+        // would otherwise fire a click that bypasses the router's onClick handler.
+        let clickTarget = target;
+        if (target.tagName !== 'A') {
+            const anchor = target.closest('a');
+            if (anchor)
+                clickTarget = anchor;
+        }
+        // Dispatch a proper MouseEvent instead of calling .click() so that
+        // framework routers (React Router, Vue Router) receive a bubbling event
+        // with the correct button/modifier state they check before navigating.
+        clickTarget.dispatchEvent(new MouseEvent('click', {
+            bubbles: true,
+            cancelable: true,
+            view: window,
+            button: args.button === 'right' ? 2 : args.button === 'middle' ? 1 : 0,
+        }));
+        return { via: result.via, tag: clickTarget.tagName.toLowerCase() };
+    },
+    [COMMAND.PAGE_TYPE]: async (raw) => {
+        const args = raw;
+        const result = resolveSelector(args.selector);
+        if (!result.element)
+            throw new Error(describeNoMatch(args.selector));
+        const target = result.element;
+        if (typeof target.value !== 'string') {
+            throw new Error('page.type: target element does not support .value');
+        }
+        // React (and Vue's controlled inputs) install setters/trackers on
+        // input.value. Setting `.value = '...'` directly bypasses them, so
+        // their state never updates. Use the native prototype setter so the
+        // framework's tracker registers the change, then dispatch a bubbling
+        // 'input' + 'change' event.
+        const proto = target instanceof HTMLInputElement
+            ? HTMLInputElement.prototype
+            : HTMLTextAreaElement.prototype;
+        const nativeSetter = Object.getOwnPropertyDescriptor(proto, 'value')?.set;
+        const next = args.clear !== false ? args.value : target.value + args.value;
+        if (nativeSetter)
+            nativeSetter.call(target, next);
+        else
+            target.value = next;
+        target.dispatchEvent(new Event('input', { bubbles: true }));
+        target.dispatchEvent(new Event('change', { bubbles: true }));
+        return { via: result.via, value: target.value };
+    },
+    [COMMAND.PAGE_EVALUATE]: async (raw) => {
+        const args = raw;
+        // eslint-disable-next-line no-new-func
+        const fn = new Function(`return (async () => { return (${args.expr}); })();`);
+        const value = await fn();
+        return { value: safeJson(value) };
+    },
+    [COMMAND.PAGE_WAIT_FOR]: async (raw) => {
+        const args = raw;
+        const timeoutMs = args.timeoutMs ?? 10_000;
+        const deadline = Date.now() + timeoutMs;
+        const isBuiltin = args.predicate === 'network.idle' || args.predicate === 'dom.ready';
+        // eslint-disable-next-line no-new-func
+        const probe = !isBuiltin
+            ? new Function(`return Boolean(${args.predicate})`)
+            : undefined;
+        while (Date.now() < deadline) {
+            if (args.predicate === 'dom.ready' && document.readyState === 'complete') {
+                return { ok: true, after: Date.now() };
+            }
+            if (args.predicate === 'network.idle') {
+                // Crude heuristic — we don't have a real idle tracker yet.
+                await new Promise((r) => setTimeout(r, 200));
+                return { ok: true, after: Date.now() };
+            }
+            if (probe && probe())
+                return { ok: true, after: Date.now() };
+            await new Promise((r) => setTimeout(r, 50));
+        }
+        throw new Error(`page.wait_for: predicate "${args.predicate}" did not become truthy in ${timeoutMs}ms`);
+    },
+    [COMMAND.PAGE_SCREENSHOT]: async (raw) => {
+        const args = raw;
+        const format = args.format ?? 'webp';
+        const maxWidth = args.maxWidth ?? 1280;
+        // Default to opaque white so transparent pages don't render a blank
+        // screenshot. Callers can pass `null` to opt back into transparency.
+        // JPEG has no alpha channel so the field is effectively always set.
+        const backgroundColor = args.backgroundColor === null
+            ? undefined
+            : (args.backgroundColor ?? (format === 'jpeg' ? '#fff' : '#ffffff'));
+        let target;
+        let via = 'document';
+        if (args.selector) {
+            const result = resolveSelector(args.selector);
+            if (!result.element)
+                throw new Error(describeNoMatch(args.selector));
+            target = result.element;
+            via = result.via;
+        }
+        else {
+            target = document.documentElement;
+        }
+        const rect = target.getBoundingClientRect();
+        const naturalWidth = Math.max(1, Math.round(rect.width || target.clientWidth || window.innerWidth));
+        const width = naturalWidth > maxWidth ? maxWidth : naturalWidth;
+        // Hide our own overlay during capture so the screenshot reflects the
+        // real page state. Without this, the floating "H" FAB and any open
+        // info card would always end up in the corner of every shot.
+        const overlayHost = document.getElementById('__harness_fe_overlay__');
+        const prevVisibility = overlayHost?.style.visibility ?? '';
+        if (overlayHost)
+            overlayHost.style.visibility = 'hidden';
+        try {
+            const result = await snapdom(target, {
+                fast: true,
+                width,
+                backgroundColor,
+            });
+            const canvas = await result.toCanvas();
+            const mime = format === 'jpeg' ? 'image/jpeg' : `image/${format}`;
+            const quality = format === 'png' ? undefined : 0.85;
+            const dataUrl = canvas.toDataURL(mime, quality);
+            return {
+                via,
+                format,
+                width: canvas.width,
+                height: canvas.height,
+                dataUrl,
+            };
+        }
+        finally {
+            if (overlayHost)
+                overlayHost.style.visibility = prevVisibility;
+        }
+    },
+    [COMMAND.PAGE_DOM_QUERY]: async (raw) => {
+        const args = raw;
+        const limit = args.limit ?? 5;
+        const matches = [];
+        // Try each selector field independently — we want all matches up to limit.
+        if (args.selector.css) {
+            const list = document.querySelectorAll(args.selector.css);
+            for (let i = 0; i < list.length && matches.length < limit; i++) {
+                matches.push({
+                    html: truncate(list[i].outerHTML, HTML_TRUNCATE),
+                    tag: list[i].tagName.toLowerCase(),
+                    via: 'css',
+                });
+            }
+        }
+        if (matches.length < limit) {
+            const result = resolveSelector(args.selector);
+            if (result.element) {
+                matches.push({
+                    html: truncate(result.element.outerHTML, HTML_TRUNCATE),
+                    tag: result.element.tagName.toLowerCase(),
+                    via: result.via,
+                });
+            }
+        }
+        return { matches };
+    },
+    [COMMAND.PAGE_SCROLL]: async (raw) => {
+        const args = raw;
+        const behavior = args.behavior ?? 'smooth';
+        if (args.selector) {
+            const result = resolveSelector(args.selector);
+            if (!result.element)
+                throw new Error(describeNoMatch(args.selector));
+            result.element.scrollIntoView({ behavior, block: 'center' });
+            return { via: result.via, scrolledIntoView: true };
+        }
+        window.scrollTo({ top: args.y ?? 0, left: args.x ?? 0, behavior });
+        return { scrollX: window.scrollX, scrollY: window.scrollY };
+    },
+    [COMMAND.PAGE_NAVIGATE]: async (raw) => {
+        const args = raw;
+        const method = args.method ?? 'href';
+        const before = location.href;
+        if (method === 'href') {
+            location.href = args.url;
+            return { method, from: before, to: args.url };
+        }
+        if (method === 'push') {
+            history.pushState({}, '', args.url);
+        }
+        else {
+            history.replaceState({}, '', args.url);
+        }
+        // Notify SPA routers that listen on popstate
+        window.dispatchEvent(new PopStateEvent('popstate', { state: history.state }));
+        return { method, from: before, to: location.href };
+    },
+    [COMMAND.PAGE_RELOAD]: async (raw) => {
+        const args = raw;
+        if (args.hard) {
+            // Hard reload — bypass cache
+            location.reload();
+        }
+        else {
+            location.reload();
+        }
+        return { reloading: true };
+    },
+    [COMMAND.PAGE_SET_HTML]: async (raw) => {
+        const args = raw;
+        const result = resolveSelector(args.selector);
+        if (!result.element)
+            throw new Error(describeNoMatch(args.selector));
+        const el = result.element;
+        const target = args.target ?? 'innerHTML';
+        const before = target === 'innerHTML' ? el.innerHTML : el.outerHTML;
+        if (target === 'innerHTML') {
+            el.innerHTML = args.html;
+            return { via: result.via, target, before: truncate(before, 500) };
+        }
+        // outerHTML replacement — the element is removed from the DOM; return the new element tag
+        const tag = el.tagName.toLowerCase();
+        el.outerHTML = args.html;
+        return { via: result.via, target, replacedTag: tag, before: truncate(before, 500) };
+    },
+    [COMMAND.PAGE_SET_STYLE]: async (raw) => {
+        const args = raw;
+        // Global injection mode: { rule: "<raw css>" }
+        if (!args.selector) {
+            const rule = args.styles['rule'];
+            if (!rule)
+                throw new Error('page.set_style: pass { rule: "<css>" } when no selector is provided');
+            const styleId = '__hfe_injected_style__';
+            let styleEl = document.getElementById(styleId);
+            if (!styleEl) {
+                styleEl = document.createElement('style');
+                styleEl.id = styleId;
+                document.head.appendChild(styleEl);
+            }
+            styleEl.textContent += `\n${rule}`;
+            return { injected: true, rule };
+        }
+        // Element inline-style mode
+        const result = resolveSelector(args.selector);
+        if (!result.element)
+            throw new Error(describeNoMatch(args.selector));
+        const el = result.element;
+        const merge = args.merge !== false; // default true
+        if (!merge)
+            el.removeAttribute('style');
+        const applied = {};
+        for (const [prop, value] of Object.entries(args.styles)) {
+            // Accept both camelCase and kebab-case
+            const camel = prop.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+            el.style[camel] = value;
+            applied[camel] = value;
+        }
+        return { via: result.via, applied, currentStyle: el.getAttribute('style') };
+    },
+    [COMMAND.CONSOLE_TAIL]: async (raw, ctx) => {
+        const args = raw;
+        return { entries: ctx.capture.console.tail(args.n) };
+    },
+    [COMMAND.NETWORK_TAIL]: async (raw, ctx) => {
+        const args = raw;
+        return { entries: ctx.capture.network.tail(args.n) };
+    },
+    [COMMAND.ERRORS_TAIL]: async (raw, ctx) => {
+        const args = raw;
+        return { entries: ctx.capture.errors.tail(args.n) };
+    },
+};
+function truncate(s, n) {
+    if (s.length <= n)
+        return s;
+    return `${s.slice(0, n)}… (truncated, total ${s.length} chars)`;
+}
+function safeJson(value) {
+    if (value === undefined)
+        return null;
+    try {
+        return JSON.parse(JSON.stringify(value));
+    }
+    catch {
+        return String(value);
+    }
+}

package/dist/dashboardUrl.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Convert the runtime's `mcpUrl` (a WebSocket URL the plugin gave us) into
+ * the dashboard URL the same daemon serves.
+ *
+ * The daemon binds one HTTP+WS port; the dashboard lives at
+ * `<http-scheme>://<host>:<port>/dashboard/`. The token, if any, is
+ * carried in the query string so the browser is pre-authenticated on
+ * first hit (after which mcp-server hands it off to a cookie — see
+ * `packages/mcp-server/src/dashboardSpa.ts`).
+ *
+ * Optionally deep-links into a session's detail page when `sessionId` is
+ * provided.
+ */
+export interface DashboardUrlInput {
+    mcpUrl: string;
+    sessionId?: string;
+}
+export declare function deriveDashboardUrl(input: DashboardUrlInput): string | undefined;