npm - @harness-fe/runtime - Versions diffs - 3.3.0 → 3.4.1 - Mend

@harness-fe/runtime 3.3.0 → 3.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/dist/index.d.ts +2 -0
package/dist/index.js +9 -0
package/dist/overlay.d.ts +9 -0
package/dist/overlay.js +291 -17
package/dist/pluginRegistry.d.ts +127 -0
package/dist/pluginRegistry.js +80 -0
package/package.json +1 -1
package/src/index.ts +29 -0
package/src/overlay.test.ts +143 -37
package/src/overlay.ts +306 -18
package/src/pluginRegistry.test.ts +76 -0
package/src/pluginRegistry.ts +189 -0

package/dist/index.d.ts CHANGED Viewed

@@ -6,3 +6,5 @@
  */
 export { RuntimeClient, tryInheritFromParent } from './client.js';
 export type { ClientOptions, ParentInheritance } from './client.js';
+export { registerOverlayPlugin, getOverlayPlugins, subscribeOverlayPlugins, } from './pluginRegistry.js';
+export type { OverlayPlugin, OverlayPluginContext, OverlayPluginSelectedElement, OverlayPluginSelector, OverlayPluginLogs, OverlayPluginGetLogsOptions, } from './pluginRegistry.js';

package/dist/index.js CHANGED Viewed

@@ -6,9 +6,17 @@
  */
 import { installOverlay } from './overlay.js';
 import { RuntimeClient, readInjectedConfig } from './client.js';
