@harness-fe/runtime 3.3.0 → 3.4.0

package/src/overlay.test.ts

@@ -2,6 +2,8 @@
 import { afterEach, describe, expect, it } from 'vitest';
 import { Window } from 'happy-dom';
 import { installOverlay, buildCssPath, replayStrokes, finalizeAnnotation, type OverlayClient } from './overlay.js';
+import { registerOverlayPlugin, __resetOverlayPlugins, type OverlayPluginContext } from './pluginRegistry.js';
+import { getCaptureStore } from './capture.js';
 
 function setupDom(): { win: Window; doc: Document } {
     const win = new Window();
@@ -317,3 +319,123 @@ describe('buildCssPath', () => {
         expect(path).toMatch(/p\.x:nth-of-type\(3\)/);
     });
 });
+
+describe('overlay plugins', () => {
+    afterEach(() => {
+        document.getElementById('__harness_fe_overlay__')?.remove();
+        __resetOverlayPlugins();
+        getCaptureStore().network.clear();
+        getCaptureStore().console.clear();
+        getCaptureStore().errors.clear();
+    });
+
+    const openCard = (root: ShadowRoot) =>
+        (root.querySelector('.fab') as HTMLButtonElement).click();
+
+    it('renders a button for a plugin registered before install', () => {
+        setupDom();
+        registerOverlayPlugin({ id: 'p1', label: 'Send', icon: '💬', onClick() {} });
+        installOverlay(makeFakeClient());
+        const root = document.getElementById('__harness_fe_overlay__')!.shadowRoot!;
+        const btn = root.querySelector('[data-plugin-id=p1]') as HTMLButtonElement;
+        expect(btn).toBeTruthy();
+        expect(btn.textContent).toBe('💬 Send');
+        const slot = root.querySelector('[data-role=plugin-actions]') as HTMLElement;
+        expect(slot.style.display).not.toBe('none');
+    });
+
+    it('renders a button for a plugin registered AFTER install (late registration)', () => {
+        setupDom();
+        installOverlay(makeFakeClient());
+        const root = document.getElementById('__harness_fe_overlay__')!.shadowRoot!;
+        expect(root.querySelector('[data-plugin-id=late]')).toBeNull();
+        registerOverlayPlugin({ id: 'late', label: 'Later', onClick() {} });
+        expect(root.querySelector('[data-plugin-id=late]')).toBeTruthy();
+    });
+
+    it('hides the plugin slot when no plugins are registered', () => {
+        setupDom();
+        installOverlay(makeFakeClient());
+        const root = document.getElementById('__harness_fe_overlay__')!.shadowRoot!;
+        const slot = root.querySelector('[data-role=plugin-actions]') as HTMLElement;
+        expect(slot.style.display).toBe('none');
+    });
+
+    it('invokes onClick with a context carrying ids / url / snapshotMarkdown', () => {
+        setupDom();
+        let ctx: OverlayPluginContext | undefined;
+        registerOverlayPlugin({ id: 'cap', label: 'Capture', onClick(c) { ctx = c; } });
+        installOverlay(makeFakeClient());
+        const root = document.getElementById('__harness_fe_overlay__')!.shadowRoot!;
+        openCard(root);
+        (root.querySelector('[data-plugin-id=cap]') as HTMLButtonElement).click();
+        expect(ctx).toBeTruthy();
+        expect(ctx!.projectId).toBe('demo');
+        expect(ctx!.sessionId).toBe('sess-12345-abcdef-9876');
+        expect(ctx!.tabId).toBe('tab-123456-abcdef');
+        expect(typeof ctx!.url).toBe('string');
+        expect(ctx!.snapshotMarkdown()).toContain('project: `demo`');
+    });
+
+    it('getLogs() redacts network bodies + auth headers by default, raw when opted out', () => {
+        setupDom();
+        getCaptureStore().network.push({
+            ts: Date.now(), method: 'POST', url: 'https://api.example.com/login',
+            status: 200,
+            requestHeaders: { authorization: 'Bearer secret', 'content-type': 'application/json' },
+            requestBody: { password: 'hunter2' },
+            responseBody: { token: 'abc' },
+        });
+        let ctx: OverlayPluginContext | undefined;
+        registerOverlayPlugin({ id: 'logs', label: 'Logs', onClick(c) { ctx = c; } });
+        installOverlay(makeFakeClient());
+        const root = document.getElementById('__harness_fe_overlay__')!.shadowRoot!;
+        openCard(root);
+        (root.querySelector('[data-plugin-id=logs]') as HTMLButtonElement).click();
+
+        const redacted = ctx!.getLogs({ network: 5 }).network[0];
+        expect(redacted.requestBody).toBeUndefined();
+        expect(redacted.responseBody).toBeUndefined();
+        expect(redacted.requestHeaders).toEqual({ 'content-type': 'application/json' });
+        expect(redacted.url).toBe('https://api.example.com/login');
+
+        const raw = ctx!.getLogs({ network: 5, redact: false }).network[0];
+        expect(raw.requestBody).toEqual({ password: 'hunter2' });
+        expect(raw.requestHeaders!.authorization).toBe('Bearer secret');
+    });
+
+    it('a requiresElement plugin click enters picker mode', () => {
+        setupDom();
+        registerOverlayPlugin({ id: 'pick', label: 'Pick', requiresElement: true, onClick() {} });
+        installOverlay(makeFakeClient());
+        const root = document.getElementById('__harness_fe_overlay__')!.shadowRoot!;
+        openCard(root);
+        (root.querySelector('[data-plugin-id=pick]') as HTMLButtonElement).click();
+        expect((root.querySelector('.picker-bar') as HTMLElement).style.display).toBe('flex');
+        expect((root.querySelector('.info-card') as HTMLElement).style.display).toBe('none');
+        expect((root.querySelector('.fab') as HTMLButtonElement).dataset.state).toBe('active');
+    });
+
+    it('toasts when a plugin onClick throws', async () => {
+        setupDom();
+        registerOverlayPlugin({ id: 'boom', label: 'Boom', onClick() { throw new Error('nope'); } });
+        installOverlay(makeFakeClient());
+        const root = document.getElementById('__harness_fe_overlay__')!.shadowRoot!;
+        openCard(root);
+        (root.querySelector('[data-plugin-id=boom]') as HTMLButtonElement).click();
+        await Promise.resolve();
+        const toast = root.querySelector('.hfe-toast') as HTMLElement;
+        expect(toast).toBeTruthy();
+        expect(toast.dataset.kind).toBe('error');
+        expect(toast.textContent).toContain('nope');
+    });
+
+    it('shows a GitHub promo link in the info card', () => {
+        setupDom();
+        installOverlay(makeFakeClient());
+        const root = document.getElementById('__harness_fe_overlay__')!.shadowRoot!;
+        const link = root.querySelector('[data-role=github]') as HTMLAnchorElement;
+        expect(link).toBeTruthy();
+        expect(link.getAttribute('href')).toBe('https://github.com/Morphicai/harness-fe');
+    });
+});

