makethisbetter 1.0.0

package/dist/widget/controller.d.ts

@@ -0,0 +1,37 @@
+import type { MakeThisBetterConfig } from '../types';
+export declare class WidgetController {
+    private config;
+    private shadow;
+    private tab;
+    private pet;
+    private toolbar;
+    private session;
+    private popup;
+    private success;
+    private frustrationPrompt;
+    private apiClient;
+    private consoleCollector;
+    private frustrationDetector;
+    private messages;
+    private mode;
+    private currentAnnotation;
+    private recordSession;
+    private recordBar;
+    private currentRecording;
+    constructor(config: MakeThisBetterConfig);
+    private buildUI;
+    private handleTabClick;
+    private handleFrustration;
+    private dismissFrustrationPrompt;
+    private enterAnnotationMode;
+    private handleToolbarModeChange;
+    private enterRecordingMode;
+    private stopRecording;
+    private exitRecordingMode;
+    private showPopup;
+    private handleSubmit;
+    private showSuccess;
+    private exitAll;
+    destroy(): void;
+}
+//# sourceMappingURL=controller.d.ts.map

package/dist/widget/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/widget/controller.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,oBAAoB,EAAc,MAAM,UAAU,CAAA;AAIhE,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,GAAG,CAA2B;IACtC,OAAO,CAAC,GAAG,CAAwB;IACnC,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,KAAK,CAA4B;IACzC,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,iBAAiB,CAAqC;IAC9D,OAAO,CAAC,SAAS,CAAW;IAC5B,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,mBAAmB,CAAmC;IAC9D,OAAO,CAAC,QAAQ,CAAgC;IAChD,OAAO,CAAC,IAAI,CAAe;IAC3B,OAAO,CAAC,iBAAiB,CAA0B;IACnD,OAAO,CAAC,aAAa,CAA6B;IAClD,OAAO,CAAC,SAAS,CAAgC;IACjD,OAAO,CAAC,gBAAgB,CAA+B;gBAE3C,MAAM,EAAE,oBAAoB;IAcxC,OAAO,CAAC,OAAO;IAef,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,iBAAiB;IAYzB,OAAO,CAAC,wBAAwB;IAKhC,OAAO,CAAC,mBAAmB;IAiB3B,OAAO,CAAC,uBAAuB;YAejB,kBAAkB;IAgBhC,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,SAAS;YAcH,YAAY;IAkC1B,OAAO,CAAC,WAAW;IAUnB,OAAO,CAAC,OAAO;IAef,OAAO,IAAI,IAAI;CAWhB"}

package/dist/widget/controller.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=controller.test.d.ts.map

package/dist/widget/controller.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.test.d.ts","sourceRoot":"","sources":["../../src/widget/controller.test.ts"],"names":[],"mappings":""}

package/dist/widget/frustration-prompt.d.ts

@@ -0,0 +1,11 @@
+import type { ShadowContainer } from './shadow';
+import type { I18nMessages } from '../i18n';
+export declare class FrustrationPromptCard {
+    private el;
+    constructor(shadow: ShadowContainer, messages: I18nMessages, handlers: {
+        onTell: () => void;
+        onDismiss: () => void;
+    });
+    destroy(): void;
+}
+//# sourceMappingURL=frustration-prompt.d.ts.map

package/dist/widget/frustration-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frustration-prompt.d.ts","sourceRoot":"","sources":["../../src/widget/frustration-prompt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAI3C,qBAAa,qBAAqB;IAChC,OAAO,CAAC,EAAE,CAAgB;gBAGxB,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,YAAY,EACtB,QAAQ,EAAE;QAAE,MAAM,EAAE,MAAM,IAAI,CAAC;QAAC,SAAS,EAAE,MAAM,IAAI,CAAA;KAAE;IAmBzD,OAAO,IAAI,IAAI;CAGhB"}

package/dist/widget/frustration-prompt.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=frustration-prompt.test.d.ts.map