+import { registerOverlayPlugin, drainPluginQueue, } from './pluginRegistry.js';
+// Informational; keep in sync with package.json on release.
+const VERSION = '3.3.0';
 const w = window;
 if (typeof window !== 'undefined' && !w.__harness_fe_started__) {
     w.__harness_fe_started__ = true;
+    // Public global for runtime plugin registration. Works before or after the
+    // overlay mounts — the registry buffers and the overlay subscribes.
+    w.HarnessFE = { registerOverlayPlugin, version: VERSION };
+    // Drain any plugins queued before the runtime loaded.
+    drainPluginQueue(w.__HARNESS_FE_PLUGINS__);
     const cfg = readInjectedConfig();
     const client = new RuntimeClient(cfg);
     client.start();
@@ -21,3 +29,4 @@ if (typeof window !== 'undefined' && !w.__harness_fe_started__) {
     w.__hfe_session_id__ = client.sessionId;
 }
 export { RuntimeClient, tryInheritFromParent } from './client.js';
+export { registerOverlayPlugin, getOverlayPlugins, subscribeOverlayPlugins, } from './pluginRegistry.js';

package/dist/overlay.d.ts CHANGED Viewed

@@ -14,6 +14,7 @@
  * or out. State machine: idle → info → (picker → question) → flash → idle.
  */
 import { type TaskAttachment } from '@harness-fe/protocol';
+import { type OverlayPluginLogs, type OverlayPluginGetLogsOptions } from './pluginRegistry.js';
 export interface OverlayClient {
     readonly projectId: string;
     readonly buildId?: string;
@@ -60,6 +61,14 @@ export declare function replayStrokes(ctx: CanvasRenderingContext2D, bgCanvas: H
  * Exported for testing.
  */
 export declare function finalizeAnnotation(): Promise<TaskAttachment | null>;
+/**
+ * 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 declare function captureElementPng(el: Element): Promise<TaskAttachment | null>;
+/** Read recent buffered logs for the plugin context. Redacts network by default. */
+export declare function collectLogs(opts?: OverlayPluginGetLogsOptions): OverlayPluginLogs;
 /**
  * Best-effort CSS path. Depth cap 12, id anchor short-circuits, ` >>> `
  * separates shadow-DOM boundaries.

package/dist/overlay.js CHANGED Viewed

@@ -13,9 +13,14 @@
  * Single Shadow DOM root attached to <body>; host page styles never leak in
  * or out. State machine: idle → info → (picker → question) → flash → idle.
  */
-import { EVENT_NAME } from '@harness-fe/protocol';
+import { EVENT_NAME, } 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, } 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;
 // Internal instrumentation attributes injected by our build plugin. Must be
@@ -242,6 +247,14 @@ export function installOverlay(client) {
     let statusPollTimer;
     /** Flattened PNG from the annotate step; null if user skipped. */
     let pendingAttachment = null;
+    /** Set while the picker is collecting an element for a `requiresElement` plugin. */
+    let pluginAwaitingElement = 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';
     const setState = (next) => {
         state = next;
         infoCard.style.display = next === 'info' ? 'flex' : 'none';
@@ -314,9 +327,29 @@ export function installOverlay(client) {
             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('[data-role=info]');
         info.textContent = describeElement(lockedEl);
@@ -339,6 +372,8 @@ export function installOverlay(client) {
             else if (state === 'picker' || state === 'question') {
                 lockedEl = null;
                 pendingAttachment = null;
+                pluginAwaitingElement = null;
+                pickerPurpose = 'copy';
                 setState('info');
             }
             else if (state === 'info') {
@@ -409,6 +444,31 @@ export function installOverlay(client) {
             }, 1200);
         }
     };
+    /**
+     * 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) => {
+        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 = [];
+        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 = () => {
         const lines = [];
         lines.push(`### Harness-FE snapshot`);
@@ -425,6 +485,107 @@ export function installOverlay(client) {
         lines.push(`- daemon: ${client.getConnectionState()}`);
         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, kind = 'ok') => {
+        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) => {
+        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, selectedEl) => {
+        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 = () => {
+        const slot = infoCard.querySelector('[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('[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 = null;
     let deleteConfirmId = null;
@@ -637,25 +798,23 @@ export function installOverlay(client) {
         setState(state === 'idle' ? 'info' : 'idle');
     });
     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('[data-role=picker-label]');
+        if (label)
+            label.textContent = '🔍 Click element to copy info';
         setState('picker');
     });
     infoCard.querySelector('[data-role=copy-snapshot]').addEventListener('click', (ev) => {
         const btn = ev.currentTarget;
         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('[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`;
@@ -671,6 +830,19 @@ export function installOverlay(client) {
             });
         }
     }
+    // GitHub promo link — anchor navigates natively; this fallback covers
+    // sandboxed iframes / popup blockers by copying the URL instead.
+    infoCard.querySelector('[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);
+        }
+    });
     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());
@@ -688,6 +860,8 @@ export function installOverlay(client) {
     }
     pickerBar.querySelector('[data-role=cancel]').addEventListener('click', () => {
         lockedEl = null;
+        pluginAwaitingElement = null;
+        pickerPurpose = 'copy';
         setState('info');
     });
     questionPanel.querySelector('[data-role=cancel]').addEventListener('click', () => {
@@ -1037,6 +1211,62 @@ export async function finalizeAnnotation() {
     resetAnnotateStrokes();
     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) {
+    try {
+        const result = await snapdom(el, { 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) {
+    const out = { ...e };
+    delete out.requestBody;
+    delete out.responseBody;
+    delete out.requestBodyTruncated;
+    delete out.responseBodyTruncated;
+    for (const key of ['requestHeaders', 'responseHeaders']) {
+        const h = out[key];
+        if (h) {
+            const safe = {};
+            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 = {}) {
+    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() {
     const style = document.createElement('style');
@@ -1263,6 +1493,47 @@ function buildStyle() {
             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;
@@ -1715,18 +1986,21 @@ function buildInfoCard() {
             <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;
 }
@@ -1751,7 +2025,7 @@ function buildPickerBar() {
     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/dist/pluginRegistry.d.ts ADDED Viewed

@@ -0,0 +1,127 @@
+/**
+ * Overlay plugin registry.
+ *
+ * Lets developers extend the in-page "H" overlay with their own action buttons
+ * — e.g. "send this scene to Slack" / "create a Jira issue" — without forking
+ * `@harness-fe/runtime`. A plugin is just a button label + an `onClick(ctx)`
+ * handler; the handler receives an {@link OverlayPluginContext} with on-demand,
+ * redaction-aware access to the current scene, logs, screenshot, and selected
+ * element.
+ *
+ * Registration order doesn't matter: plugins registered before the overlay
+ * mounts are buffered here, and the overlay subscribes so anything registered
+ * later renders immediately. See `index.ts` for the `window.HarnessFE` global
+ * and the `window.__HARNESS_FE_PLUGINS__` pre-boot queue.
+ */
+import type { PageLoadPayload, ConsoleEntry, NetworkEntry, ErrorEntry, TaskAttachment } from '@harness-fe/protocol';
+/** Selector descriptor for a picked element (mirrors TaskSubmitPayload.selector). */
+export interface OverlayPluginSelector {
+    /** Source location `file:line:col` from the build transform, if present. */
+    loc?: string;
+    /** Component display name from the build transform, if present. */
+    comp?: string;
+    /** Best-effort CSS path. */
+    css: string;
+}
+/** The element the user picked (only present for `requiresElement` plugins). */
+export interface OverlayPluginSelectedElement {
+    /** Live DOM node. */
+    el: Element;
+    selector: OverlayPluginSelector;
+    /** outerHTML with internal instrumentation attrs stripped + truncated. */
+    outerHTML: string;
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export interface OverlayPluginLogs {
+    console: ConsoleEntry[];
+    network: NetworkEntry[];
+    errors: ErrorEntry[];
+}
+export interface OverlayPluginGetLogsOptions {
+    /** Max console entries (newest last). Default 0 — pass a count to include. */
+    console?: number;
+    /** Max network entries. Default 0. */
+    network?: number;
+    /** Max error entries. Default 0. */
+    errors?: number;
+    /**
+     * When `true` (the default), network entries are reduced to metadata:
+     * request/response bodies are dropped and `authorization` / `cookie`
+     * headers are stripped. Set `false` to receive raw entries — only do this
+     * when you control the destination, as bodies may contain secrets.
+     */
+    redact?: boolean;
+}
+/**
+ * Per-invocation context handed to a plugin's `onClick`. Getters are lazy: the
+ * snapshot / logs / screenshot are only computed when you call them, so a
+ * plugin pays for exactly what it uses.
+ */
+export interface OverlayPluginContext {
+    readonly projectId: string;
+    readonly displayName?: string;
+    readonly buildId?: string;
+    readonly parentProjectId?: string;
+    readonly sessionId: string;
+    readonly tabId: string;
+    readonly visitorId?: string;
+    readonly userId?: string;
+    /** `location.href` at click time. */
+    readonly url: string;
+    readonly connectionState: 'connecting' | 'open' | 'closed';
+    /** Deep link to this session in the daemon dashboard, if the address is known. */
+    readonly dashboardUrl?: string;
+    /** Present only for plugins declared with `requiresElement: true`. */
+    readonly selectedElement?: OverlayPluginSelectedElement;
+    /** Shareable markdown summary (project / build / session / tab / url / time / conn). */
+    snapshotMarkdown(): string;
+    /** Structured page-load snapshot: page / viewport / storage / performance. */
+    snapshot(): PageLoadPayload;
+    /** Recent buffered logs. Redacted by default — see {@link OverlayPluginGetLogsOptions}. */
+    getLogs(opts?: OverlayPluginGetLogsOptions): OverlayPluginLogs;
+    /** Rasterize an element (default: the picked element, else `document.body`) to a PNG attachment. */
+    captureScreenshot(el?: Element): Promise<TaskAttachment | null>;
+    /** Daemon RPC over the whitelisted channel (e.g. `tasks.mine`). Undefined if unavailable. */
+    query?: <TResult = unknown>(method: string, args?: unknown) => Promise<TResult>;
+    /** Copy text to the clipboard (best-effort). */
+    copyToClipboard(text: string): Promise<void>;
+    /** Show a brief feedback toast on the overlay. */
+    toast(message: string, kind?: 'ok' | 'error'): void;
+}
+export interface OverlayPlugin {
+    /** Unique id. Re-registering the same id replaces the previous plugin. */
+    id: string;
+    /** Button label shown in the info card. */
+    label: string;
+    /** Optional leading icon (emoji or single char). */
+    icon?: string;
+    /**
+     * When `true`, clicking the button first enters element-picker mode; the
+     * picked element is then available as `ctx.selectedElement` in `onClick`.
+     */
+    requiresElement?: boolean;
+    /** Invoked when the button is clicked. May be async; rejections are toasted. */
+    onClick(ctx: OverlayPluginContext): void | Promise<void>;
+}
+/**
+ * Register an overlay plugin. Returns an unregister function (handy for HMR
+ * cleanup). Registering an id that already exists replaces it.
+ */
+export declare function registerOverlayPlugin(plugin: OverlayPlugin): () => void;
+/** Current plugins, in registration order. */
+export declare function getOverlayPlugins(): OverlayPlugin[];
+/** Subscribe to registry changes (add / replace / remove). Returns an unsubscribe fn. */
+export declare function subscribeOverlayPlugins(fn: () => void): () => void;
+/**
+ * Drain a pre-boot queue of plugins. Developers whose script may run before the
+ * runtime loads can push plain plugin objects onto
+ * `window.__HARNESS_FE_PLUGINS__`; `index.ts` calls this once on boot.
+ */
+export declare function drainPluginQueue(queue: unknown): void;
+/** Test-only: clear all plugins and listeners. */
+export declare function __resetOverlayPlugins(): void;

package/dist/pluginRegistry.js ADDED Viewed

@@ -0,0 +1,80 @@
+/**
+ * Overlay plugin registry.
+ *
+ * Lets developers extend the in-page "H" overlay with their own action buttons
+ * — e.g. "send this scene to Slack" / "create a Jira issue" — without forking
+ * `@harness-fe/runtime`. A plugin is just a button label + an `onClick(ctx)`
+ * handler; the handler receives an {@link OverlayPluginContext} with on-demand,
+ * redaction-aware access to the current scene, logs, screenshot, and selected
+ * element.
+ *
+ * Registration order doesn't matter: plugins registered before the overlay
+ * mounts are buffered here, and the overlay subscribes so anything registered
+ * later renders immediately. See `index.ts` for the `window.HarnessFE` global
+ * and the `window.__HARNESS_FE_PLUGINS__` pre-boot queue.
+ */
+const plugins = new Map();
+const listeners = new Set();
+function notify() {
+    for (const fn of listeners) {
+        try {
+            fn();
+        }
+        catch {
+            /* a bad listener must not break registration */
+        }
+    }
+}
+/**
+ * Register an overlay plugin. Returns an unregister function (handy for HMR
+ * cleanup). Registering an id that already exists replaces it.
+ */
+export function registerOverlayPlugin(plugin) {
+    if (!plugin || typeof plugin.id !== 'string' || plugin.id === '') {
+        throw new Error('registerOverlayPlugin: plugin.id is required');
+    }
+    if (typeof plugin.onClick !== 'function') {
+        throw new Error(`registerOverlayPlugin: plugin "${plugin.id}" needs an onClick handler`);
+    }
+    plugins.set(plugin.id, plugin);
+    notify();
+    return () => {
+        if (plugins.get(plugin.id) === plugin) {
+            plugins.delete(plugin.id);
+            notify();
+        }
+    };
+}
+/** Current plugins, in registration order. */
+export function getOverlayPlugins() {
+    return [...plugins.values()];
+}
+/** Subscribe to registry changes (add / replace / remove). Returns an unsubscribe fn. */
+export function subscribeOverlayPlugins(fn) {
+    listeners.add(fn);
+    return () => {
+        listeners.delete(fn);
+    };
+}
+/**
+ * Drain a pre-boot queue of plugins. Developers whose script may run before the
+ * runtime loads can push plain plugin objects onto
+ * `window.__HARNESS_FE_PLUGINS__`; `index.ts` calls this once on boot.
+ */
+export function drainPluginQueue(queue) {
+    if (!Array.isArray(queue))
+        return;
+    for (const p of queue) {
+        try {
+            registerOverlayPlugin(p);
+        }
+        catch {
+            /* skip malformed queued entries */
+        }
+    }
+}
+/** Test-only: clear all plugins and listeners. */
+export function __resetOverlayPlugins() {
+    plugins.clear();
+    listeners.clear();
+}