@rose42/feedback-capture 0.1.0

package/dist/plugins/core.js

@@ -0,0 +1,62 @@
+/**
+ * Run each plugin's `setup`, returning a single dispose that runs all
+ * setup-returned disposers and `dispose` hooks (idempotent).
+ */
+export function installCapturePlugins(plugins) {
+    const disposers = [];
+    let disposed = false;
+    for (const plugin of plugins) {
+        if (plugin.setup) {
+            try {
+                const fromSetup = plugin.setup();
+                if (typeof fromSetup === "function") {
+                    disposers.push(fromSetup);
+                }
+            }
+            catch {
+                // A failed setup must not block other plugins.
+            }
+        }
+        if (plugin.dispose) {
+            disposers.push(() => {
+                plugin.dispose?.();
+            });
+        }
+    }
+    return () => {
+        if (disposed)
+            return;
+        disposed = true;
+        for (let i = disposers.length - 1; i >= 0; i--) {
+            try {
+                disposers[i]();
+            }
+            catch {
+                // Ignore dispose errors.
+            }
+        }
+    };
+}
+/**
+ * Await all `collect()` calls and merge into an envelope keyed by plugin id.
+ * Skips `undefined`. On collect throw, stores `{ ok: false, error }` under that id.
+ */
+export async function collectPluginExtras(plugins) {
+    const envelope = {};
+    await Promise.all(plugins.map(async (plugin) => {
+        try {
+            const value = await plugin.collect();
+            if (value !== undefined) {
+                envelope[plugin.id] = { ok: true, value };
+            }
+        }
+        catch (error) {
+            envelope[plugin.id] = {
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }));
+    return envelope;
+}
+//# sourceMappingURL=core.js.map

package/dist/plugins/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../../src/plugins/core.ts"],"names":[],"mappings":"AAcA;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAyC;IAC7E,MAAM,SAAS,GAAsB,EAAE,CAAC;IACxC,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,IAAI,CAAC;gBACH,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC;gBACjC,IAAI,OAAO,SAAS,KAAK,UAAU,EAAE,CAAC;oBACpC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;gBAC5B,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,+CAA+C;YACjD,CAAC;QACH,CAAC;QACD,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE;gBAClB,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC;YACrB,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,GAAG,EAAE;QACV,IAAI,QAAQ;YAAE,OAAO;QACrB,QAAQ,GAAG,IAAI,CAAC;QAChB,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC/C,IAAI,CAAC;gBACH,SAAS,CAAC,CAAC,CAAE,EAAE,CAAC;YAClB,CAAC;YAAC,MAAM,CAAC;gBACP,yBAAyB;YAC3B,CAAC;QACH,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAW;IAEX,MAAM,QAAQ,GAAG,EAAgD,CAAC;IAClE,MAAM,OAAO,CAAC,GAAG,CACf,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;QAC3B,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;YACrC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACvB,QAAoC,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;YACzE,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACd,QAAoC,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG;gBACjD,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;aAC9D,CAAC;QACJ,CAAC;IACH,CAAC,CAAC,CACH,CAAC;IACF,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/plugins/elementTarget.d.ts

@@ -0,0 +1,156 @@
+import type { FeedbackCapturePlugin } from "./core.js";
+import type { FeedbackViewport } from "../types.js";
+export type ElementBoundingBox = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** Best-effort component / definition site (from framework debug + sourcemaps). */
+export type ComponentSourceLocation = {
+    name?: string;
+    fileName: string;
+    line: number;
+    column?: number;
+};
+/** Optional enrichment merged onto {@link ElementTarget} after DOM snapshot. */
+export type ElementSourceEnrichment = {
+    /**
+     * Primary focus for open-in-editor / agents (usage site when the leaf is a
+     * UI primitive; otherwise the leaf itself).
+     */
+    component?: ComponentSourceLocation;
+    /**
+     * Innermost definition when it differs from {@link component}
+     * (e.g. design-system `Link` while `component` is `Header`).
+     */
+    leaf?: ComponentSourceLocation;
+    /** Outer ancestors beyond primary (and leaf), capped by the resolver. */
+    owners?: ComponentSourceLocation[];
+};
+/** Pluggable DOM → source bridge (React, Vue, …). Failures must not reject. */
+export type ResolveElementSource = (el: Element) => Promise<ElementSourceEnrichment | undefined>;
+/** Structured DOM target for agent-facing feedback. */
+export type ElementTarget = {
+    selector: string;
+    tagName: string;
+    id?: string;
+    role?: string;
+    name?: string;
+    textSnippet?: string;
+    boundingBox: ElementBoundingBox;
+    innerHTMLSnippet?: string;
+    /** Curated computed styles when requested. */
+    styles?: Record<string, string>;
+    viewport: FeedbackViewport;
+    /**
+     * Primary component focus (usage preferred over UI primitives).
+     * Omitted when unresolved.
+     */
+    component?: ComponentSourceLocation;
+    /** Innermost definition when different from {@link component}. */
+    leaf?: ComponentSourceLocation;
+    /** Outer ancestors beyond primary / leaf (when resolved). */
+    owners?: ComponentSourceLocation[];
+};
+/**
+ * Which computed styles to attach.
+ * - `"none"` — omit (default)
+ * - `"layout"` — box model / positioning / flex-grid
+ * - `"computed"` — layout + typography / color / border / opacity
+ */
+export type ElementStylesMode = "none" | "layout" | "computed";
+export type PickElementOptions = {
+    /** Roots whose descendants are ignored (feedback UI, picker chrome). */
+    ignoreRoots?: HTMLElement[];
+    /** Optional status hint shown while picking (dodges the pointer). */
+    hint?: string;
+    /**
+     * Include a truncated `innerHTML` snippet on the target.
+     * Default: `false` (selector / role / text / bbox are usually enough for agents;
+     * HTML can be large and may contain sensitive copy).
+     */
+    includeInnerHTML?: boolean;
+    /** Max characters for `innerHTMLSnippet` when enabled (default: 500). */
+    maxInnerHTMLLength?: number;
+    /**
+     * Attach curated `getComputedStyle` values.
+     * Default: `"none"`. Prefer `"layout"` for spacing bugs; `"computed"` adds paint/type.
+     */
+    styles?: ElementStylesMode;
+    /**
+     * Optional framework bridge (e.g. `createReactSourceResolver`).
+     * Runs after the DOM snapshot; errors are swallowed.
+     */
+    resolveSource?: ResolveElementSource;
+};
+export type ElementTargetPluginOptions = {
+    /** Default ignore roots for {@link ElementTargetPlugin.pick} (feedback UI chrome). */
+    getIgnoreRoots?: () => HTMLElement[];
+    /** Default hint shown on the picker overlay. */
+    hint?: string;
+    /**
+     * Include truncated innerHTML on collected targets.
+     * Default: `false`.
+     */
+    includeInnerHTML?: boolean;
+    /** Max characters for `innerHTMLSnippet` when enabled (default: 500). */
+    maxInnerHTMLLength?: number;
+    /** Default styles mode for picks (default: `"none"`). */
+    styles?: ElementStylesMode;
+    /** Default source resolver for picks / recollect. */
+    resolveSource?: ResolveElementSource;
+};
+/**
+ * Session plugin: owns the picked target, exposes pick/clear, and collects
+ * into `envelope.elementTarget` (omitted when nothing is picked).
+ */
+export type ElementTargetPlugin = FeedbackCapturePlugin<"elementTarget", ElementTarget> & {
+    /** Open the DevTools-style picker; stores the result on success. Cancel keeps the prior target. */
+    pick: (options?: PickElementOptions) => Promise<ElementTarget | null>;
+    /** Clear the current target. */
+    clear: () => void;
+    /** Read the current target. */
+    getTarget: () => ElementTarget | undefined;
+    /** Replace the current target (custom UI / tests). */
+    setTarget: (target: ElementTarget | undefined) => void;
+};
+/** Box model / positioning / flex-grid — useful for spacing & alignment bugs. */
+export declare const LAYOUT_STYLE_PROPS: readonly ["display", "position", "top", "right", "bottom", "left", "inset", "width", "height", "min-width", "min-height", "max-width", "max-height", "margin", "margin-top", "margin-right", "margin-bottom", "margin-left", "padding", "padding-top", "padding-right", "padding-bottom", "padding-left", "box-sizing", "overflow", "overflow-x", "overflow-y", "z-index", "transform", "gap", "row-gap", "column-gap", "flex", "flex-direction", "flex-wrap", "flex-grow", "flex-shrink", "flex-basis", "align-items", "align-self", "align-content", "justify-content", "justify-items", "justify-self", "grid", "grid-template-columns", "grid-template-rows", "grid-column", "grid-row", "place-items", "place-content"];
+/** Typography / paint — useful with layout for visual polish bugs. */
+export declare const COMPUTED_EXTRA_STYLE_PROPS: readonly ["font-family", "font-size", "font-weight", "font-style", "line-height", "letter-spacing", "text-align", "text-decoration", "text-transform", "white-space", "color", "background", "background-color", "background-image", "border", "border-radius", "border-top", "border-right", "border-bottom", "border-left", "box-shadow", "opacity", "visibility", "cursor", "pointer-events"];
+/**
+ * Read a curated subset of `getComputedStyle` for agent-facing feedback.
+ * Returns `undefined` when mode is `"none"` or nothing useful was collected.
+ */
+export declare function collectComputedStyles(el: Element, mode?: ElementStylesMode): Record<string, string> | undefined;
+/** Prefer the nearest interactive ancestor for icon / SVG clicks. */
+export declare function resolveInteractiveTarget(el: Element): Element;
+/**
+ * Build a stable-ish CSS selector: #id → [data-testid] → tag:nth-of-type path.
+ */
+export declare function buildCssSelector(el: Element): string;
+export type CollectElementTargetOptions = {
+    includeInnerHTML?: boolean;
+    maxInnerHTMLLength?: number;
+    styles?: ElementStylesMode;
+    resolveSource?: ResolveElementSource;
+};
+/** Snapshot an element into an {@link ElementTarget} (DOM fields only; sync). */
+export declare function collectElementTarget(el: Element, options?: CollectElementTargetOptions): ElementTarget;
+/**
+ * DOM snapshot plus optional {@link ResolveElementSource} enrichment.
+ * Resolver errors are swallowed so pick always returns DOM metadata.
+ */
+export declare function collectElementTargetAsync(el: Element, options?: CollectElementTargetOptions): Promise<ElementTarget>;
+/**
+ * Low-level DevTools-style picker (does not store state).
+ * Prefer {@link createElementTargetPlugin} `.pick()` in session flows.
+ */
+export declare function pickElement(options?: PickElementOptions): Promise<ElementTarget | null>;
+/**
+ * Built-in plugin that owns element picking and contributes `envelope.elementTarget`.
+ * Register at session init (like console logs); call `pick()` / `clear()` from the UI.
+ */
+export declare function createElementTargetPlugin(options?: ElementTargetPluginOptions): ElementTargetPlugin;
+//# sourceMappingURL=elementTarget.d.ts.map

package/dist/plugins/elementTarget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elementTarget.d.ts","sourceRoot":"","sources":["../../src/plugins/elementTarget.ts"],"names":[],"mappings":"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"}