package/dist/widget/frustration-prompt.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frustration-prompt.test.d.ts","sourceRoot":"","sources":["../../src/widget/frustration-prompt.test.ts"],"names":[],"mappings":""}

package/dist/widget/payload.d.ts

@@ -0,0 +1,5 @@
+import type { PageContext } from '../context/collector';
+import type { Annotation, FeedbackPayload, MakeThisBetterConfig } from '../types';
+import type { RecordingResult } from '../record/session';
+export declare function buildPayload(description: string, pageContext: PageContext, consoleErrors: string[], annotation: Annotation | null, user: MakeThisBetterConfig['user'], recording?: RecordingResult): FeedbackPayload;
+//# sourceMappingURL=payload.d.ts.map

package/dist/widget/payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../../src/widget/payload.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAExD,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,WAAW,EACxB,aAAa,EAAE,MAAM,EAAE,EACvB,UAAU,EAAE,UAAU,GAAG,IAAI,EAC7B,IAAI,EAAE,oBAAoB,CAAC,MAAM,CAAC,EAClC,SAAS,CAAC,EAAE,eAAe,GAC1B,eAAe,CAmBjB"}

package/dist/widget/payload.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=payload.test.d.ts.map

package/dist/widget/payload.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.test.d.ts","sourceRoot":"","sources":["../../src/widget/payload.test.ts"],"names":[],"mappings":""}

package/dist/widget/pet.d.ts

@@ -0,0 +1,12 @@
+import type { ShadowContainer } from './shadow';
+import type { I18nMessages } from '../i18n';
+export declare class PetEntry {
+    private el;
+    private bubble;
+    private onClick;
+    constructor(shadow: ShadowContainer, messages: I18nMessages, onClick: () => void);
+    private buildSVG;
+    setActive(active: boolean): void;
+    destroy(): void;
+}
+//# sourceMappingURL=pet.d.ts.map

package/dist/widget/pet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pet.d.ts","sourceRoot":"","sources":["../../src/widget/pet.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAG3C,qBAAa,QAAQ;IACnB,OAAO,CAAC,EAAE,CAAgB;IAC1B,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,OAAO,CAAY;gBAGzB,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,MAAM,IAAI;IAyBrB,OAAO,CAAC,QAAQ;IAkBhB,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAOhC,OAAO,IAAI,IAAI;CAIhB"}

package/dist/widget/pet.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pet.test.d.ts.map

package/dist/widget/pet.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pet.test.d.ts","sourceRoot":"","sources":["../../src/widget/pet.test.ts"],"names":[],"mappings":""}

package/dist/widget/shadow.d.ts

@@ -0,0 +1,11 @@
+import type { MakeThisBetterConfig } from '../types';
+export declare class ShadowContainer {
+    private host;
+    readonly root: ShadowRoot;
+    constructor(theme?: MakeThisBetterConfig['theme']);
+    el<T extends HTMLElement = HTMLElement>(tag: string, className?: string): T;
+    append(...nodes: Node[]): void;
+    remove(...nodes: Node[]): void;
+    destroy(): void;
+}
+//# sourceMappingURL=shadow.d.ts.map

package/dist/widget/shadow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadow.d.ts","sourceRoot":"","sources":["../../src/widget/shadow.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAEpD,qBAAa,eAAe;IAC1B,OAAO,CAAC,IAAI,CAAa;IACzB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;gBAEb,KAAK,GAAE,oBAAoB,CAAC,OAAO,CAAU;IAczD,EAAE,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC;IAM3E,MAAM,CAAC,GAAG,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI;IAI9B,MAAM,CAAC,GAAG,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI;IAM9B,OAAO,IAAI,IAAI;CAGhB"}

package/dist/widget/shadow.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=shadow.test.d.ts.map

package/dist/widget/shadow.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadow.test.d.ts","sourceRoot":"","sources":["../../src/widget/shadow.test.ts"],"names":[],"mappings":""}

package/dist/widget/tab.d.ts

