@xysfe/bug-tap 0.0.0-stage → 0.1.0

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 (76) hide show
  1. package/CHANGELOG.md +69 -0
  2. package/LICENSE +21 -0
  3. package/README.md +461 -2
  4. package/THIRD_PARTY_NOTICES.md +39 -0
  5. package/dist/bug-tap-screenshot.min.js +10 -0
  6. package/dist/bug-tap-screenshot.min.js.map +1 -0
  7. package/dist/bug-tap-vue.cjs +2 -0
  8. package/dist/bug-tap-vue.cjs.map +1 -0
  9. package/dist/bug-tap-vue.js +106 -0
  10. package/dist/bug-tap-vue.js.map +1 -0
  11. package/dist/bug-tap-vue.min.js +2 -0
  12. package/dist/bug-tap-vue.min.js.map +1 -0
  13. package/dist/bug-tap.cjs +2 -0
  14. package/dist/bug-tap.cjs.map +1 -0
  15. package/dist/bug-tap.js +13 -0
  16. package/dist/bug-tap.js.map +1 -0
  17. package/dist/bug-tap.min.js +508 -0
  18. package/dist/bug-tap.min.js.map +1 -0
  19. package/dist/config.d.ts +14 -0
  20. package/dist/core/body.d.ts +30 -0
  21. package/dist/core/breadcrumbs.d.ts +85 -0
  22. package/dist/core/browser-api-errors.d.ts +55 -0
  23. package/dist/core/byte-buffer.d.ts +43 -0
  24. package/dist/core/collector.d.ts +34 -0
  25. package/dist/core/console-collector.d.ts +23 -0
  26. package/dist/core/env-collector.d.ts +16 -0
  27. package/dist/core/error-collector.d.ts +48 -0
  28. package/dist/core/error-noise.d.ts +43 -0
  29. package/dist/core/network-collector.d.ts +97 -0
  30. package/dist/core/network-record.d.ts +19 -0
  31. package/dist/core/resource-timing.d.ts +28 -0
  32. package/dist/core/ring-buffer.d.ts +22 -0
  33. package/dist/core/selector.d.ts +3 -0
  34. package/dist/core/serialize.d.ts +5 -0
  35. package/dist/core/tongji.d.ts +14 -0
  36. package/dist/core/user.d.ts +9 -0
  37. package/dist/index-BBRuTNvo.js +4685 -0
  38. package/dist/index-BBRuTNvo.js.map +1 -0
  39. package/dist/index-DCLLRJxX.cjs +488 -0
  40. package/dist/index-DCLLRJxX.cjs.map +1 -0
  41. package/dist/index.d.ts +33 -0
  42. package/dist/integrations.d.ts +26 -0
  43. package/dist/panel-mount-Dia21VuZ.cjs +2 -0
  44. package/dist/panel-mount-Dia21VuZ.cjs.map +1 -0
  45. package/dist/panel-mount-mAOg572s.js +499 -0
  46. package/dist/panel-mount-mAOg572s.js.map +1 -0
  47. package/dist/screenshot-global.d.ts +14 -0
  48. package/dist/sdk.d.ts +76 -0
  49. package/dist/transport/log-item.d.ts +2 -0
  50. package/dist/transport/offline-queue.d.ts +48 -0
  51. package/dist/transport/payload.d.ts +15 -0
  52. package/dist/transport/transport.d.ts +57 -0
  53. package/dist/transport/upload.d.ts +8 -0
  54. package/dist/types.d.ts +459 -0
  55. package/dist/ui/element-picker.d.ts +51 -0
  56. package/dist/ui/floating-button.d.ts +43 -0
  57. package/dist/ui/icons.d.ts +1 -0
  58. package/dist/ui/panel-mount.d.ts +20 -0
  59. package/dist/ui/panel.vue.d.ts +15 -0
  60. package/dist/ui/screenshot-loader-shared.d.ts +2 -0
  61. package/dist/ui/screenshot-loader.d.ts +14 -0
  62. package/dist/ui/screenshot-loader.iife.d.ts +16 -0
  63. package/dist/ui/screenshot.d.ts +20 -0
  64. package/dist/ui/shadow-host.d.ts +16 -0
  65. package/dist/ui/styles.css.d.ts +1 -0
  66. package/dist/ui/visibility.d.ts +25 -0
  67. package/dist/utils/match.d.ts +2 -0
  68. package/dist/utils/ua.d.ts +6 -0
  69. package/dist/utils/url.d.ts +2 -0
  70. package/dist/vue-global.d.ts +21 -0
  71. package/dist/vue.d.ts +49 -0
  72. package/docs/api.md +257 -0
  73. package/docs/backend-api.md +401 -0
  74. package/docs/bundler.md +122 -0
  75. package/docs/config.md +396 -0
  76. package/package.json +97 -4
