@runablehq/website-runtime

Drop-in visual feedback overlay for React apps. Hover over elements, click to select, leave comments with text + images. Each comment automatically captures the React component's source location via fiber _debugSource.

How It Works

1. <AgentFeedback> renders a transparent overlay via a portal on document.body
2. Hovering highlights DOM elements with a bounding box + component name
3. Clicking selects the element and opens a comment popover at the click point
4. User writes a comment (text + optional images) — an element snapshot is auto-captured
5. Numbered pin markers appear for each comment — hover to preview, click to edit
6. Bottom action bar provides undo/redo, discard, and apply
7. On "Apply", comments are sent to the parent via postMessage (iframe mode) or onSubmit callback

Integration

import { AgentFeedback } from "@runablehq/website-runtime";
import "@runablehq/website-runtime/styles";

function App() {
  return (
    <div>
      {/* your app */}
      <AgentFeedback onSubmit={(comment) => console.log(comment)} />
    </div>
  );
}

Iframe Mode

When the component runs inside an iframe, it starts disabled and waits for the parent to send a postMessage:

// Parent → enable the overlay
iframe.contentWindow.postMessage({ type: "runable:enable" }, "*");

// Parent → disable the overlay
iframe.contentWindow.postMessage({ type: "runable:disable" }, "*");

// Child → sends back on load
// { type: "runable:ready" }

// Child → sends on apply
// { type: "runable:apply", comments: FeedbackComment[] }

// Child → sends on discard
// { type: "runable:discard" }

Playground

pnpm run dev    # http://localhost:3334

• Standalone: Opens a sample site with <AgentFeedback> always enabled
• Iframe bridge: Open /parent.html to test enable/disable and message logging

Source Layout

src/
  core/
    fiber.ts              — DOM → React fiber → source location extraction
    selection.ts          — useSelection() hook — hover/click tracking
    feedback-store.tsx    — Context + useReducer state with undo/redo
    snapshot.ts           — Element screenshot capture (html-to-image)
    iframe-bridge.ts      — postMessage type definitions
    use-iframe-bridge.ts  — iframe enable/disable/apply hook
    use-placement.ts      — Smart popover positioning
  ui/
    feedback-root.tsx     — <AgentFeedback> root component + portal
    comment-popover.tsx   — New comment compose UI
    comment-markers.tsx   — Pin markers + tooltip + edit
    highlight-overlay.tsx — Selection highlight box
    edit-actions-bar.tsx  — Bottom action bar