@@ -0,0 +1,10 @@
+import type { ShadowContainer } from './shadow';
+import type { I18nMessages } from '../i18n';
+export declare class FeedbackTab {
+    private el;
+    private onClick;
+    constructor(shadow: ShadowContainer, messages: I18nMessages, position: 'left' | 'right', onClick: () => void);
+    setActive(active: boolean): void;
+    destroy(): void;
+}
+//# sourceMappingURL=tab.d.ts.map

package/dist/widget/tab.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tab.d.ts","sourceRoot":"","sources":["../../src/widget/tab.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE3C,qBAAa,WAAW;IACtB,OAAO,CAAC,EAAE,CAAmB;IAC7B,OAAO,CAAC,OAAO,CAAY;gBAGzB,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,YAAY,EACtB,QAAQ,EAAE,MAAM,GAAG,OAAO,EAC1B,OAAO,EAAE,MAAM,IAAI;IAWrB,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAIhC,OAAO,IAAI,IAAI;CAIhB"}

package/dist/widget/tab.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tab.test.d.ts.map

package/dist/widget/tab.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tab.test.d.ts","sourceRoot":"","sources":["../../src/widget/tab.test.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "makethisbetter",
+  "version": "1.0.0",
+  "description": "Make This Better JS Widget SDK — embed user feedback collection in any website",
+  "type": "module",
+  "main": "./dist/makethisbetter.cjs.js",
+  "module": "./dist/makethisbetter.esm.js",
+  "types": "./dist/index.d.ts",
+  "unpkg": "./dist/makethisbetter.js",
+  "jsdelivr": "./dist/makethisbetter.js",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/makethisbetter.esm.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/makethisbetter.cjs.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "dev": "vite serve demo",
+    "build": "vite build && vite build --config vite.iife.config.ts && tsc --emitDeclarationOnly --declaration --declarationDir dist && cp dist/index.d.ts dist/index.d.mts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit",
+    "lint": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^1.5.0",
+    "jsdom": "^24.0.0",
+    "rrweb": "^2.1.0",
+    "typescript": "^5.4.0",
+    "vite": "^5.2.0",
+    "vitest": "^1.5.0"
+  },
+  "dependencies": {
+    "html-to-image": "^1.11.11"
+  },
+  "peerDependencies": {
+    "rrweb": "^2.1.0"
+  },
+  "peerDependenciesMeta": {
+    "rrweb": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "feedback",
+    "widget",
+    "user-feedback",
+    "bug-reporting",
+    "annotation"
+  ],
+  "license": "BSL-1.1"
+}

package/src/annotate/draw.test.ts

