@rose42/t3-feedback 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,464 @@
+/**
+ * Seamless Open-in-T3 handoff from `GET/POST /__t3-feedback/open`.
+ * Open `pairUrl` first (auto-pairs), then navigate to `threadUrl`.
+ */
+export type T3FeedbackOpenHandoff = {
+    pairUrl: string;
+    threadUrl: string;
+    environmentId: string;
+};
+/** Result returned by the Vite middleware after a successful T3 turn. */
+export type FeedbackSendResult = {
+    threadId: string;
+    threadTitle: string;
+    projectId: string;
+    /** T3 environment id for deep links (`/$environmentId/$threadId`). */
+    environmentId?: string;
+    /** Human label from `/.well-known/t3/environment` (helps spot wrong-server wiring). */
+    environmentLabel?: string;
+    sequence: number;
+    openUrl: string;
+};
+/** Live / inferred agent activity for a feedback thread. */
+export type ThreadProbeState = "working" | "settled" | "unknown";
+export type ThreadProbeResult = {
+    threadId: string;
+    state: ThreadProbeState;
+};
+/** GET /__t3-feedback/threads?ids=… response body. */
+export type ThreadsProbeResponse = {
+    threads: ThreadProbeResult[];
+};
+/** One project thread from GET /__t3-feedback/threads (no `ids`). */
+export type ThreadListItem = {
+    threadId: string;
+    title: string;
+    state: ThreadProbeState;
+    /** ISO timestamp from the shell snapshot when present. */
+    updatedAt?: string;
+};
+/** GET /__t3-feedback/threads (no `ids`) response body. */
+export type ThreadsListResponse = {
+    threads: ThreadListItem[];
+};
+/** Per-thread result from POST /__t3-feedback/settle. */
+export type ThreadSettleResult = {
+    threadId: string;
+    /** True when settle dispatched, or the thread was already gone from the shell. */
+    ok: boolean;
+    /** Thread missing from the shell snapshot (treated as already settled). */
+    skipped?: boolean;
+    error?: string;
+};
+/** POST /__t3-feedback/settle response body. */
+export type ThreadsSettleResponse = {
+    threads: ThreadSettleResult[];
+};
+/**
+ * How the client reuses T3 threads across sends.
+ * - `"ask"`: New vs Continue control; soft-defaults to Continue when same route /
+ *   report type within a short TTL (default)
+ * - `"session-route"`: always reuse while `sessionStorage` + pathname match
+ * - `"never"`: new thread every send
+ */
+export type T3FeedbackThreadReuse = "ask" | "session-route" | "never";
+/** When the floating ✎ button is shown. Keyboard shortcut always works. */
+export type T3FeedbackFabVisibility = "mobile" | "always" | "never";
+/** Fixed offsets from the viewport edges (px numbers or CSS lengths). */
+export type T3FeedbackFabPosition = {
+    top?: number | string;
+    right?: number | string;
+    bottom?: number | string;
+    left?: number | string;
+};
+/** Floating action button appearance for the injected / mounted client. */
+export type T3FeedbackFabOptions = {
+    /**
+     * Default: `"mobile"` — show only at or below `mobileMaxWidth`.
+     * `"always"` — all viewports; `"never"` — omit the button (shortcut still works).
+     */
+    visibility?: T3FeedbackFabVisibility;
+    /**
+     * Max viewport width (px) treated as mobile when `visibility` is `"mobile"`.
+     * Default: `719`.
+     */
+    mobileMaxWidth?: number;
+    /**
+     * Edge offsets. Default: `{ right: 16, bottom: 16 }`.
+     * Only provided edges are applied (e.g. `{ top: 12, left: 12 }` pins top-left).
+     */
+    position?: T3FeedbackFabPosition;
+    /** FAB diameter (px number or CSS length). Default: `44`. */
+    size?: number | string;
+};
+/** Resolved FAB options embedded in the client config. */
+export type T3FeedbackFabConfig = {
+    visibility: T3FeedbackFabVisibility;
+    mobileMaxWidth: number;
+    position: T3FeedbackFabPosition;
+    size: number | string;
+};
+export declare const DEFAULT_FAB_CONFIG: T3FeedbackFabConfig;
+export declare function resolveFabConfig(fab?: T3FeedbackFabOptions): T3FeedbackFabConfig;
+/** Built-in emoji glyphs for Bug / Feedback / Suggestion when using `"emoji"` or a partial map. */
+export declare const DEFAULT_REPORT_TYPE_EMOJIS: {
+    readonly bug: "🐛";
+    readonly feedback: "💬";
+    readonly suggestion: "💡";
+};
+/**
+ * Custom emoji (or other short glyph) per report type.
+ * Prefer UI labels (`Bug` / `Feedback` / `Suggestion`); lowercase keys also work.
+ * Omitted keys fall back to {@link DEFAULT_REPORT_TYPE_EMOJIS}.
+ */
+export type T3FeedbackReportTypeGlyphMap = {
+    Bug?: string;
+    Feedback?: string;
+    Suggestion?: string;
+    bug?: string;
+    feedback?: string;
+    suggestion?: string;
+};
+/** Normalized custom glyphs after {@link resolveReportTypeGlyph}. */
+export type T3FeedbackReportTypeGlyphCustom = {
+    bug: string;
+    feedback: string;
+    suggestion: string;
+};
+/**
+ * How report-type affordances (Bug / Feedback / Suggestion) are drawn in the overlay
+ * and prefixed on new T3 thread titles.
+ * - `"icon"` — SVG icons in the UI; textual titles (`Bug: …`)
+ * - `"emoji"` — built-in emojis in the UI and in new thread titles (`🐛: …`)
+ * - map — custom glyphs, e.g. `{ Bug: "🐛", Feedback: "💬", Suggestion: "💡" }`
+ */
+export type T3FeedbackReportTypeGlyph = "icon" | "emoji" | T3FeedbackReportTypeGlyphMap;
+/** Value embedded in the client config / used when rendering glyphs. */
+export type T3FeedbackReportTypeGlyphResolved = "icon" | "emoji" | T3FeedbackReportTypeGlyphCustom;
+export declare const DEFAULT_REPORT_TYPE_GLYPH: T3FeedbackReportTypeGlyphResolved;
+export declare function resolveReportTypeGlyph(value?: T3FeedbackReportTypeGlyph): T3FeedbackReportTypeGlyphResolved;
+/**
+ * Keyboard chord that opens the feedback panel.
+ * When the whole `shortcut` option is omitted, defaults to Ctrl/⌘+Shift+F.
+ * When `shortcut` is set, omitted `mod` / `shift` / `alt` default to `false`.
+ */
+export type T3FeedbackShortcutOptions = {
+    /** Matched case-insensitively against `event.key`. Default: `"f"`. */
+    key?: string;
+    /**
+     * Require Ctrl (Windows/Linux) or ⌘ (macOS) — `ctrlKey || metaKey`.
+     * Default when `shortcut` is set: `false`. Plugin-wide default chord uses `true`.
+     */
+    mod?: boolean;
+    /**
+     * Require Shift.
+     * Default when `shortcut` is set: `false`. Plugin-wide default chord uses `true`.
+     */
+    shift?: boolean;
+    /** Require Alt/Option. Default: `false`. */
+    alt?: boolean;
+};
+/** Resolved shortcut embedded in the client config. */
+export type T3FeedbackShortcutConfig = {
+    key: string;
+    mod: boolean;
+    shift: boolean;
+    alt: boolean;
+};
+export declare const DEFAULT_SHORTCUT: T3FeedbackShortcutConfig;
+/** Default chord for element picking: Ctrl/⌘+Shift+E. */
+export declare const DEFAULT_PICK_SHORTCUT: T3FeedbackShortcutConfig;
+/** Default chord for Capture screenshot: Ctrl/⌘+Shift+S. */
+export declare const DEFAULT_SCREENSHOT_SHORTCUT: T3FeedbackShortcutConfig;
+/** Default chord for Record (frame burst): Ctrl/⌘+Shift+R. */
+export declare const DEFAULT_RECORD_SHORTCUT: T3FeedbackShortcutConfig;
+/** What to do after a successful element pick. */
+export type T3FeedbackAfterPick = "none" | "capture" | "crop";
+/**
+ * How Capture / Change-region attaches screenshots.
+ * - `"ui"` — attach full image, enable crop on thumbs (default); Capture focuses
+ *   the new thumb's crop control so Enter opens the overlay (never auto-opens)
+ * - `"auto"` — silently crop to the picked element when present, else full image
+ * - `"none"` — always attach the full image (no crop UI)
+ */
+export type T3FeedbackScreenshotCrop = "ui" | "auto" | "none";
+/** Element-pick behavior for the injected / mounted client. */
+export type T3FeedbackPickOptions = {
+    /**
+     * Chord that starts element picking immediately.
+     * Default when omitted: Ctrl/⌘+Shift+E. Set `false` to disable.
+     * When set as an object, omitted modifiers default to `false` (same as `shortcut`).
+     */
+    shortcut?: T3FeedbackShortcutOptions | false;
+    /**
+     * After a successful pick:
+     * - `"none"` — store the target only
+     * - `"capture"` — take a full-tab screenshot (no crop UI)
+     * - `"crop"` — take a screenshot and silently crop to the element (default)
+     */
+    afterPick?: T3FeedbackAfterPick;
+    /** CSS-pixel padding around the element when `afterPick` is `"crop"`. Default: `12`. */
+    cropPaddingPx?: number;
+    /**
+     * Include truncated innerHTML on the picked target.
+     * Default: `false` (selector / role / text / bbox are usually enough).
+     * Sets the panel checkbox default; users can override per session in the UI.
+     */
+    includeInnerHTML?: boolean;
+    /** Max characters for innerHTML when enabled (default: 500). */
+    maxInnerHTMLLength?: number;
+    /**
+     * Attach curated computed styles on the picked target.
+     * Default: `"none"`. `"layout"` = box/flex/grid; `"computed"` = layout + paint/type.
+     * Sets the panel select default; users can override per session in the UI.
+     */
+    styles?: "none" | "layout" | "computed";
+    /**
+     * Framework adapter for component source enrichment.
+     * - `"auto"` (default): detect + try qwik/locator/next/react/vue/svelte
+     * - `"react"` | `"next"` | `"vue"` | `"svelte"` | `"qwik"` | `"locator"`: pin one adapter
+     * - `"none"`: DOM metadata only
+     *
+     * Custom function inject is not available here (config is JSON-serialized into
+     * the client). Use {@link mountT3Feedback} `pick.resolveSource` for that.
+     */
+    sourceFramework?: "react" | "next" | "vue" | "svelte" | "qwik" | "locator" | "auto" | "none";
+    /**
+     * When a picked element resolves to a component file, make the path in the
+     * ELEMENT chip clickable to open it in the IDE.
+     *
+     * - omit / `true` — GET Vite's `/__open-in-editor?file=path:line:column`
+     *   (set `LAUNCH_EDITOR=cursor` or `code` if auto-detect fails)
+     * - `false` — plain text path, no open action
+     * - `{ endpoint }` — same as Vite, but a custom path (still `?file=`)
+     * - `{ urlTemplate }` — navigate to a URL with `{file}`, `{line}`, `{column}`
+     *   (e.g. `vscode://file/{file}:{line}:{column}`); wins over `endpoint`
+     */
+    openInEditor?: boolean | T3FeedbackOpenInEditorOptions;
+};
+/** Custom open-in-editor behavior when not using the Vite default endpoint alone. */
+export type T3FeedbackOpenInEditorOptions = {
+    /**
+     * GET endpoint that accepts `?file=path:line:column` (Vite-compatible).
+     * Default: `/__open-in-editor`. Ignored when `urlTemplate` is set.
+     */
+    endpoint?: string;
+    /**
+     * Browser navigation URL template. Placeholders: `{file}`, `{line}`, `{column}`.
+     * `{file}` is inserted raw (use absolute paths if your scheme requires them).
+     */
+    urlTemplate?: string;
+};
+/** Screenshot / crop behavior for Capture and Change region. */
+export type T3FeedbackScreenshotOptions = {
+    /**
+     * Chord that starts Capture screenshot (opens the panel if needed).
+     * Default when omitted: Ctrl/⌘+Shift+S. Set `false` to disable.
+     * When set as an object, omitted modifiers default to `false` (same as `shortcut`).
+     */
+    shortcut?: T3FeedbackShortcutOptions | false;
+    /**
+     * Default: `"ui"`. See {@link T3FeedbackScreenshotCrop}.
+     */
+    crop?: T3FeedbackScreenshotCrop;
+    /** CSS-pixel padding when `crop` is `"auto"`. Default: pick padding or `12`. */
+    cropPaddingPx?: number;
+    /**
+     * Max images per report (capture, paste, and burst share this budget).
+     * Default: 5, clamped to 1–10.
+     */
+    maxImages?: number;
+};
+/** Frame-burst record behavior. */
+export type T3FeedbackRecordOptions = {
+    /**
+     * Chord that starts recording immediately (opens the panel afterward).
+     * Default when omitted: Ctrl/⌘+Shift+R. Set `false` to disable.
+     * When set as an object, omitted modifiers default to `false` (same as `shortcut`).
+     */
+    shortcut?: T3FeedbackShortcutOptions | false;
+};
+/** Resolved open-in-editor config (`null` = disabled). */
+export type T3FeedbackOpenInEditorConfig = {
+    /** Vite-style GET endpoint; used when `urlTemplate` is absent. */
+    endpoint: string;
+    /** Optional navigation template; wins over `endpoint` when set. */
+    urlTemplate?: string;
+};
+/** Resolved pick options embedded in the client config. */
+export type T3FeedbackPickConfig = {
+    /** `null` when pick shortcut is disabled. */
+    shortcut: T3FeedbackShortcutConfig | null;
+    afterPick: T3FeedbackAfterPick;
+    cropPaddingPx: number;
+    includeInnerHTML: boolean;
+    maxInnerHTMLLength: number;
+    styles: "none" | "layout" | "computed";
+    sourceFramework: "react" | "next" | "vue" | "svelte" | "qwik" | "locator" | "auto" | "none";
+    /** `null` when open-in-editor is disabled. */
+    openInEditor: T3FeedbackOpenInEditorConfig | null;
+};
+/** Default Vite DEV endpoint for opening a file in the editor. */
+export declare const DEFAULT_OPEN_IN_EDITOR_ENDPOINT = "/__open-in-editor";
+/** Resolved screenshot options embedded in the client config. */
+export type T3FeedbackScreenshotConfig = {
+    /** `null` when capture shortcut is disabled. */
+    shortcut: T3FeedbackShortcutConfig | null;
+    crop: T3FeedbackScreenshotCrop;
+    cropPaddingPx: number;
+    maxImages: number;
+};
+/** Resolved record options embedded in the client config. */
+export type T3FeedbackRecordConfig = {
+    /** `null` when record shortcut is disabled. */
+    shortcut: T3FeedbackShortcutConfig | null;
+};
+export declare function resolveOpenInEditorConfig(value?: boolean | T3FeedbackOpenInEditorOptions): T3FeedbackOpenInEditorConfig | null;
+export declare function resolvePickConfig(pick?: T3FeedbackPickOptions): T3FeedbackPickConfig;
+export declare function resolveScreenshotConfig(screenshot?: T3FeedbackScreenshotOptions, pickCropPaddingPx?: number): T3FeedbackScreenshotConfig;
+export declare function resolveRecordConfig(record?: T3FeedbackRecordOptions): T3FeedbackRecordConfig;
+/**
+ * Resolve plugin/mount shortcut options.
+ * - No `shortcut` / `shortcutKey`: Ctrl/⌘+Shift+F
+ * - `shortcut` object: omitted modifiers are `false`
+ * - Legacy `shortcutKey` only: same key with Ctrl/⌘+Shift
+ */
+export declare function resolveShortcut(shortcut?: T3FeedbackShortcutOptions, shortcutKey?: string): T3FeedbackShortcutConfig;
+/** Human-readable chord label (e.g. `Ctrl/⌘+Shift+F` or `F (Ctrl/⌘+Shift+F in fields)`). */
+export declare function formatShortcutLabel(shortcut: T3FeedbackShortcutConfig): string;
+/** Whether `event` matches the resolved chord (modifiers must match exactly). */
+export declare function matchesShortcut(event: Pick<KeyboardEvent, "key" | "ctrlKey" | "metaKey" | "shiftKey" | "altKey">, shortcut: T3FeedbackShortcutConfig): boolean;
+/** True when the chord requires at least one modifier (global; works while typing). */
+export declare function shortcutRequiresModifier(shortcut: T3FeedbackShortcutConfig): boolean;
+/**
+ * Fixed escape hatch for bare-key shortcuts: same key with Ctrl/⌘+Shift
+ * (works in editable fields where the bare key is ignored).
+ */
+export declare function matchesBareKeyOverride(event: Pick<KeyboardEvent, "key" | "ctrlKey" | "metaKey" | "shiftKey" | "altKey">, shortcut: T3FeedbackShortcutConfig): boolean;
+/**
+ * True when `target` is an editable / typing surface where a bare key
+ * should insert text instead of opening feedback.
+ */
+export declare function isEditableKeyboardTarget(target: EventTarget | null): boolean;
+/**
+ * Whether this keydown should open feedback.
+ * - Configured modified chords: exact match anywhere (including inputs).
+ * - Bare-key shortcuts: bare key outside editable fields, plus Ctrl/⌘+Shift+key
+ *   anywhere as a global override while typing.
+ */
+export declare function shouldOpenFromShortcut(event: Pick<KeyboardEvent, "key" | "ctrlKey" | "metaKey" | "shiftKey" | "altKey" | "target">, shortcut: T3FeedbackShortcutConfig): boolean;
+/** Built-in capture plugins selectable via `activePlugins`. Comment is always on. */
+export declare const T3_BUILTIN_PLUGIN_IDS: readonly ["pageContext", "consoleLogs", "screenshot", "elementTarget"];
+export type T3BuiltinPluginId = (typeof T3_BUILTIN_PLUGIN_IDS)[number];
+/** Per-built-in options (serializable; embedded in the client config). */
+export type T3FeedbackBuiltinPluginOptions = {
+    consoleLogs?: {
+        /** Ring-buffer size for console capture. Default: `200`. */
+        maxEntries?: number;
+    };
+};
+/**
+ * Resolve which built-ins are active.
+ * - `active` omitted → all four (today’s defaults)
+ * - explicit list → only those ids (unknown strings ignored)
+ * - `includeConsoleLogs: false` strips `consoleLogs` (deprecated alias)
+ */
+export declare function resolveActivePlugins(active?: readonly T3BuiltinPluginId[], includeConsoleLogs?: boolean): Set<T3BuiltinPluginId>;
+/** Stable ordered list of active built-in ids (for JSON client config). */
+export declare function resolveActivePluginList(active?: readonly T3BuiltinPluginId[], includeConsoleLogs?: boolean): T3BuiltinPluginId[];
+/** Options for `t3FeedbackPlugin` (Node / Vite config). */
+export type T3FeedbackPluginOptions = {
+    /** T3 HTTP origin. Default: http://localhost:3773 (override via T3_FEEDBACK_ORIGIN). */
+    origin?: string;
+    /**
+     * Browser-facing origin for Open-in-T3 links. Default: same as `origin`.
+     * Set this (or `T3_FEEDBACK_OPEN_ORIGIN`) when the host browser must use a
+     * different URL than Node (e.g. `http://localhost:3774` while the bridge uses
+     * an in-container hostname). Do **not** point this at another container's T3.
+     */
+    openOrigin?: string;
+    /**
+     * Optional prefix for newly created thread titles
+     * (e.g. `"Checkout"` → `"Checkout: /pay · broken CTA"`).
+     * Titles are derived per send; this is not a sticky reuse key.
+     */
+    threadTitle?: string;
+    /**
+     * How the injected client reuses threads across sends.
+     * Default: `"ask"` — New vs Continue in the panel (soft-default Continue when
+     * same pathname + report type within TTL).
+     * `"session-route"` — always reuse while on the same pathname.
+     * `"never"` — new thread every send.
+     */
+    threadReuse?: T3FeedbackThreadReuse;
+    /** Prefer matching this workspace root when picking a T3 project. */
+    workspaceRootHints?: string[];
+    /**
+     * Full keyboard chord (key + modifiers). Default when omitted: Ctrl/⌘+Shift+F.
+     * When set, omitted modifiers are false — e.g. `{ key: "f" }` is bare F.
+     * Bare keys skip editable fields; Ctrl/⌘+Shift+key still opens while typing.
+     * Prefer this over `shortcutKey` when changing modifiers.
+     */
+    shortcut?: T3FeedbackShortcutOptions;
+    /**
+     * @deprecated Use `shortcut: { key }` instead. Letter only; modifiers stay Ctrl/⌘+Shift.
+     */
+    shortcutKey?: string;
+    /**
+     * When true (default), inject the feedback UI into the page via transformIndexHtml.
+     * Set false to mount manually via `@rose42/t3-feedback/client`.
+     */
+    injectClient?: boolean;
+    /** Floating ✎ button visibility, position, and size (default: mobile-only). */
+    fab?: T3FeedbackFabOptions;
+    /**
+     * Report-type glyphs in the overlay and on new thread titles: SVG `"icon"`
+     * (default), `"emoji"`, or a custom map (`{ Bug: "🐛", Feedback: "💬", Suggestion: "💡" }`).
+     * `"emoji"` / map replace `Bug` / `Feedback` / `Suggestion` in new chat names.
+     */
+    reportTypeGlyph?: T3FeedbackReportTypeGlyph;
+    /** Element pick shortcut + after-pick capture/crop behavior. */
+    pick?: T3FeedbackPickOptions;
+    /** Capture / Change-region crop behavior. */
+    screenshot?: T3FeedbackScreenshotOptions;
+    /** Frame-burst record shortcut. */
+    record?: T3FeedbackRecordOptions;
+    /**
+     * App version string included on bug/feedback reports (`envelope.version`).
+     * In DEV the client also attaches an HMR generation counter (`#n`).
+     */
+    version?: string;
+    /**
+     * Which built-in capture plugins to enable.
+     * Omit = all four (`pageContext`, `consoleLogs`, `screenshot`, `elementTarget`).
+     * Explicit list = only those (comment is always collected for the panel).
+     */
+    activePlugins?: T3BuiltinPluginId[];
+    /** Options for built-ins selected by `activePlugins`. */
+    pluginOptions?: T3FeedbackBuiltinPluginOptions;
+    /**
+     * Vite-resolved module ids/paths whose default export (or module namespace) is a
+     * `FeedbackCapturePlugin`, an array of them, or a factory returning the same.
+     * Loaded as imports in the injected virtual client (not JSON-serialized).
+     * Example: `["./src/dev/authFeedbackPlugin.ts"]`.
+     */
+    customPlugins?: string[];
+};
+/** Serialized options embedded for the injected / auto-mounted client. */
+export type T3FeedbackClientConfig = {
+    shortcut: T3FeedbackShortcutConfig;
+    endpoint: string;
+    fab: T3FeedbackFabConfig;
+    threadReuse: T3FeedbackThreadReuse;
+    pick: T3FeedbackPickConfig;
+    screenshot: T3FeedbackScreenshotConfig;
+    record: T3FeedbackRecordConfig;
+    /** Report-type UI glyphs: `"icon"` (default), `"emoji"`, or a resolved custom map. */
+    reportTypeGlyph: T3FeedbackReportTypeGlyphResolved;
+    /** App version for `envelope.version` (optional). */
+    version?: string;
+    /** Active built-in plugin ids (ordered). Omit / empty handled by {@link resolveActivePlugins}. */
+    activePlugins: T3BuiltinPluginId[];
+    /** Serializable built-in options (e.g. console ring size). */
+    pluginOptions?: T3FeedbackBuiltinPluginOptions;
+};