@david-xpn/llm-ui-feedback 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 david-xpn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,177 @@
+# @david-xpn/llm-ui-feedback
+
+Drop-in React feedback widget that captures component context for LLM consumption.
+
+Users click on any element in your app, leave a comment, and the widget captures a rich context bundle — React component tree, props, screenshot with marker, and a pre-formatted LLM prompt — ready to paste into Claude, ChatGPT, or any LLM chat.
+
+## Features
+
+- **One-line integration** — add `<FeedbackWidget />` to your root, done
+- **React component tree capture** — walks the fiber tree to extract component names and props
+- **Screenshot with X marker** — captures the viewport and marks the clicked element
+- **LLM-ready prompt** — generates a structured prompt with page URL, component path, props, element text, and user comment
+- **Copy & download** — copy the prompt to clipboard and download the screenshot
+- **localStorage persistence** — no backend needed, all data stays client-side
+- **Feedback list panel** — view, copy, and manage all saved feedback entries
+- **Configurable** — position, color, and keyboard shortcut
+
+## Install
+
+```bash
+npm install @david-xpn/llm-ui-feedback
+```
+
+## Quick Start
+
+```tsx
+import { FeedbackWidget } from '@david-xpn/llm-ui-feedback';
+
+function App() {
+  return (
+    <>
+      <YourApp />
+      <FeedbackWidget />
+    </>
+  );
+}
+```
+
+That's it. A floating `+` button appears in the bottom-right corner. Click it to enter pick mode, click any element, leave a comment, and get an LLM-ready prompt.
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Corner position for the floating button |
+| `buttonColor` | `string` | `'#3b82f6'` | Hex color for the FAB button |
+| `hotkey` | `string` | `undefined` | Keyboard shortcut to toggle pick mode (e.g. `'Alt+F'`) |
+
+### Example with all props
+
+```tsx
+<FeedbackWidget
+  position="bottom-left"
+  buttonColor="#10b981"
+  hotkey="Alt+F"
+/>
+```
+
+## How It Works
+
+1. User clicks the `+` floating button to enter **pick mode**
+2. User clicks any element on the page
+3. The widget captures:
+   - **Component path** — React fiber tree walk (e.g. `App > Layout > Dashboard > MetricCard`)
+   - **Props** — scalar props (strings, numbers, booleans) from each component
+   - **Element text** — innerText of the clicked element (truncated to 100 chars)
+   - **Page URL** — current `window.location.href`
+   - **Screenshot** — viewport capture via `html2canvas-pro` with a red X at the click position
+4. User types a comment and saves
+5. The entry is stored in `localStorage` with a pre-formatted LLM prompt
+6. User can **copy the prompt** and **download the screenshot** to paste into any LLM
+
+### Example prompt output
+
+```
+Page: https://myapp.com/dashboard/metrics
+Component: App > Layout > Dashboard > MetricCard
+Props:
+  MetricCard: {"metricId":"revenue","period":"Q4"}
+Element text: "Revenue: $1.2M"
+
+User feedback: "This number looks wrong, should be $1.4M"
+
+Screenshot attached with red X marking the clicked element.
+```
+
+## Exported API
+
+```ts
+// Components
+import { FeedbackWidget } from '@david-xpn/llm-ui-feedback';
+
+// Types
+import type {
+  FeedbackWidgetProps,
+  FeedbackEntry,
+  CapturedContext,
+  ComponentInfo,
+  WidgetPosition,
+} from '@david-xpn/llm-ui-feedback';
+
+// Storage utilities (for programmatic access)
+import {
+  loadEntries,
+  deleteEntry,
+  clearEntries,
+} from '@david-xpn/llm-ui-feedback';
+```
+
+### Storage utilities
+
+| Function | Description |
+| --- | --- |
+| `loadEntries()` | Returns all saved `FeedbackEntry[]` from localStorage |
+| `deleteEntry(id)` | Deletes a single entry by ID |
+| `clearEntries()` | Removes all feedback entries |
+
+## Production Setup
+
+In production builds, minifiers rename component functions (`MetricCard` becomes `t`), which makes the component path useless. Configure your bundler to preserve function names:
+
+### Vite
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  esbuild: {
+    keepNames: true,
+  },
+});
+```
+
+### webpack (Terser)
+
+```js
+// webpack.config.js
+module.exports = {
+  optimization: {
+    minimizer: [
+      new TerserPlugin({
+        terserOptions: { keep_fnames: true },
+      }),
+    ],
+  },
+};
+```
+
+### Next.js
+
+```js
+// next.config.js
+module.exports = {
+  webpack: (config) => {
+    const terser = config.optimization?.minimizer?.find(
+      (p) => p.constructor.name === 'TerserPlugin'
+    );
+    if (terser) {
+      terser.options.terserOptions = {
+        ...terser.options.terserOptions,
+        keep_fnames: true,
+      };
+    }
+    return config;
+  },
+};
+```
+
+See [docs/production-setup.md](docs/production-setup.md) for more bundler configurations.
+
+## Requirements
+
+- React 18+
+- Browser environment (uses `localStorage`, `document`, `html2canvas-pro`)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,42 @@
+import React from 'react';
+
+type WidgetPosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+interface ComponentInfo {
+    name: string;
+    props: Record<string, unknown>;
+}
+interface FeedbackEntry {
+    id: string;
+    timestamp: string;
+    url: string;
+    componentPath: string;
+    components: ComponentInfo[];
+    elementText: string;
+    comment: string;
+    screenshot: string | null;
+    prompt: string;
+}
+interface CapturedContext {
+    url: string;
+    componentPath: string;
+    components: ComponentInfo[];
+    elementText: string;
+    clickX: number;
+    clickY: number;
+}
+
+interface FeedbackWidgetProps {
+    /** Corner position for the floating buttons. Default: 'bottom-right' */
+    position?: WidgetPosition;
+    /** Hex color for the FAB and badge accent. Default: '#3b82f6' */
+    buttonColor?: string;
+    /** Keyboard shortcut to toggle pick mode, e.g. 'Alt+F'. No default (opt-in only). */
+    hotkey?: string;
+}
+declare function FeedbackWidget({ position, buttonColor, hotkey, }?: FeedbackWidgetProps): React.ReactPortal;
+
+declare function loadEntries(): FeedbackEntry[];
+declare function deleteEntry(id: string): void;
+declare function clearEntries(): void;
+
+export { type CapturedContext, type ComponentInfo, type FeedbackEntry, FeedbackWidget, type FeedbackWidgetProps, type WidgetPosition, clearEntries, deleteEntry, loadEntries };

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+import React from 'react';
+
+type WidgetPosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+interface ComponentInfo {
+    name: string;
+    props: Record<string, unknown>;
+}
+interface FeedbackEntry {
+    id: string;
+    timestamp: string;
+    url: string;
+    componentPath: string;
+    components: ComponentInfo[];
+    elementText: string;
+    comment: string;
+    screenshot: string | null;
+    prompt: string;
+}
+interface CapturedContext {
+    url: string;
+    componentPath: string;
+    components: ComponentInfo[];
+    elementText: string;
+    clickX: number;
+    clickY: number;
+}
+
+interface FeedbackWidgetProps {
+    /** Corner position for the floating buttons. Default: 'bottom-right' */
+    position?: WidgetPosition;
+    /** Hex color for the FAB and badge accent. Default: '#3b82f6' */
+    buttonColor?: string;
+    /** Keyboard shortcut to toggle pick mode, e.g. 'Alt+F'. No default (opt-in only). */
+    hotkey?: string;
+}
+declare function FeedbackWidget({ position, buttonColor, hotkey, }?: FeedbackWidgetProps): React.ReactPortal;
+
+declare function loadEntries(): FeedbackEntry[];
+declare function deleteEntry(id: string): void;
+declare function clearEntries(): void;
+
+export { type CapturedContext, type ComponentInfo, type FeedbackEntry, FeedbackWidget, type FeedbackWidgetProps, type WidgetPosition, clearEntries, deleteEntry, loadEntries };