@@ -0,0 +1,168 @@
+import { afterEach, describe, it, expect, vi } from 'vitest'
+import { ShadowContainer } from '../widget/shadow'
+import { DrawLayer } from './draw'
+
+const SVG_SEL = 'svg[class="mtb-draw-svg"]'
+
+describe('DrawLayer', () => {
+  let shadow: ShadowContainer
+  let onDrawComplete: ReturnType<typeof vi.fn>
+  let draw: DrawLayer
+
+  function setup() {
+    shadow = new ShadowContainer()
+    onDrawComplete = vi.fn()
+    draw = new DrawLayer(shadow, onDrawComplete)
+  }
+
+  afterEach(() => {
+    draw.destroy()
+    shadow.destroy()
+    document.body.innerHTML = ''
+  })
+
+  describe('constructor', () => {
+    it('appends an SVG element to the shadow root', () => {
+      setup()
+      const svg = shadow.root.querySelector(SVG_SEL)
+      expect(svg).toBeTruthy()
+      expect(svg!.tagName).toBe('svg')
+    })
+  })
+
+  describe('startDraw', () => {
+    it('creates a path element in the SVG', () => {
+      setup()
+      draw.startDraw(10, 20)
+      const path = shadow.root.querySelector(`${SVG_SEL} path`)
+      expect(path).toBeTruthy()
+      expect(path!.tagName).toBe('path')
+    })
+
+    it('sets isCurrentlyDrawing to true', () => {
+      setup()
+      expect(draw.isCurrentlyDrawing()).toBe(false)
+      draw.startDraw(10, 20)
+      expect(draw.isCurrentlyDrawing()).toBe(true)
+    })
+
+    it('initializes point count to 1', () => {
+      setup()
+      draw.startDraw(10, 20)
+      expect(draw.getPointCount()).toBe(1)
+    })
+  })
+
+  describe('continueDraw', () => {
+    it('adds points and updates the path d attribute', () => {
+      setup()
+      draw.startDraw(10, 20)
+      draw.continueDraw(30, 40)
+      const path = shadow.root.querySelector(`${SVG_SEL} path`)!
+      expect(path.getAttribute('d')).toContain('M 10 20')
+      expect(path.getAttribute('d')).toContain('L 30 40')
+      expect(draw.getPointCount()).toBe(2)
+    })
+
+    it('does nothing when not drawing', () => {
+      setup()
+      draw.continueDraw(30, 40)
+      expect(draw.getPointCount()).toBe(0)
+    })
+  })
+
+  describe('endDraw', () => {
+    it('calls onDrawComplete with a draw annotation when enough points', () => {
+      setup()
+      draw.startDraw(0, 0)
+      draw.continueDraw(10, 10)
+      draw.endDraw()
+
+      expect(onDrawComplete).toHaveBeenCalledOnce()
+      const annotation = onDrawComplete.mock.calls[0][0]
+      expect(annotation.type).toBe('draw')
+      expect(annotation.drawPath).toContain('M 0 0')
+      expect(annotation.drawPath).toContain('L 10 10')
+      expect(annotation.x).toBe(5)
+      expect(annotation.y).toBe(5)
+    })
+
+    it('removes the path and does not call callback with fewer than 2 points', () => {
+      setup()
+      draw.startDraw(10, 20)
+      draw.endDraw()
+
+      expect(onDrawComplete).not.toHaveBeenCalled()
+      expect(draw.isCurrentlyDrawing()).toBe(false)
+    })
+
+    it('does nothing when not currently drawing', () => {
+      setup()
+      draw.endDraw()
+      expect(onDrawComplete).not.toHaveBeenCalled()
+    })
+
+    it('sets isCurrentlyDrawing to false after ending', () => {
+      setup()
+      draw.startDraw(0, 0)
+      draw.continueDraw(10, 10)
+      draw.endDraw()
+      expect(draw.isCurrentlyDrawing()).toBe(false)
+    })
+  })
+
+  describe('clearAll', () => {
+    it('removes all SVG children and resets state', () => {
+      setup()
+      draw.startDraw(0, 0)
+      draw.continueDraw(10, 10)
+      draw.clearAll()
+
+      expect(shadow.root.querySelector(SVG_SEL)!.childElementCount).toBe(0)
+      expect(draw.isCurrentlyDrawing()).toBe(false)
+      expect(draw.getPointCount()).toBe(0)
+    })
+  })
+
+  describe('cancelCurrentDraw', () => {
+    it('removes the current path and resets drawing state', () => {
+      setup()
+      draw.startDraw(0, 0)
+      draw.continueDraw(10, 10)
+      draw.cancelCurrentDraw()
+
+      expect(draw.isCurrentlyDrawing()).toBe(false)
+      expect(draw.getPointCount()).toBe(0)
+      const svg = shadow.root.querySelector(SVG_SEL)!
+      expect(svg.querySelector('path')).toBeNull()
+    })
+
+    it('is safe to call when not drawing', () => {
+      setup()
+      expect(() => draw.cancelCurrentDraw()).not.toThrow()
+    })
+  })
+
+  describe('destroy', () => {
+    it('removes the SVG element from the shadow root', () => {
+      setup()
+      draw.destroy()
+      expect(shadow.root.querySelector(SVG_SEL)).toBeNull()
+    })
+  })
+
+  describe('getCenter calculation', () => {
+    it('computes the center of the bounding box of all points', () => {
+      setup()
+      draw.startDraw(0, 0)
+      draw.continueDraw(100, 0)
+      draw.continueDraw(100, 100)
+      draw.continueDraw(0, 100)
+      draw.endDraw()
+
+      const annotation = onDrawComplete.mock.calls[0][0]
+      expect(annotation.x).toBe(50)
+      expect(annotation.y).toBe(50)
+    })
+  })
+})

