@harness-fe/runtime 3.3.0 → 3.4.1

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,14 @@ 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;
+    /**
+     * Purpose of the current picker session:
+     * - 'copy': copy element info to clipboard for use with an agent (default)
+     * - 'report': legacy report-a-problem flow (still used internally by plugins)
+     */
+    let pickerPurpose: 'copy' | 'report' = 'copy';
 
     const setState = (next: State) => {
         state = next;
@@ -360,9 +386,29 @@ export function installOverlay(client: OverlayClient): void {
         if (!hoveredEl) return;
         lockedEl = hoveredEl;
         setHighlight(lockedEl);
-        // 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.
+        // A plugin requested the element — hand it straight to its onClick and
+        // skip all other flows.
+        if (pluginAwaitingElement) {
+            const plugin = pluginAwaitingElement;
+            pluginAwaitingElement = null;
+            const el = lockedEl;
+            lockedEl = null;
+            setState('idle');
+            void invokePlugin(plugin, el);
+            return;
+        }
+        // Copy mode: build element info and copy to clipboard for agent use.
+        if (pickerPurpose === 'copy') {
+            const el = lockedEl;
+            lockedEl = null;
+            const text = buildElementCopyText(el);
+            void copyText(text).then(() => {
+                showToast('✓ Element info copied');
+            });
+            setState('idle');
+            return;
+        }
+        // Report mode (legacy, no longer exposed in UI but kept for plugin compatibility).
         pendingAttachment = null;
         const info = questionPanel.querySelector<HTMLElement>('[data-role=info]')!;
         info.textContent = describeElement(lockedEl);
@@ -385,6 +431,8 @@ export function installOverlay(client: OverlayClient): void {
             } else if (state === 'picker' || state === 'question') {
                 lockedEl = null;
                 pendingAttachment = null;
+                pluginAwaitingElement = null;
+                pickerPurpose = 'copy';
                 setState('info');
             } else if (state === 'info') {
                 setState('idle');
@@ -454,6 +502,30 @@ export function installOverlay(client: OverlayClient): void {
         }
     };
 
+    /**
+     * Build a compact element-info block for pasting into an agent prompt.
+     * Omits HTML (too verbose); includes source location, component name, css
+     * path, and session context — enough for the agent to locate and fix the
+     * element without any further investigation.
+     */
+    const buildElementCopyText = (el: Element): string => {
+        const tag = el.tagName.toLowerCase();
+        const comp = el.getAttribute('data-morphix-comp');
+        const loc = el.getAttribute('data-morphix-loc');
+        const css = buildCssPath(el);
+        const lines: string[] = [];
+        lines.push(`### Element context`);
+        lines.push('');
+        if (comp) lines.push(`- component: \`${comp}\``);
+        if (loc) lines.push(`- source: \`${loc}\``);
+        lines.push(`- tag: \`${tag}\``);
+        lines.push(`- css: \`${css}\``);
+        lines.push(`- project: \`${client.projectId}\`${client.displayName ? ` (${client.displayName})` : ''}`);
+        lines.push(`- session: \`${client.sessionId}\``);
+        lines.push(`- url: ${location.href}`);
+        return lines.join('\n') + '\n';
+    };
+
     const buildSnapshot = (): string => {
         const lines: string[] = [];
         lines.push(`### Harness-FE snapshot`);
@@ -469,6 +541,109 @@ 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;
+                    pickerPurpose = 'report'; // plugins use the legacy element-selection flow
+                    const label = pickerBar.querySelector<HTMLElement>('[data-role=picker-label]');
+                    if (label) label.textContent = '🎯 Click an element';
+                    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;
@@ -671,7 +846,10 @@ export function installOverlay(client: OverlayClient): void {
 
     infoCard.querySelector('[data-role=close]')!.addEventListener('click', () => setState('idle'));
 
-    infoCard.querySelector('[data-role=report]')!.addEventListener('click', () => {
+    infoCard.querySelector('[data-role=pick-element]')!.addEventListener('click', () => {
+        pickerPurpose = 'copy';
+        const label = pickerBar.querySelector<HTMLElement>('[data-role=picker-label]');
+        if (label) label.textContent = '🔍 Click element to copy info';
         setState('picker');
     });
 
@@ -680,19 +858,12 @@ export function installOverlay(client: OverlayClient): void {
         void copyText(buildSnapshot(), btn);
     });
 
-    infoCard.querySelector('[data-role=view-reports]')!.addEventListener('click', () => {
-        setState('reports');
-    });
-
     // "Open dashboard" — derive the daemon's dashboard URL from mcpUrl and
     // pop it in a new tab, deep-linked to this session. Show the button
     // only when we actually know the daemon address (mcpUrl was supplied by
     // 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 +879,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 +910,8 @@ export function installOverlay(client: OverlayClient): void {
 
     pickerBar.querySelector('[data-role=cancel]')!.addEventListener('click', () => {
         lockedEl = null;
+        pluginAwaitingElement = null;
+        pickerPurpose = 'copy';
         setState('info');
     });
 
@@ -1148,6 +1333,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 +1619,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;
@@ -1829,18 +2114,21 @@ function buildInfoCard(): HTMLDivElement {
             <div class="row"><span class="key">url</span><span class="pill url" data-role="url"></span></div>
         </div>
         <div class="actions">
-            <button class="primary" data-role="report" type="button">
-                <span class="icon">🎯</span>
-                <span class="label">Report a problem</span>
-                <span class="hint">Pick an element →</span>
+            <button class="primary" data-role="pick-element" type="button">
+                <span class="icon">🔍</span>
+                <span class="label">Copy element info</span>
+                <span class="hint">pick element →</span>
             </button>
             <button class="secondary" data-role="open-dashboard" type="button" style="display:none">
                 <span class="icon">↗</span>
                 <span>Open dashboard</span>
             </button>
-            <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;
 }
@@ -1867,7 +2155,7 @@ function buildPickerBar(): HTMLDivElement {
     const bar = document.createElement('div');
     bar.className = 'picker-bar';
     bar.innerHTML = `
-        <span class="label">🎯 Click an element to flag it</span>
+        <span class="label" data-role="picker-label">🔍 Click element to copy info</span>
         <span class="hint">esc to cancel</span>
         <button data-role="cancel" type="button">Cancel</button>
     `;

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);
+    });
+});