@@ -0,0 +1,51 @@
1
+ import type { ElementSnapshot } from '../types';
2
+ export interface PickerOptions {
3
+ ignoreElements?: Element[];
4
+ hint?: string;
5
+ }
6
+ export declare class ElementPicker {
7
+ private host;
8
+ private root;
9
+ private box;
10
+ private badge;
11
+ private confirmBar;
12
+ private confirmText;
13
+ private hovered;
14
+ private pending;
15
+ private raf;
16
+ private active;
17
+ private lastX;
18
+ private lastY;
19
+ private pointerKnown;
20
+ private resolve;
21
+ private previousCursor;
22
+ private altPressed;
23
+ private coarsePointer;
24
+ private touchStartX;
25
+ private touchStartY;
26
+ private touchMoved;
27
+ start(options?: PickerOptions): Promise<ElementSnapshot | null>;
28
+ private detectCoarsePointer;
29
+ stop(): void;
30
+ private mount;
31
+ private ignoreElements;
32
+ private isIgnored;
33
+ private hitTest;
34
+ private onMouseMove;
35
+ private onScroll;
36
+ private scheduleUpdate;
37
+ private updateHighlight;
38
+ private onClick;
39
+ private onMousePress;
40
+ private onPointerPress;
41
+ private onSuppress;
42
+ private onTouchStart;
43
+ private onTouchEnd;
44
+ private onTouchMove;
45
+ private isOwnUi;
46
+ private setPending;
47
+ private clearPending;
48
+ private onKeyDown;
49
+ private onKeyUp;
50
+ private finish;
51
+ }
@@ -0,0 +1,43 @@
1
+ export interface FloatingButtonOptions {
2
+ text: string;
3
+ position: 'bottom-right' | 'bottom-left';
4
+ onClick: () => void;
5
+ onDragEnd?: (state: FabPosition) => void;
6
+ }
7
+ export interface FabPosition {
8
+ side: 'left' | 'right';
9
+ top: number;
10
+ }
11
+ export declare class FloatingButton {
12
+ private readonly options;
13
+ readonly el: HTMLButtonElement;
14
+ private readonly wrapper;
15
+ private startX;
16
+ private startY;
17
+ private originLeft;
18
+ private originTop;
19
+ private dragging;
20
+ private moved;
21
+ private suppressClick;
22
+ private scrollTimer;
23
+ private scrolling;
24
+ private listeningScroll;
25
+ constructor(options: FloatingButtonOptions);
26
+ get element(): HTMLElement;
27
+ private bindScroll;
28
+ private unbindScroll;
29
+ private onScroll;
30
+ private bindEvents;
31
+ /** 首次打开面板时展示 loading,直到面板渲染完成 */
32
+ setLoading(loading: boolean): void;
33
+ private onPointerDown;
34
+ private onPointerMove;
35
+ private onPointerUp;
36
+ private applyPosition;
37
+ private snapTo;
38
+ /** 首次挂载时恢复上次位置,没有则用默认位置 */
39
+ restorePosition(): void;
40
+ show(): void;
41
+ hide(): void;
42
+ destroy(): void;
43
+ }
@@ -0,0 +1 @@
1
+ export declare const FAB_ICON = "\n<svg viewBox=\"0 0 24 24\" width=\"20\" height=\"20\" fill=\"none\"\n stroke=\"currentColor\" stroke-width=\"1.9\" stroke-linecap=\"round\" stroke-linejoin=\"round\"\n aria-hidden=\"true\" focusable=\"false\">\n <path d=\"M21 11.5a8.38 8.38 0 0 1-.9 3.8 8.5 8.5 0 0 1-7.6 4.7 8.38 8.38 0 0 1-3.8-.9L3 21l1.9-5.7a8.38 8.38 0 0 1-.9-3.8 8.5 8.5 0 0 1 4.7-7.6 8.38 8.38 0 0 1 3.8-.9h.5a8.48 8.48 0 0 1 8 8v.5z\"/>\n <path d=\"M12 7.6v4.6\"/>\n <circle cx=\"12\" cy=\"15.2\" r=\"1\" fill=\"currentColor\" stroke=\"none\"/>\n</svg>";
@@ -0,0 +1,20 @@
1
+ import type { ElementSnapshot, ReporterFormValues, Screenshot, SubmitResponse } from '../types';
2
+ export interface PanelCallbacks {
3
+ onSubmit(values: ReporterFormValues, screenshots: Screenshot[], elements: ElementSnapshot[]): Promise<SubmitResponse>;
4
+ onClose?(): void;
5
+ onCapture(): Promise<Screenshot>;
6
+ onUpload(file: File): Promise<Screenshot>;
7
+ onPickElement(): Promise<ElementSnapshot | null>;
8
+ onDisable?: () => void;
9
+ canUploadScreenshot?: boolean;
10
+ maxElements?: number;
11
+ }
12
+ export declare class ReporterPanel {
13
+ readonly overlay: HTMLDivElement;
14
+ private readonly app;
15
+ private readonly api;
16
+ constructor(callbacks: PanelCallbacks);
17
+ open(autoCapture?: boolean): void;
18
+ close(): void;
19
+ unmount(): void;
20
+ }
@@ -0,0 +1,15 @@
1
+ import type { PanelCallbacks } from './panel-mount';
2
+ type __VLS_Props = {
3
+ callbacks: PanelCallbacks;
4
+ };
5
+ declare function show(autoCapture?: boolean): void;
6
+ declare function hide(): void;
7
+ declare function resetView(): void;
8
+ declare function resetForm(): void;
9
+ declare const _default: import("vue").DefineComponent<__VLS_Props, {
10
+ show: typeof show;
11
+ hide: typeof hide;
12
+ resetForm: typeof resetForm;
13
+ resetView: typeof resetView;
14
+ }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
15
+ export default _default;
@@ -0,0 +1,2 @@
1
+ /** 按绝对地址注入脚本并取回全局入口;加载完成但没有暴露入口时明确报错 */
2
+ export declare function loadScreenshotGlobal(url: string): Promise<unknown>;
@@ -0,0 +1,14 @@
1
+ /**
2
+ * 截图库加载实现(ESM 产物)。
3
+ *
4
+ * 两种模式,由 `screenshot.scriptUrl` 决定:
5
+ * - 默认:`import('html2canvas-pro')`,业务打包器拆成按需 chunk
6
+ * - 配了 `scriptUrl`:改用外部脚本,适合 webpack 4 这类解析器不支持 ES2020 语法的场景
7
+ * (html2canvas-pro 的产物含 `??`,webpack 4 的 acorn 会直接解析失败)
8
+ *
9
+ * IIFE 构建会用 `screenshot-loader.iife.ts` 替换本文件(见 vite.config.ts 的 alias)。
10
+ */
11
+ import type { Html2Canvas } from './screenshot';
12
+ /** 由 SDK 在配置解析 / setConfig 时调用 */
13
+ export declare function setScreenshotScriptUrl(url: string): void;
14
+ export declare function loadHtml2CanvasImpl(): Promise<Html2Canvas>;
@@ -0,0 +1,16 @@
1
+ /**
2
+ * 截图库加载实现(IIFE 产物)。
3
+ *
4
+ * 主包 `bug-tap.min.js` 必须保持单文件且不含 html2canvas:
5
+ * 首次需要截图时,注入 `bug-tap-screenshot.min.js`。
6
+ *
7
+ * 地址解析顺序:
8
+ * 1. `screenshot.scriptUrl` 显式配置(支持相对路径 / 绝对 URL)
9
+ * 2. 与主包同目录(读取 `<script src>` 的 URL 再替换文件名)
10
+ *
11
+ * 这个文件通过 vite.config.ts 的 alias 替换掉 `screenshot-loader.ts`。
12
+ */
13
+ import type { Html2Canvas } from './screenshot';
14
+ /** 由 SDK 在配置解析 / setConfig 时调用 */
15
+ export declare function setScreenshotScriptUrl(url: string): void;
16
+ export declare function loadHtml2CanvasImpl(): Promise<Html2Canvas>;
@@ -0,0 +1,20 @@
1
+ import type { Screenshot } from '../types';
2
+ /**
3
+ * html2canvas-pro 体积约 51KB gzip,只有用户点开面板需要截图时才会用到。
4
+ *
5
+ * 加载方式由构建产物决定(见 `screenshot-loader.ts` / `screenshot-loader.iife.ts`):
6
+ * - ESM:`import('html2canvas-pro')`,业务打包器拆成按需 chunk
7
+ * - IIFE:注入 `bug-tap-screenshot.min.js`,地址可由 `screenshot.scriptUrl` 指定
8
+ */
9
+ export type Html2Canvas = typeof import('html2canvas-pro').default;
10
+ /** 由 SDK 在配置解析 / setConfig 时调用,仅 IIFE 生效 */
11
+ export declare function configureScreenshotScript(url: string): void;
12
+ export interface CaptureOptions {
13
+ ignoreElement?: HTMLElement | null;
14
+ quality: number;
15
+ maxWidth: number;
16
+ maxSizeKB: number;
17
+ source?: 'auto' | 'manual';
18
+ }
19
+ export declare function captureViewport(options: CaptureOptions): Promise<Screenshot>;
20
+ export declare function readImageFile(file: File, options: CaptureOptions): Promise<Screenshot>;
@@ -0,0 +1,16 @@
1
+ export type ThemeMode = 'light' | 'dark' | 'auto';
2
+ export declare class ShadowHost {
3
+ private readonly theme;
4
+ readonly host: HTMLDivElement;
5
+ readonly root: ShadowRoot;
6
+ private media;
7
+ private readonly onThemeChange;
8
+ constructor(theme: ThemeMode, zIndex: number);
9
+ mount(): void;
10
+ unmount(): void;
11
+ private injectStyles;
12
+ private bindTheme;
13
+ private unbindTheme;
14
+ private applyTheme;
15
+ private resolveTheme;
16
+ }
@@ -0,0 +1 @@
1
+ export declare const STYLES = "\n:host {\n all: initial;\n --br-bg: #ffffff;\n --br-bg-soft: #f6f8fa;\n --br-fg: #1f2328;\n --br-muted: #656d76;\n --br-border: #d0d7de;\n --br-primary: #1d64e0;\n --br-primary-fg: #ffffff;\n --br-danger: #d1242f;\n --br-ok: #1a7f37;\n --br-shadow: 0 8px 30px rgba(15, 23, 42, .18);\n --br-radius: 10px;\n --br-z: 2147483000;\n position: fixed;\n inset: 0;\n z-index: var(--br-z);\n pointer-events: none;\n font-family: -apple-system, BlinkMacSystemFont, \"Segoe UI\", \"PingFang SC\", \"Microsoft YaHei\", sans-serif;\n font-size: 14px;\n line-height: 1.6;\n color: var(--br-fg);\n -webkit-font-smoothing: antialiased;\n}\n\n:host([data-theme=\"dark\"]) {\n --br-bg: #1c2128;\n --br-bg-soft: #22272e;\n --br-fg: #e6edf3;\n --br-muted: #9198a1;\n --br-border: #3d444d;\n --br-primary: #4d8ff0;\n --br-primary-fg: #0d1117;\n --br-danger: #f85149;\n --br-ok: #3fb950;\n --br-shadow: 0 8px 30px rgba(0, 0, 0, .5);\n}\n\n*, *::before, *::after { box-sizing: border-box; }\n\n.br-fab-wrap {\n position: fixed;\n right: calc(20px + env(safe-area-inset-right, 0px));\n bottom: calc(20px + env(safe-area-inset-bottom, 0px));\n z-index: calc(var(--br-z) + 1);\n display: inline-flex;\n align-items: center;\n gap: 4px;\n pointer-events: auto;\n touch-action: none;\n transition: opacity .2s ease;\n}\n.br-fab-wrap--left { right: auto; left: calc(20px + env(safe-area-inset-left, 0px)); }\n.br-fab-wrap--hidden { display: none; }\n.br-fab-wrap--free { right: auto; bottom: auto; }\n.br-fab-wrap--dragging { cursor: grabbing; transition: none; }\n/* \u6EDA\u52A8\u65F6\u6DE1\u5316\uFF0C\u51CF\u5C11\u5BF9\u5185\u5BB9\u7684\u5E72\u6270 */\n.br-fab-wrap--scrolling { opacity: .42; }\n.br-fab-wrap--scrolling .br-fab { box-shadow: 0 2px 8px rgba(15, 23, 42, .16); }\n.br-fab-wrap--dragging .br-fab { transform: scale(1.04); box-shadow: 0 10px 26px rgba(15, 23, 42, .32); }\n\n.br-fab-icon {\n display: inline-flex;\n align-items: center;\n justify-content: center;\n width: 20px;\n height: 20px;\n transition: opacity .15s ease;\n}\n.br-fab-icon svg { display: block; }\n\n/* loading\uFF1A\u56FE\u6807\u6DE1\u51FA\uFF0C\u73AF\u5F62\u6307\u793A\u5668\u8986\u76D6\u4E0A\u6765 */\n.br-fab--loading { cursor: progress; }\n.br-fab--loading .br-fab-icon { opacity: 0; }\n.br-fab--loading::after {\n content: '';\n position: absolute;\n width: 18px;\n height: 18px;\n border: 2px solid rgba(255, 255, 255, .35);\n border-top-color: var(--br-primary-fg);\n border-radius: 50%;\n animation: br-spin .7s linear infinite;\n}\n@keyframes br-spin { to { transform: rotate(360deg); } }\n@media (prefers-reduced-motion: reduce) {\n .br-fab--loading::after { animation-duration: 2s; }\n}\n\n.br-fab {\n position: relative;\n display: inline-flex;\n align-items: center;\n justify-content: center;\n width: 46px;\n height: 46px;\n padding: 0;\n border: 1px solid rgba(255, 255, 255, .18);\n border-radius: 50%;\n background: var(--br-primary);\n color: var(--br-primary-fg);\n box-shadow: var(--br-shadow);\n cursor: grab;\n pointer-events: auto;\n user-select: none;\n touch-action: none;\n transition: transform .15s ease, opacity .15s ease, box-shadow .15s ease;\n}\n.br-fab:hover { transform: translateY(-1px); }\n.br-fab:active { cursor: grabbing; }\n.br-fab:focus-visible { outline: 2px solid #fff; outline-offset: 2px; }\n\n.br-overlay {\n position: fixed;\n inset: 0;\n z-index: calc(var(--br-z) + 2);\n display: none;\n background: rgba(15, 23, 42, .38);\n pointer-events: auto;\n}\n.br-overlay--open { display: block; }\n.br-overlay--hidden { display: none; }\n.br-panel--hidden { display: none !important; }\n\n.br-panel {\n position: fixed;\n top: 50%;\n left: 50%;\n transform: translate(-50%, -50%);\n width: 640px;\n max-width: calc(100vw - 40px);\n height: 80vh;\n max-height: 900px;\n display: none;\n flex-direction: column;\n background: var(--br-bg);\n color: var(--br-fg);\n border-radius: 16px;\n box-shadow: var(--br-shadow);\n pointer-events: auto;\n overflow: hidden;\n}\n.br-panel--open { display: flex; }\n\n.br-header {\n display: flex;\n align-items: center;\n gap: 10px;\n padding: 14px 16px;\n border-bottom: 1px solid var(--br-border);\n background: var(--br-bg);\n}\n.br-heading { flex: 1; margin: 0; font-size: 15px; font-weight: 600; }\n.br-close {\n width: 30px;\n height: 30px;\n border: 1px solid var(--br-border);\n border-radius: 8px;\n background: transparent;\n color: var(--br-muted);\n font: inherit;\n font-size: 16px;\n line-height: 1;\n cursor: pointer;\n}\n.br-close:hover { background: var(--br-bg-soft); color: var(--br-fg); }\n\n.br-body {\n flex: 1;\n overflow-y: auto;\n padding: 14px 16px 18px;\n display: flex;\n flex-direction: column;\n gap: 14px;\n}\n\n.br-hidden { display: none !important; }\n.br-form { display: flex; flex-direction: column; gap: 14px; }\n.br-field { display: flex; flex-direction: column; gap: 6px; }\n.br-label { font-size: 13px; font-weight: 600; color: var(--br-fg); }\n.br-required { color: var(--br-danger); margin-left: 2px; }\n.br-hint { font-size: 12px; color: var(--br-muted); }\n\n.br-input, .br-textarea, .br-select {\n width: 100%;\n border: 1px solid var(--br-border);\n border-radius: 8px;\n background: var(--br-bg);\n color: var(--br-fg);\n font: inherit;\n font-size: 13px;\n padding: 8px 10px;\n outline: none;\n}\n.br-input:focus, .br-textarea:focus, .br-select:focus {\n border-color: var(--br-primary);\n box-shadow: 0 0 0 3px rgba(29, 100, 224, .16);\n}\n.br-textarea { resize: vertical; min-height: 96px; }\n.br-row { display: flex; gap: 10px; }\n.br-row > .br-field { flex: 1; min-width: 0; }\n\n.br-shot-preview {\n display: block;\n width: 100%;\n max-height: 220px;\n margin-top: 8px;\n object-fit: contain;\n object-position: top center;\n border: 1px dashed var(--br-border);\n border-radius: 8px;\n background: var(--br-bg-soft);\n}\n.br-shot-actions { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; }\n.br-shot-status { font-size: 12px; color: var(--br-muted); }\n.br-btn--link-inline {\n padding: 0;\n border: 0;\n background: transparent;\n color: var(--br-primary);\n font: inherit;\n font-size: 12px;\n cursor: pointer;\n}\n.br-btn--link-inline:hover { text-decoration: underline; }\n.br-element-box { display: flex; flex-direction: column; gap: 8px; }\n.br-element-list { display: flex; flex-direction: column; gap: 4px; }\n.br-element-item {\n display: flex;\n align-items: center;\n gap: 8px;\n padding: 4px 6px 4px 8px;\n border: 1px solid var(--br-border);\n border-radius: 6px;\n background: var(--br-bg-soft);\n}\n.br-element-item-text {\n flex: 1;\n min-width: 0;\n overflow: hidden;\n text-overflow: ellipsis;\n white-space: nowrap;\n font-family: ui-monospace, SFMono-Regular, Menlo, monospace;\n font-size: 12px;\n color: var(--br-fg);\n}\n.br-element-item-del {\n flex: none;\n width: 18px;\n height: 18px;\n padding: 0;\n border: 0;\n border-radius: 4px;\n background: transparent;\n color: var(--br-muted);\n font: inherit;\n font-size: 14px;\n line-height: 1;\n cursor: pointer;\n}\n.br-element-item-del:hover { background: var(--br-border); color: var(--br-fg); }\n\n.br-thumb-list { display: flex; flex-wrap: wrap; gap: 8px; }\n.br-attach-row { display: flex; align-items: center; gap: 8px; }\n.br-thumb {\n position: relative;\n width: 72px;\n height: 72px;\n border: 1px solid var(--br-border);\n border-radius: 6px;\n overflow: hidden;\n background: var(--br-bg-soft);\n}\n.br-thumb img { width: 100%; height: 100%; object-fit: cover; display: block; }\n/* \u81EA\u52A8\u622A\u56FE\u89D2\u6807\uFF1A\u4E0E\u7528\u6237\u624B\u52A8\u4E0A\u4F20\u7684\u56FE\u533A\u5206\u5F00\uFF0C\u907F\u514D\u8BEF\u4EE5\u4E3A\u662F\u81EA\u5DF1\u7684\u56FE */\n.br-thumb-tag {\n position: absolute;\n left: 2px;\n bottom: 2px;\n padding: 1px 5px;\n border-radius: 4px;\n background: rgba(15, 23, 42, .62);\n color: #fff;\n font: 11px/1.4 -apple-system, \"Segoe UI\", \"Microsoft YaHei\", sans-serif;\n pointer-events: none;\n}\n.br-thumb-del {\n position: absolute;\n top: 2px;\n right: 2px;\n width: 18px;\n height: 18px;\n padding: 0;\n border: 0;\n border-radius: 50%;\n background: rgba(15, 23, 42, .62);\n color: #fff;\n font: inherit;\n font-size: 13px;\n line-height: 1;\n cursor: pointer;\n opacity: 0;\n transition: opacity .15s ease;\n}\n.br-thumb:hover .br-thumb-del,\n.br-thumb-del:focus-visible { opacity: 1; }\n@media (max-width: 560px) {\n .br-thumb-del { opacity: 1; }\n}\n\n.br-footer {\n display: flex;\n align-items: center;\n gap: 10px;\n padding: 12px 16px;\n border-top: 1px solid var(--br-border);\n background: var(--br-bg);\n}\n.br-footer .br-spacer { flex: 1; }\n\n.br-btn {\n border: 1px solid var(--br-border);\n border-radius: 8px;\n background: var(--br-bg);\n color: var(--br-fg);\n font: inherit;\n font-size: 13px;\n padding: 7px 14px;\n cursor: pointer;\n}\n.br-btn:hover { background: var(--br-bg-soft); }\n.br-btn:disabled { opacity: .55; cursor: not-allowed; }\n.br-btn--primary {\n border-color: var(--br-primary);\n background: var(--br-primary);\n color: var(--br-primary-fg);\n}\n.br-btn--primary:hover { filter: brightness(1.05); background: var(--br-primary); }\n.br-btn--ghost { background: transparent; }\n.br-btn--link {\n padding: 0;\n border: 0;\n background: transparent;\n color: var(--br-muted);\n font-size: 12px;\n text-decoration: underline;\n cursor: pointer;\n margin-right: auto;\n}\n.br-btn--link:hover { color: var(--br-fg); }\n.br-btn--sm { padding: 4px 10px; font-size: 12px; }\n\n.br-status { font-size: 12px; color: var(--br-muted); min-height: 18px; }\n.br-status--error { color: var(--br-danger); }\n.br-status--ok { color: var(--br-ok); }\n\n.br-success { display: flex; flex-direction: column; gap: 12px; padding: 8px 0; }\n.br-success-title { font-size: 15px; font-weight: 600; color: var(--br-ok); }\n.br-link { color: var(--br-primary); text-decoration: underline; word-break: break-all; }\n.br-success-actions { display: flex; gap: 8px; margin-top: 4px; }\n\n@media (max-width: 560px) {\n .br-panel {\n top: auto;\n left: 0;\n right: 0;\n bottom: 0;\n transform: none;\n width: auto;\n max-width: none;\n height: 75vh;\n max-height: 85vh;\n border-radius: 16px 16px 0 0;\n padding-bottom: env(safe-area-inset-bottom, 0px);\n }\n .br-row { flex-direction: column; gap: 14px; }\n .br-fab-wrap { right: calc(14px + env(safe-area-inset-right, 0px)); bottom: calc(14px + env(safe-area-inset-bottom, 0px)); }\n .br-fab-wrap--left { right: auto; left: calc(14px + env(safe-area-inset-left, 0px)); }\n}\n";
@@ -0,0 +1,25 @@
1
+ /**
2
+ * 反馈按钮的显隐决策,唯一入口是 resolveVisibility。
3
+ *
4
+ * 优先级(从高到低):
5
+ * 1. URL 参数命中 → 展示并持久化,可用来重新打开已关闭的入口
6
+ * 2. URL 参数明确关闭 → 隐藏
7
+ * 3. 用户点过「不再显示」→ 隐藏(always 模式也要尊重)
8
+ * 4. triggered 模式 → 仅当已持久化开启时展示
9
+ * 5. always 模式 → 展示
10
+ */
11
+ export interface VisibilityOptions {
12
+ mode: 'always' | 'triggered';
13
+ queryParam: string;
14
+ queryValue: string;
15
+ }
16
+ export type VisibilityFlag = '1' | '0' | null;
17
+ export declare function readVisibilityFlag(): VisibilityFlag;
18
+ export declare function writeVisibilityFlag(enabled: boolean): void;
19
+ /**
20
+ * 读取 URL 上的开关。
21
+ * 返回 null 表示 URL 没带这个参数;true/false 表示带了且值匹配/不匹配。
22
+ */
23
+ export declare function readQueryFlag(options: VisibilityOptions): boolean | null;
24
+ /** 计算按钮是否展示;URL 命中开启时会持久化标记 */
25
+ export declare function resolveVisibility(options: VisibilityOptions): boolean;
@@ -0,0 +1,2 @@
1
+ /** 采集过滤用的匹配:字符串按包含、正则按 test,异常一律视为不匹配 */
2
+ export declare function matchesPattern(pattern: string | RegExp, text: string): boolean;
@@ -0,0 +1,6 @@
1
+ export interface ParsedUserAgent {
2
+ browser?: string;
3
+ browserVersion?: string;
4
+ os?: string;
5
+ }
6
+ export declare function parseUserAgent(ua: string): ParsedUserAgent;
@@ -0,0 +1,2 @@
1
+ /** 把相对地址按当前页面解析成绝对地址;解析失败时原样返回 */
2
+ export declare function absoluteUrl(value: string): string;
@@ -0,0 +1,21 @@
1
+ /**
2
+ * IIFE 插件产物:`bug-tap-vue.min.js`。
3
+ *
4
+ * CDN 用法(Vue 2 与 Vue 3 都用同一个全局对象):
5
+ * ```html
6
+ * <script src="bug-tap.min.js"></script>
7
+ * <script src="bug-tap-vue.min.js"></script>
8
+ * <script>
9
+ * app.use(window.BugTapVue, { router }); // Vue 3
10
+ * Vue.use(window.BugTapVue, { router }); // Vue 2
11
+ * </script>
12
+ * ```
13
+ */
14
+ import plugin from './vue';
15
+ import type { VuePlugin } from './vue';
16
+ declare global {
17
+ interface Window {
18
+ BugTapVue?: VuePlugin;
19
+ }
20
+ }
21
+ export default plugin;
package/dist/vue.d.ts ADDED
@@ -0,0 +1,49 @@
1
+ /**
2
+ * Vue 插件入口:`@xysfe/bug-tap/vue`
3
+ *
4
+ * 一个入口同时支持 Vue 2 与 Vue 3,形态由**调用方式**决定,不做版本嗅探
5
+ * (与 Sentry `@sentry/vue` 的 `app` / `Vue` 双路径一致):
6
+ *
7
+ * ```js
8
+ * // Vue 3:app.use(plugin, { router })
9
+ * createApp(App).use(router).use(BugTapVue, { router }).mount('#app');
10
+ *
11
+ * // Vue 2:Vue.use(plugin, { router })
12
+ * Vue.use(BugTapVue, { router });
13
+ * new Vue({ router }).$mount('#app');
14
+ * ```
15
+ *
16
+ * 不 `import 'vue'`:只用鸭子类型访问 `config.errorHandler` 与 `router.afterEach`,
17
+ * 因此本文件零依赖、零体积,也不锁死 Vue 版本。
18
+ */
19
+ import type { BugTapApi } from './types';
20
+ /**
21
+ * 插件实际用到的最小客户端契约。
22
+ * 不含 setTag / setContext:本文件只用捕获与面包屑,契约越窄越好接。
23
+ */
24
+ export type VueClient = Pick<BugTapApi, 'captureException' | 'addBreadcrumb' | 'disableRouteCapture'>;
25
+ export interface VueRouterLike {
26
+ afterEach?(hook: (to: unknown, from?: unknown, failure?: unknown) => void): unknown;
27
+ }
28
+ interface VueConfigLike {
29
+ errorHandler?: ((error: unknown, instance: unknown, info: string) => void) | null;
30
+ }
31
+ /** Vue 3 应用实例:有 config,且有 _context / _instance 这类内部字段 */
32
+ interface VueAppLike {
33
+ config?: VueConfigLike | null;
34
+ use?: unknown;
35
+ }
36
+ export interface VuePluginOptions {
37
+ /** 不传则使用 window.BugTap(CDN 场景) */
38
+ client?: VueClient;
39
+ /** 传 vue-router 实例:路由改由 afterEach 记录,并停用主包的 history 补丁 */
40
+ router?: VueRouterLike;
41
+ /** 是否挂 errorHandler,默认 true */
42
+ captureErrors?: boolean;
43
+ }
44
+ export interface VuePlugin {
45
+ install(target: VueAppLike | VueConfigLike, options?: VuePluginOptions): () => void;
46
+ }
47
+ export declare function createVuePlugin(fallbackClient?: VueClient | null): VuePlugin;
48
+ declare const plugin: VuePlugin;
49
+ export default plugin;
package/docs/api.md ADDED
@@ -0,0 +1,257 @@
1
+ # 全局 API
2
+
3
+ SDK 加载后 `window.BugTap` 即存在,无需等待 `DOMContentLoaded`。ESM 用户也可以 `import { init, BugTap } from '@xysfe/bug-tap'`。
4
+
5
+ ## init
6
+
7
+ ```ts
8
+ BugTap.init(config?: BugTapConfig): BugTapApi | null
9
+ ```
10
+
11
+ - 不传 `config` 时读取 `window.BugTapConfig`
12
+ - 重复调用是幂等的,返回同一实例
13
+ - 配置缺失或非法时返回 `null`,不抛错,不阻断页面
14
+
15
+ ```js
16
+ BugTap.init({ project: 'p' }); // endpoint 默认 /go/SupportTools/logreport
17
+ ```
18
+
19
+ ## open / close
20
+
21
+ ```ts
22
+ BugTap.open(): void
23
+ BugTap.close(): void
24
+ ```
25
+
26
+ 打开/关闭反馈面板,与 `openReporter()` / `closeReporter()` 等价。
27
+
28
+ ## openReporter / closeReporter
29
+
30
+ ```ts
31
+ BugTap.openReporter(): void
32
+ BugTap.closeReporter(): void
33
+ ```
34
+
35
+ 打开/关闭 Bug 反馈面板。
36
+
37
+ ```js
38
+ document.getElementById('feedback').addEventListener('click', () => {
39
+ BugTap.openReporter();
40
+ });
41
+ ```
42
+
43
+ ## setConfig
44
+
45
+ ```ts
46
+ BugTap.setConfig(patch: Partial<BugTapConfig>): void
47
+ ```
48
+
49
+ 深合并配置。会重建上报 UI;采集相关配置变化时重建采集器并清空已有缓冲。
50
+
51
+ ```js
52
+ BugTap.setConfig({ environment: 'staging' });
53
+ ```
54
+
55
+ 注意:deep merge 会把 `undefined` 当成「没传」而保留旧值,所以清空用户信息请用 `setUser(null)`,不要用 `setConfig({ user: undefined })`。
56
+
57
+ ## setUser
58
+
59
+ ```ts
60
+ BugTap.setUser(user: UserInfo | (() => UserInfo | null | undefined) | null): void
61
+ ```
62
+
63
+ 运行时更新登录用户信息,下次提交立即生效,不影响已采集的缓冲与 UI。
64
+
65
+ ```js
66
+ BugTap.setUser({ id: 'u-200', name: '李四' }); // 登录 / 切换账号
67
+ BugTap.setUser(() => readStore().user); // 每次提交时求值
68
+ BugTap.setUser(null); // 退出登录,清空
69
+ ```
70
+
71
+ 字段约束见 [config.md 的 user 一节](config.md#user)。
72
+
73
+ ## setTag / setExtra / setContext
74
+
75
+ ```ts
76
+ BugTap.setTag(key: string, value: string | number | boolean): void
77
+ BugTap.setExtra(key: string, value: unknown): void
78
+ BugTap.setContext(name: string, context: Record<string, unknown>): void
79
+ ```
80
+
81
+ 给之后的反馈附加业务上下文,写入 `ext.tags` / `ext.extra` / `ext.contexts`,并在 `content` 里带前 5 个 tag 便于全文检索。
82
+
83
+ ```js
84
+ BugTap.setTag('tenant', 'sh');
85
+ BugTap.setTag('feature', 'order-export');
86
+ BugTap.setExtra('orderId', 'O-20261117-001');
87
+ BugTap.setContext('cart', { count: 3, amount: 199 });
88
+ ```
89
+
90
+ 报告中超过体积上限时,`extra` / `contexts` 会按 key 的写入顺序从旧到新裁剪。
91
+
92
+ 写入时会做**有界深拷贝**:环引用替换为 `[Circular]`,深度最多 6 层、每个对象最多 50 个键、数组最多 50 项,getter 抛错时跳过该键。所以可以直接传 Vue reactive、Pinia store 这类带回引用的对象,不会在提交时因 `JSON.stringify` 抛错。
93
+
94
+ ## addBreadcrumb
95
+
96
+ ```ts
97
+ BugTap.addBreadcrumb(breadcrumb: { type?, message?, ... }): void
98
+ ```
99
+
100
+ 主动往时间线写一条记录,适合标记「提交订单」「切换 Tab」这类业务动作。`t` 由 SDK 补齐,省略 `type` 时记为 `manual`。
101
+
102
+ ```js
103
+ BugTap.addBreadcrumb({ message: 'submit order', data: { orderId: 'O-1' } });
104
+ ```
105
+
106
+ ## captureException / captureMessage
107
+
108
+ ```ts
109
+ BugTap.captureException(error: unknown, context?: Record<string, unknown>): void
110
+ BugTap.captureMessage(message: string, context?: Record<string, unknown>): void
111
+ ```
112
+
113
+ 主动记录异常或消息,进入下一次用户反馈的 `errors[]`。**不会单独发请求**,避免业务在循环里调用时打爆网关。
114
+
115
+ ```js
116
+ try {
117
+ await submitOrder();
118
+ } catch (error) {
119
+ BugTap.captureException(error, { orderId: currentOrder.id });
120
+ }
121
+ ```
122
+
123
+ Vue / React 的框架级异常接入见 `installVueErrorHandler` / `reactErrorHandlers`。
124
+
125
+ ## flush
126
+
127
+ ```ts
128
+ BugTap.flush(): Promise<number>
129
+ ```
130
+
131
+ 立即重放 IndexedDB 补偿队列,返回本次成功发出的条数。通常不需要手动调用:初始化、`online`、`visibilitychange` 已自动触发。
132
+
133
+ ## 框架集成
134
+
135
+ ### Vue(`@xysfe/bug-tap/vue`)
136
+
137
+ 一个入口同时支持 Vue 2 与 Vue 3,**形态由调用方式决定**,不做版本嗅探(与 Sentry `@sentry/vue` 的 `app` / `Vue` 双路径一致):
138
+
139
+ ```js
140
+ // Vue 3
141
+ import BugTapVue from '@xysfe/bug-tap/vue';
142
+ createApp(App).use(router).use(BugTapVue, { router }).mount('#app');
143
+
144
+ // Vue 2
145
+ import BugTapVue from '@xysfe/bug-tap/vue';
146
+ Vue.use(BugTapVue, { router });
147
+ new Vue({ router }).$mount('#app');
148
+ ```
149
+
150
+ ```ts
151
+ interface VuePluginOptions {
152
+ client?: VueClient; // 不传则用 window.BugTap(CDN 场景)
153
+ router?: VueRouterLike; // 传了就用 router.afterEach 记路由,并停用主包 history 补丁
154
+ captureErrors?: boolean; // 默认 true
155
+ }
156
+ ```
157
+
158
+ 插件行为:
159
+
160
+ - 链式包装 `Vue.config.errorHandler` / `app.config.errorHandler`,不覆盖业务原有处理
161
+ - 上报 `source: "vue"`、`info`、`component`(Vue 3 取 `instance.$.type.__name`,Vue 2 取 `$options.name`)、当前路由
162
+ - 传了 `router` 时调用 `client.disableRouteCapture()` 摘掉主包的 history 补丁,路由改由 `afterEach` 记录,一次导航只记一条
163
+ - 导航失败(chunk 404、守卫抛错)记成 `errors[]`,带 `from` / `to`
164
+ - 未初始化时安装是安全的空操作,不会阻断应用启动
165
+
166
+ 插件不 `import 'vue'`,因此零依赖、约 1KB gzip,也不锁定 Vue 版本。
167
+
168
+ ### React
169
+
170
+ ```ts
171
+ // React 19:createRoot(el, BugTap.reactErrorHandlers())
172
+ createRoot(el, reactErrorHandlers());
173
+ // React 18 及以下:ErrorBoundary.componentDidCatch 里
174
+ BugTap.captureException(error, { source: 'react', componentStack: info.componentStack });
175
+ ```
176
+
177
+ - React 19:`onUncaughtError` / `onCaughtError` / `onRecoverableError` 回调,上报 `source: "react"` 与 `componentStack`
178
+ - React 18 及以下:在 ErrorBoundary 的 `componentDidCatch(error, info)` 里调用 `BugTap.captureException(error, { source: 'react', componentStack: info.componentStack })`
179
+
180
+ 框架接住的异常不会冒泡到 `window.onerror`,不显式接入就采不到。
181
+
182
+ ## createClient
183
+
184
+ ```ts
185
+ BugTap.createClient(config: BugTapConfig): BugTapApi | null
186
+ ```
187
+
188
+ 创建独立实例,用于微前端 / 多子应用隔离 UI 与 project。注意采集器包装的是全局 API,多个实例会各自采集一份;只需要一个上报入口时优先用 `init()`。
189
+
190
+ ## destroy
191
+
192
+ ```ts
193
+ BugTap.destroy(): void
194
+ ```
195
+
196
+ - 移除悬浮按钮与面板
197
+ - 还原 console / fetch / XMLHttpRequest / WebSocket / EventSource 的原始函数(仅在当前函数仍是 SDK 包装版本时)
198
+ - 移除全局异常监听与 `online` / `pagehide` 监听
199
+ - 本地补偿队列(IndexedDB)保留,下次 `init()` 后仍会重放
200
+ - 之后可再次调用 `init()` 恢复
201
+
202
+ ```js
203
+ BugTap.destroy();
204
+ BugTap.init();
205
+ ```
206
+
207
+ ## getReport
208
+
209
+ ```ts
210
+ BugTap.getReport(): BugReport
211
+ ```
212
+
213
+ 返回当前采集到的报告快照(不含截图,不发起请求)。可用于业务侧自行分析、二次上报或调试。
214
+
215
+ ```js
216
+ const report = BugTap.getReport();
217
+ console.log(report.logs.length, report.errors.length, report.network.length);
218
+ ```
219
+
220
+ 未初始化时抛错。
221
+
222
+ ## version
223
+
224
+ ```ts
225
+ BugTap.version: string
226
+ ```
227
+
228
+ 当前 SDK 版本,与 `package.json` 一致。
229
+
230
+ ## 生命周期
231
+
232
+ ```
233
+ 加载 SDK
234
+ → 读取 window.BugTapConfig
235
+ → 立即启动 Collector(console / error / network)
236
+ → 按 reporter.enabled 挂载悬浮按钮
237
+
238
+ 点击悬浮按钮
239
+ → 按钮进入 loading
240
+ → 首次点击时创建 Vue 应用并挂载 Shadow DOM 反馈面板
241
+ → 按 screenshot.enabled && auto 自动截图
242
+
243
+ 提交
244
+ → 若有截图:先 POST /platform/file/uploadPicture 换成 URL(失败降级 base64)
245
+ → 组装 BugReport(带 user / track,体积裁剪)
246
+ → 组装 LogItem[](content 摘要 + ext 结构化 JSON)
247
+ → POST endpoint(超时 / 重试)
248
+ → 成功展示反馈编号(clientReportId)
249
+ ```
250
+
251
+ ## 事件与集成
252
+
253
+ 当前版本不提供事件总线。需要与业务系统联动时:
254
+
255
+ - 用 `getReport()` 取快照
256
+ - 用 `transport.headers` 注入业务标识(如用户 ID、租户 ID)
257
+ - 用 `setConfig()` 动态切换环境或项目