package/src/annotate/draw.ts

@@ -0,0 +1,108 @@
+import type { ShadowContainer } from '../widget/shadow'
+import type { Annotation } from '../types'
+import { DRAW_STROKE } from '../styles'
+
+export class DrawLayer {
+  private svg: SVGSVGElement
+  private path: SVGPathElement | null = null
+  private points: [number, number][] = []
+  private isDrawing = false
+  private onDrawComplete: (annotation: Annotation) => void
+
+  constructor(shadow: ShadowContainer, onDrawComplete: (annotation: Annotation) => void) {
+    this.onDrawComplete = onDrawComplete
+
+    this.svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg')
+    this.svg.setAttribute('class', 'mtb-draw-svg')
+    shadow.append(this.svg)
+  }
+
+  startDraw(x: number, y: number): void {
+    this.isDrawing = true
+    this.points = [[x, y]]
+
+    this.path = document.createElementNS('http://www.w3.org/2000/svg', 'path')
+    this.path.setAttribute('fill', 'none')
+    this.path.setAttribute('stroke', DRAW_STROKE.color)
+    this.path.setAttribute('stroke-width', DRAW_STROKE.width)
+    this.path.setAttribute('stroke-linecap', DRAW_STROKE.linecap)
+    this.path.setAttribute('stroke-linejoin', DRAW_STROKE.linejoin)
+    this.path.setAttribute('style', `filter:${DRAW_STROKE.filter}`)
+    this.svg.appendChild(this.path)
+  }
+
+  continueDraw(x: number, y: number): void {
+    if (!this.isDrawing || !this.path) return
+    this.points.push([x, y])
+    this.path.setAttribute('d', this.buildPathD())
+  }
+
+  endDraw(): void {
+    if (!this.isDrawing || this.points.length < 2) {
+      this.isDrawing = false
+      if (this.path) {
+        this.path.remove()
+        this.path = null
+      }
+      return
+    }
+    this.isDrawing = false
+
+    const center = this.getCenter()
+    const pathD = this.buildPathD()
+
+    const annotation: Annotation = {
+      type: 'draw',
+      x: center[0],
+      y: center[1],
+      drawPath: pathD,
+    }
+
+    this.onDrawComplete(annotation)
+  }
+
+  private buildPathD(): string {
+    if (this.points.length === 0) return ''
+    const [fx, fy] = this.points[0]
+    let d = `M ${fx} ${fy}`
+    for (let i = 1; i < this.points.length; i++) {
+      const [x, y] = this.points[i]
+      d += ` L ${x} ${y}`
+    }
+    return d
+  }
+
+  private getCenter(): [number, number] {
+    const xs = this.points.map(p => p[0])
+    const ys = this.points.map(p => p[1])
+    const cx = (Math.min(...xs) + Math.max(...xs)) / 2
+    const cy = (Math.min(...ys) + Math.max(...ys)) / 2
+    return [cx, cy]
+  }
+
+  clearAll(): void {
+    while (this.svg.firstChild) this.svg.removeChild(this.svg.firstChild)
+    this.path = null
+    this.isDrawing = false
+    this.points = []
+  }
+
+  cancelCurrentDraw(): void {
+    this.path?.remove()
+    this.path = null
+    this.isDrawing = false
+    this.points = []
+  }
+
+  isCurrentlyDrawing(): boolean {
+    return this.isDrawing
+  }
+
+  getPointCount(): number {
+    return this.points.length
+  }
+
+  destroy(): void {
+    this.svg.remove()
+  }
+}