package/src/overlay.ts

@@ -14,9 +14,27 @@
  * or out. State machine: idle → info → (picker → question) → flash → idle.
  */
 
-import { EVENT_NAME, type TaskSubmitPayload, type TaskAttachment } from '@harness-fe/protocol';
+import {
+    EVENT_NAME,
+    type TaskSubmitPayload,
+    type TaskAttachment,
+    type NetworkEntry,
+} from '@harness-fe/protocol';
 import { snapdom } from '@zumer/snapdom';
 import { deriveDashboardUrl } from './dashboardUrl.js';
+import { getCaptureStore } from './capture.js';
+import { collectPageLoadSnapshot } from './snapshot.js';
+import {
+    getOverlayPlugins,
+    subscribeOverlayPlugins,
+    type OverlayPlugin,
+    type OverlayPluginContext,
+    type OverlayPluginLogs,
+    type OverlayPluginGetLogsOptions,
+} from './pluginRegistry.js';
+
+/** Repo URL surfaced in the overlay footer. */
+const GITHUB_URL = 'https://github.com/Morphicai/harness-fe';
 
 const HOST_ID = '__harness_fe_overlay__';
 const MAX_OUTER_HTML = 2048;
@@ -289,6 +307,8 @@ export function installOverlay(client: OverlayClient): void {
     let statusPollTimer: number | undefined;
     /** Flattened PNG from the annotate step; null if user skipped. */
     let pendingAttachment: TaskAttachment | null = null;
+    /** Set while the picker is collecting an element for a `requiresElement` plugin. */
+    let pluginAwaitingElement: OverlayPlugin | null = null;
 
     const setState = (next: State) => {
         state = next;
@@ -360,6 +380,17 @@ export function installOverlay(client: OverlayClient): void {
         if (!hoveredEl) return;
         lockedEl = hoveredEl;
         setHighlight(lockedEl);
+        // A plugin requested the element — hand it straight to its onClick and
+        // skip the report/question flow entirely.
+        if (pluginAwaitingElement) {
+            const plugin = pluginAwaitingElement;
+            pluginAwaitingElement = null;
+            const el = lockedEl;
+            lockedEl = null;
+            setState('idle');
+            void invokePlugin(plugin, el);
+            return;
+        }
         // Go straight to the question step. Screenshots are now opt-in via
         // the "Add screenshot" button inside the question panel — users
         // shouldn't have to draw on every report.
@@ -385,6 +416,7 @@ export function installOverlay(client: OverlayClient): void {
             } else if (state === 'picker' || state === 'question') {
                 lockedEl = null;
                 pendingAttachment = null;
+                pluginAwaitingElement = null;
                 setState('info');
             } else if (state === 'info') {
                 setState('idle');
@@ -469,6 +501,106 @@ export function installOverlay(client: OverlayClient): void {
         return lines.join('\n') + '\n';
     };
 
+    // ─── Plugin support ──────────────────────────────────────────────────
+    const dashboardUrl = client.mcpUrl
+        ? deriveDashboardUrl({ mcpUrl: client.mcpUrl, sessionId: client.sessionId })
+        : undefined;
+
+    /** Brief transient toast anchored near the FAB. */
+    const showToast = (message: string, kind: 'ok' | 'error' = 'ok'): void => {
+        const el = document.createElement('div');
+        el.className = 'hfe-toast';
+        el.dataset.kind = kind;
+        el.textContent = message;
+        root.appendChild(el);
+        requestAnimationFrame(() => { el.dataset.show = '1'; });
+        setTimeout(() => {
+            el.dataset.show = '';
+            setTimeout(() => el.remove(), 250);
+        }, 2400);
+    };
+
+    const buildPluginContext = (selectedEl?: Element): OverlayPluginContext => {
+        const selectedElement = selectedEl
+            ? {
+                  el: selectedEl,
+                  selector: {
+                      comp: selectedEl.getAttribute('data-morphix-comp') ?? undefined,
+                      loc: selectedEl.getAttribute('data-morphix-loc') ?? undefined,
+                      css: buildCssPath(selectedEl),
+                  },
+                  outerHTML: truncate(stripInternalAttrs(selectedEl.outerHTML), MAX_OUTER_HTML),
+                  rect: (() => {
+                      const r = selectedEl.getBoundingClientRect();
+                      return { x: r.x, y: r.y, width: r.width, height: r.height };
+                  })(),
+              }
+            : undefined;
+        return {
+            projectId: client.projectId,
+            displayName: client.displayName,
+            buildId: client.buildId,
+            parentProjectId: client.parentProjectId,
+            sessionId: client.sessionId,
+            tabId: client.tabId,
+            visitorId: client.visitorId,
+            userId: client.userId,
+            url: location.href,
+            connectionState: client.getConnectionState(),
+            dashboardUrl,
+            selectedElement,
+            snapshotMarkdown: buildSnapshot,
+            snapshot: () => collectPageLoadSnapshot(client.sessionId),
+            getLogs: (opts) => collectLogs(opts),
+            captureScreenshot: (el) => captureElementPng(el ?? selectedEl ?? document.body),
+            query: client.query ? client.query.bind(client) : undefined,
+            copyToClipboard: (text) => copyText(text),
+            toast: showToast,
+        };
+    };
+
+    const invokePlugin = async (plugin: OverlayPlugin, selectedEl?: Element): Promise<void> => {
+        try {
+            await plugin.onClick(buildPluginContext(selectedEl));
+        } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            showToast(`${plugin.label}: ${msg}`, 'error');
+        }
+    };
+
+    /** (Re)render the plugin button group in the info card. */
+    const renderPluginButtons = (): void => {
+        const slot = infoCard.querySelector<HTMLElement>('[data-role=plugin-actions]');
+        if (!slot) return;
+        const list = getOverlayPlugins();
+        slot.innerHTML = '';
+        slot.style.display = list.length ? '' : 'none';
+        for (const plugin of list) {
+            const btn = document.createElement('button');
+            btn.className = 'secondary';
+            btn.type = 'button';
+            btn.dataset.pluginId = plugin.id;
+            btn.textContent = `${plugin.icon ? plugin.icon + ' ' : ''}${plugin.label}`;
+            btn.addEventListener('click', () => {
+                if (plugin.requiresElement) {
+                    pluginAwaitingElement = plugin;
+                    setState('picker');
+                } else {
+                    setState('idle');
+                    void invokePlugin(plugin);
+                }
+            });
+            slot.appendChild(btn);
+        }
+    };
+
+    renderPluginButtons();
+    const unsubscribePlugins = subscribeOverlayPlugins(() => {
+        // Only the info card shows plugin buttons; re-render whenever the set changes.
+        renderPluginButtons();
+    });
+    void unsubscribePlugins; // overlay lives for the page lifetime; no teardown path
+
     // ─── Reports rendering ───────────────────────────────────────────────
     let editingTaskId: string | null = null;
     let deleteConfirmId: string | null = null;
@@ -690,9 +822,6 @@ export function installOverlay(client: OverlayClient): void {
     // the plugin / runtime config).
     {
         const dashboardBtn = infoCard.querySelector<HTMLButtonElement>('[data-role=open-dashboard]')!;
-        const dashboardUrl = client.mcpUrl
-            ? deriveDashboardUrl({ mcpUrl: client.mcpUrl, sessionId: client.sessionId })
-            : undefined;
         if (dashboardUrl) {
             dashboardBtn.style.display = '';
             dashboardBtn.title = `Open ${dashboardUrl} in a new tab`;
@@ -708,6 +837,18 @@ export function installOverlay(client: OverlayClient): void {
         }
     }
 
+    // GitHub promo link — anchor navigates natively; this fallback covers
+    // sandboxed iframes / popup blockers by copying the URL instead.
+    infoCard.querySelector<HTMLAnchorElement>('[data-role=github]')!.addEventListener('click', (ev) => {
+        try {
+            const opened = window.open(GITHUB_URL, '_blank', 'noopener,noreferrer');
+            if (opened) ev.preventDefault();
+        } catch {
+            ev.preventDefault();
+            void copyText(GITHUB_URL, ev.currentTarget as HTMLElement);
+        }
+    });
+
     reportsCard.querySelector('[data-role=back]')!.addEventListener('click', () => setState('info'));
     reportsCard.querySelector('[data-role=close]')!.addEventListener('click', () => setState('idle'));
     reportsCard.querySelector('[data-role=refresh]')!.addEventListener('click', () => void refreshReports());
@@ -727,6 +868,7 @@ export function installOverlay(client: OverlayClient): void {
 
     pickerBar.querySelector('[data-role=cancel]')!.addEventListener('click', () => {
         lockedEl = null;
+        pluginAwaitingElement = null;
         setState('info');
     });
 
@@ -1148,6 +1290,65 @@ export async function finalizeAnnotation(): Promise<TaskAttachment | null> {
     return att;
 }
 
+// ─── Plugin helpers (screenshot / logs) ───────────────────────────────────
+
+/**
+ * Rasterize an element to a PNG TaskAttachment via snapdom. Returns null on
+ * failure (cross-origin, test env, …) so plugins can degrade gracefully.
+ * Exported for testing.
+ */
+export async function captureElementPng(el: Element): Promise<TaskAttachment | null> {
+    try {
+        const result = await snapdom(el as HTMLElement, { fast: true });
+        const canvas = await result.toCanvas();
+        const dataUrl = canvas.toDataURL('image/png', 0.85);
+        const base64 = dataUrl.replace(/^data:image\/png;base64,/, '');
+        return {
+            id: `att_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`,
+            kind: 'screenshot',
+            data: base64,
+            width: canvas.width || 1,
+            height: canvas.height || 1,
+        };
+    } catch {
+        return null;
+    }
+}
+
+const SENSITIVE_HEADER_RE = /^(authorization|cookie|set-cookie|proxy-authorization)$/i;
+
+/** Strip bodies + auth/cookie headers from a network entry. */
+function redactNetworkEntry(e: NetworkEntry): NetworkEntry {
+    const out: NetworkEntry = { ...e };
+    delete out.requestBody;
+    delete out.responseBody;
+    delete out.requestBodyTruncated;
+    delete out.responseBodyTruncated;
+    for (const key of ['requestHeaders', 'responseHeaders'] as const) {
+        const h = out[key];
+        if (h) {
+            const safe: Record<string, string> = {};
+            for (const [k, v] of Object.entries(h)) {
+                if (!SENSITIVE_HEADER_RE.test(k)) safe[k] = v;
+            }
+            out[key] = safe;
+        }
+    }
+    return out;
+}
+
+/** Read recent buffered logs for the plugin context. Redacts network by default. */
+export function collectLogs(opts: OverlayPluginGetLogsOptions = {}): OverlayPluginLogs {
+    const store = getCaptureStore();
+    const redact = opts.redact !== false;
+    const network = store.network.tail(opts.network ?? 0);
+    return {
+        console: store.console.tail(opts.console ?? 0),
+        errors: store.errors.tail(opts.errors ?? 0),
+        network: redact ? network.map(redactNetworkEntry) : network,
+    };
+}
+
 // ─── DOM builders ────────────────────────────────────────────────────────
 
 function buildStyle(): HTMLStyleElement {
@@ -1375,6 +1576,47 @@ function buildStyle(): HTMLStyleElement {
             border-color: rgba(52, 211, 153, 0.3);
         }
 
+        .info-card .plugin-actions {
+            display: flex;
+            flex-direction: column;
+            gap: 8px;
+            margin-top: 8px;
+            padding-top: 8px;
+            border-top: 1px solid rgba(255, 255, 255, 0.06);
+        }
+        .info-card .promo {
+            margin-top: 8px;
+            text-align: center;
+        }
+        .info-card .promo-link {
+            color: #a1a1aa;
+            font-size: 11px;
+            text-decoration: none;
+            opacity: 0.7;
+        }
+        .info-card .promo-link:hover { color: #f4f4f5; opacity: 1; }
+
+        .hfe-toast {
+            position: fixed;
+            bottom: 64px;
+            left: 50%;
+            transform: translate(-50%, 8px);
+            max-width: 320px;
+            padding: 8px 14px;
+            background: #111827;
+            color: #f4f4f5;
+            border: 1px solid rgba(255, 255, 255, 0.12);
+            border-radius: 10px;
+            font: 500 12px/1.4 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+            box-shadow: 0 6px 24px rgba(0, 0, 0, 0.4);
+            opacity: 0;
+            transition: opacity 0.2s ease, transform 0.2s ease;
+            z-index: 2147483647;
+            pointer-events: none;
+        }
+        .hfe-toast[data-show="1"] { opacity: 1; transform: translate(-50%, 0); }
+        .hfe-toast[data-kind="error"] { border-color: rgba(248, 113, 113, 0.4); color: #fca5a5; }
+
         .picker-bar {
             position: fixed;
             top: 12px;
@@ -1841,6 +2083,10 @@ function buildInfoCard(): HTMLDivElement {
             <button class="secondary" data-role="view-reports" type="button">📁 My reports</button>
             <button class="secondary" data-role="copy-snapshot" type="button">📋 Copy snapshot</button>
         </div>
+        <div class="plugin-actions" data-role="plugin-actions" style="display:none"></div>
+        <div class="promo">
+            <a class="promo-link" data-role="github" href="${GITHUB_URL}" target="_blank" rel="noopener noreferrer">⭐ Harness-FE on GitHub</a>
+        </div>
     `;
     return card;
 }

package/src/pluginRegistry.test.ts

@@ -0,0 +1,76 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+    registerOverlayPlugin,
+    getOverlayPlugins,
+    subscribeOverlayPlugins,
+    drainPluginQueue,
+    __resetOverlayPlugins,
+    type OverlayPlugin,
+} from './pluginRegistry.js';
+
+const noop = () => {};
+
+function plugin(id: string, over: Partial<OverlayPlugin> = {}): OverlayPlugin {
+    return { id, label: id, onClick: noop, ...over };
+}
+
+afterEach(() => __resetOverlayPlugins());
+
+describe('pluginRegistry', () => {
+    it('registers and lists in order', () => {
+        registerOverlayPlugin(plugin('a'));
+        registerOverlayPlugin(plugin('b'));
+        expect(getOverlayPlugins().map((p) => p.id)).toEqual(['a', 'b']);
+    });
+
+    it('re-registering an id replaces, keeps position', () => {
+        registerOverlayPlugin(plugin('a', { label: 'first' }));
+        registerOverlayPlugin(plugin('b'));
+        registerOverlayPlugin(plugin('a', { label: 'second' }));
+        const ids = getOverlayPlugins().map((p) => p.id);
+        expect(ids).toEqual(['a', 'b']);
+        expect(getOverlayPlugins().find((p) => p.id === 'a')!.label).toBe('second');
+    });
+
+    it('unregister removes the plugin', () => {
+        const off = registerOverlayPlugin(plugin('a'));
+        expect(getOverlayPlugins()).toHaveLength(1);
+        off();
+        expect(getOverlayPlugins()).toHaveLength(0);
+    });
+
+    it('unregister is a no-op once the id was replaced', () => {
+        const off = registerOverlayPlugin(plugin('a', { label: 'old' }));
+        registerOverlayPlugin(plugin('a', { label: 'new' })); // replaces
+        off(); // should NOT remove the new one
+        expect(getOverlayPlugins().map((p) => p.id)).toEqual(['a']);
+        expect(getOverlayPlugins()[0].label).toBe('new');
+    });
+
+    it('rejects a plugin with no id or no onClick', () => {
+        expect(() => registerOverlayPlugin({ label: 'x' } as unknown as OverlayPlugin)).toThrow();
+        expect(() =>
+            registerOverlayPlugin({ id: 'x', label: 'x' } as unknown as OverlayPlugin),
+        ).toThrow();
+    });
+
+    it('notifies subscribers on add / replace / remove (late registration)', () => {
+        const fn = vi.fn();
+        const unsub = subscribeOverlayPlugins(fn);
+        const off = registerOverlayPlugin(plugin('a'));
+        expect(fn).toHaveBeenCalledTimes(1);
+        off();
+        expect(fn).toHaveBeenCalledTimes(2);
+        unsub();
+        registerOverlayPlugin(plugin('b'));
+        expect(fn).toHaveBeenCalledTimes(2); // no longer listening
+    });
+
+    it('drainPluginQueue registers an array and ignores junk', () => {
+        drainPluginQueue([plugin('a'), plugin('b'), null, 42, { id: '', label: 'bad' }]);
+        expect(getOverlayPlugins().map((p) => p.id)).toEqual(['a', 'b']);
+        drainPluginQueue(undefined); // no throw
+        drainPluginQueue('nope' as unknown);
+        expect(getOverlayPlugins()).toHaveLength(2);
+    });
+});