package/src/annotate/highlighter.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from 'vitest'
+import { getElementName, getCssSelector } from './highlighter'
+
+describe('getElementName', () => {
+  it('returns aria-label when present', () => {
+    const el = document.createElement('button')
+    el.setAttribute('aria-label', 'Close dialog')
+    expect(getElementName(el)).toBe('Close dialog')
+  })
+
+  it('returns text content when no label', () => {
+    const el = document.createElement('button')
+    el.textContent = 'Export PDF'
+    expect(getElementName(el)).toBe('Export PDF')
+  })
+
+  it('returns tag name as fallback', () => {
+    const el = document.createElementNS('http://www.w3.org/2000/svg', 'svg')
+    expect(getElementName(el)).toBe('svg')
+  })
+
+  it('truncates long text content', () => {
+    const el = document.createElement('p')
+    el.textContent = 'a'.repeat(100)
+    expect(getElementName(el).length).toBeLessThanOrEqual(40)
+  })
+})
+
+describe('getCssSelector', () => {
+  it('returns id selector when element has id', () => {
+    const el = document.createElement('div')
+    el.id = 'main'
+    document.body.appendChild(el)
+    expect(getCssSelector(el)).toBe('#main')
+    document.body.removeChild(el)
+  })
+
+  it('returns tag selector for unknown element', () => {
+    const el = document.createElement('span')
+    const parent = document.createElement('div')
+    parent.appendChild(el)
+    document.body.appendChild(parent)
+    const selector = getCssSelector(el)
+    expect(selector).toContain('span')
+    document.body.removeChild(parent)
+  })
+})

package/src/annotate/highlighter.ts

@@ -0,0 +1,84 @@
+import type { ShadowContainer } from '../widget/shadow'
+
+export class ElementHighlighter {
+  private highlightEl: HTMLDivElement
+
+  constructor(shadow: ShadowContainer) {
+    this.highlightEl = shadow.el<HTMLDivElement>('div', 'mtb-highlight')
+    this.hide()
+    shadow.append(this.highlightEl)
+  }
+
+  highlight(el: Element): void {
+    const rect = el.getBoundingClientRect()
+    this.highlightEl.style.top = `${rect.top - 2}px`
+    this.highlightEl.style.left = `${rect.left - 2}px`
+    this.highlightEl.style.width = `${rect.width + 4}px`
+    this.highlightEl.style.height = `${rect.height + 4}px`
+    this.highlightEl.style.display = 'block'
+  }
+
+  hide(): void {
+    this.highlightEl.style.display = 'none'
+  }
+
+  destroy(): void {
+    this.highlightEl.remove()
+  }
+}
+
+export function getElementName(el: Element): string {
+  if (el instanceof HTMLElement) {
+    const label = el.getAttribute('aria-label')
+    if (label) return label
+
+    const title = el.getAttribute('title')
+    if (title) return title
+
+    const text = el.textContent?.trim().slice(0, 40)
+    if (text) return text
+
+    const placeholder = (el as HTMLInputElement).placeholder
+    if (placeholder) return placeholder
+
+    const alt = (el as HTMLImageElement).alt
+    if (alt) return alt
+
+    const dataMark = el.getAttribute('data-mark')
+    if (dataMark) return dataMark
+  }
+  return el.tagName.toLowerCase()
+}
+
+export function getCssSelector(el: Element): string {
+  const parts: string[] = []
+  let current: Element | null = el
+  while (current && current !== document.body && parts.length < 5) {
+    let selector = current.tagName.toLowerCase()
+    if (current.id) {
+      selector = `#${current.id}`
+      parts.unshift(selector)
+      break
+    }
+    const classNames = Array.from(current.classList)
+      .filter(c => !c.startsWith('mtb-'))
+      .slice(0, 2)
+      .join('.')
+    if (classNames) selector += `.${classNames}`
+
+    const parent = current.parentElement
+    if (parent) {
+      const siblings = Array.from(parent.children).filter(
+        c => c.tagName === current!.tagName,
+      )
+      if (siblings.length > 1) {
+        const idx = siblings.indexOf(current) + 1
+        selector += `:nth-child(${idx})`
+      }
+    }
+
+    parts.unshift(selector)
+    current = current.parentElement
+  }
+  return parts.join(' > ')
+}