makethisbetter 1.0.0

package/src/annotate/overlay.test.ts

@@ -0,0 +1,91 @@
+import { afterEach, describe, it, expect, vi } from 'vitest'
+import { ShadowContainer } from '../widget/shadow'
+import { AnnotationOverlay } from './overlay'
+
+describe('AnnotationOverlay', () => {
+  let shadow: ShadowContainer
+  let handlers: {
+    onMouseDown: ReturnType<typeof vi.fn>
+    onMouseMove: ReturnType<typeof vi.fn>
+    onMouseUp: ReturnType<typeof vi.fn>
+    onMouseLeave: ReturnType<typeof vi.fn>
+  }
+  let overlay: AnnotationOverlay
+
+  function setup() {
+    shadow = new ShadowContainer()
+    handlers = {
+      onMouseDown: vi.fn(),
+      onMouseMove: vi.fn(),
+      onMouseUp: vi.fn(),
+      onMouseLeave: vi.fn(),
+    }
+    overlay = new AnnotationOverlay(shadow, handlers)
+  }
+
+  afterEach(() => {
+    document.body.innerHTML = ''
+  })
+
+  describe('constructor', () => {
+    it('creates overlay and dim elements in the shadow root', () => {
+      setup()
+      expect(shadow.root.querySelector('.mtb-overlay')).toBeInstanceOf(HTMLDivElement)
+      expect(shadow.root.querySelector('.mtb-dim')).toBeInstanceOf(HTMLDivElement)
+      overlay.destroy()
+    })
+  })
+
+  describe('mouse event handlers', () => {
+    it('dispatches mousedown to the handler', () => {
+      setup()
+      const overlayEl = shadow.root.querySelector('.mtb-overlay')!
+      overlayEl.dispatchEvent(new MouseEvent('mousedown', { bubbles: true }))
+      expect(handlers.onMouseDown).toHaveBeenCalledOnce()
+      overlay.destroy()
+    })
+
+    it('dispatches mousemove to the handler', () => {
+      setup()
+      const overlayEl = shadow.root.querySelector('.mtb-overlay')!
+      overlayEl.dispatchEvent(new MouseEvent('mousemove', { bubbles: true }))
+      expect(handlers.onMouseMove).toHaveBeenCalledOnce()
+      overlay.destroy()
+    })
+
+    it('dispatches mouseup to the handler', () => {
+      setup()
+      const overlayEl = shadow.root.querySelector('.mtb-overlay')!
+      overlayEl.dispatchEvent(new MouseEvent('mouseup', { bubbles: true }))
+      expect(handlers.onMouseUp).toHaveBeenCalledOnce()
+      overlay.destroy()
+    })
+
+    it('dispatches mouseleave to the handler', () => {
+      setup()
+      const overlayEl = shadow.root.querySelector('.mtb-overlay')!
+      overlayEl.dispatchEvent(new MouseEvent('mouseleave', { bubbles: true }))
+      expect(handlers.onMouseLeave).toHaveBeenCalledOnce()
+      overlay.destroy()
+    })
+  })
+
+  describe('destroy', () => {
+    it('removes overlay and dim elements from the shadow root', () => {
+      setup()
+      overlay.destroy()
+      expect(shadow.root.querySelector('.mtb-overlay')).toBeNull()
+      expect(shadow.root.querySelector('.mtb-dim')).toBeNull()
+    })
+
+    it('removes event listeners so handlers are not called after destroy', () => {
+      setup()
+      const overlayEl = shadow.root.querySelector('.mtb-overlay')!
+      overlay.destroy()
+
+      handlers.onMouseDown.mockClear()
+      overlayEl.dispatchEvent(new MouseEvent('mousedown', { bubbles: true }))
+      expect(handlers.onMouseDown).not.toHaveBeenCalled()
+    })
+  })
+})

package/src/annotate/overlay.ts

@@ -0,0 +1,44 @@
+import type { ShadowContainer } from '../widget/shadow'
+
+export class AnnotationOverlay {
+  private overlayEl: HTMLDivElement
+  private dimEl: HTMLDivElement
+  private onMouseDown: (e: MouseEvent) => void
+  private onMouseMove: (e: MouseEvent) => void
+  private onMouseUp: (e: MouseEvent) => void
+  private onMouseLeave: (e: MouseEvent) => void
+
+  constructor(
+    shadow: ShadowContainer,
+    handlers: {
+      onMouseDown: (e: MouseEvent) => void
+      onMouseMove: (e: MouseEvent) => void
+      onMouseUp: (e: MouseEvent) => void
+      onMouseLeave: (e: MouseEvent) => void
+    },
+  ) {
+    this.onMouseDown = handlers.onMouseDown
+    this.onMouseMove = handlers.onMouseMove
+    this.onMouseUp = handlers.onMouseUp
+    this.onMouseLeave = handlers.onMouseLeave
+
+    this.overlayEl = shadow.el<HTMLDivElement>('div', 'mtb-overlay')
+    this.overlayEl.addEventListener('mousedown', this.onMouseDown)
+    this.overlayEl.addEventListener('mousemove', this.onMouseMove)
+    this.overlayEl.addEventListener('mouseup', this.onMouseUp)
+    this.overlayEl.addEventListener('mouseleave', this.onMouseLeave)
+    shadow.append(this.overlayEl)
+
+    this.dimEl = shadow.el<HTMLDivElement>('div', 'mtb-dim')
+    shadow.append(this.dimEl)
+  }
+
+  destroy(): void {
+    this.overlayEl.removeEventListener('mousedown', this.onMouseDown)
+    this.overlayEl.removeEventListener('mousemove', this.onMouseMove)
+    this.overlayEl.removeEventListener('mouseup', this.onMouseUp)
+    this.overlayEl.removeEventListener('mouseleave', this.onMouseLeave)
+    this.overlayEl.remove()
+    this.dimEl.remove()
+  }
+}

package/src/annotate/pin.test.ts

@@ -0,0 +1,87 @@
+import { afterEach, describe, it, expect } from 'vitest'
+import { ShadowContainer } from '../widget/shadow'
+import { PinMarker } from './pin'
+
+describe('PinMarker', () => {
+  let shadow: ShadowContainer
+  let pin: PinMarker
+
+  function setup() {
+    shadow = new ShadowContainer()
+    pin = new PinMarker(shadow)
+  }
+
+  afterEach(() => {
+    document.body.innerHTML = ''
+  })
+
+  describe('constructor', () => {
+    it('creates an instance without adding any pins', () => {
+      setup()
+      expect(shadow.root.querySelectorAll('.mtb-pin').length).toBe(0)
+      pin.destroy()
+    })
+  })
+
+  describe('addPin', () => {
+    it('adds a pin element to the shadow root', () => {
+      setup()
+      pin.addPin(100, 200, 1)
+      const pinEl = shadow.root.querySelector('.mtb-pin')
+      expect(pinEl).toBeInstanceOf(HTMLDivElement)
+      expect(pinEl!.textContent).toBe('1')
+      expect((pinEl as HTMLDivElement).style.top).toBe('200px')
+      expect((pinEl as HTMLDivElement).style.left).toBe('100px')
+      pin.destroy()
+    })
+
+    it('adds multiple pins with sequential indices', () => {
+      setup()
+      pin.addPin(10, 20, 1)
+      pin.addPin(30, 40, 2)
+      pin.addPin(50, 60, 3)
+      const pins = shadow.root.querySelectorAll('.mtb-pin')
+      expect(pins.length).toBe(3)
+      expect(pins[0].textContent).toBe('1')
+      expect(pins[1].textContent).toBe('2')
+      expect(pins[2].textContent).toBe('3')
+      pin.destroy()
+    })
+  })
+
+  describe('clearAll', () => {
+    it('removes all pin elements from the shadow root', () => {
+      setup()
+      pin.addPin(10, 20, 1)
+      pin.addPin(30, 40, 2)
+      pin.clearAll()
+      expect(shadow.root.querySelectorAll('.mtb-pin').length).toBe(0)
+      pin.destroy()
+    })
+
+    it('is safe to call when no pins exist', () => {
+      setup()
+      expect(() => pin.clearAll()).not.toThrow()
+      pin.destroy()
+    })
+
+    it('allows adding new pins after clearing', () => {
+      setup()
+      pin.addPin(10, 20, 1)
+      pin.clearAll()
+      pin.addPin(50, 60, 1)
+      expect(shadow.root.querySelectorAll('.mtb-pin').length).toBe(1)
+      pin.destroy()
+    })
+  })
+
+  describe('destroy', () => {
+    it('removes all pins via clearAll', () => {
+      setup()
+      pin.addPin(10, 20, 1)
+      pin.addPin(30, 40, 2)
+      pin.destroy()
+      expect(shadow.root.querySelectorAll('.mtb-pin').length).toBe(0)
+    })
+  })
+})

package/src/annotate/pin.ts

@@ -0,0 +1,28 @@
+import type { ShadowContainer } from '../widget/shadow'
+
+export class PinMarker {
+  private pins: HTMLDivElement[] = []
+  private shadow: ShadowContainer
+
+  constructor(shadow: ShadowContainer) {
+    this.shadow = shadow
+  }
+
+  addPin(x: number, y: number, index: number): void {
+    const pin = this.shadow.el<HTMLDivElement>('div', 'mtb-pin')
+    pin.textContent = String(index)
+    pin.style.top = `${y}px`
+    pin.style.left = `${x}px`
+    this.shadow.append(pin)
+    this.pins.push(pin)
+  }
+
+  clearAll(): void {
+    for (const pin of this.pins) pin.remove()
+    this.pins = []
+  }
+
+  destroy(): void {
+    this.clearAll()
+  }
+}

package/src/annotate/session.test.ts

@@ -0,0 +1,219 @@
+import { afterEach, beforeEach, describe, it, expect, vi } from 'vitest'
+import { ShadowContainer } from '../widget/shadow'
+import { AnnotationSession } from './session'
+import { getMessages } from '../i18n'
+
+const SVG_SEL = 'svg[class="mtb-draw-svg"]'
+
+describe('AnnotationSession', () => {
+  let shadow: ShadowContainer
+  let session: AnnotationSession
+  let onReady: ReturnType<typeof vi.fn>
+  const messages = getMessages('en')
+
+  beforeEach(() => {
+    // jsdom does not implement elementFromPoint — stub it
+    document.elementFromPoint = vi.fn().mockReturnValue(null)
+  })
+
+  function setup() {
+    shadow = new ShadowContainer()
+    onReady = vi.fn()
+    session = new AnnotationSession(shadow, messages, onReady)
+  }
+
+  afterEach(() => {
+    document.body.innerHTML = ''
+    vi.restoreAllMocks()
+  })
+
+  describe('constructor', () => {
+    it('creates overlay, highlighter, pin, and draw elements in shadow root', () => {
+      setup()
+      expect(shadow.root.querySelector('.mtb-overlay')).toBeInstanceOf(HTMLDivElement)
+      expect(shadow.root.querySelector('.mtb-highlight')).toBeInstanceOf(HTMLDivElement)
+      expect(shadow.root.querySelector(SVG_SEL)).toBeTruthy()
+      expect(shadow.root.querySelector('.mtb-dim')).toBeInstanceOf(HTMLDivElement)
+      session.destroy()
+    })
+  })
+
+  describe('pin annotation via short click', () => {
+    it('creates a pin annotation on mousedown + mouseup with fewer than 5 points', () => {
+      setup()
+      const overlayEl = shadow.root.querySelector('.mtb-overlay')!
+
+      overlayEl.dispatchEvent(
+        new MouseEvent('mousedown', { clientX: 100, clientY: 200, bubbles: true }),
+      )
+      overlayEl.dispatchEvent(
+        new MouseEvent('mouseup', { clientX: 100, clientY: 200, bubbles: true }),
+      )
+
+      expect(onReady).toHaveBeenCalledOnce()
+      const [annotation] = onReady.mock.calls[0]
+      expect(annotation.type).toBe('pin')
+      expect(annotation.x).toBe(100)
+      expect(annotation.y).toBe(200)
+      session.destroy()
+    })
+
+    it('adds a pin marker to the shadow root', () => {
+      setup()
+      const overlayEl = shadow.root.querySelector('.mtb-overlay')!
+
+      overlayEl.dispatchEvent(
+        new MouseEvent('mousedown', { clientX: 50, clientY: 50, bubbles: true }),
+      )
+      overlayEl.dispatchEvent(
+        new MouseEvent('mouseup', { clientX: 50, clientY: 50, bubbles: true }),
+      )
+
+      const pin = shadow.root.querySelector('.mtb-pin')
+      expect(pin).toBeInstanceOf(HTMLDivElement)
+      expect(pin!.textContent).toBe('1')
+      session.destroy()
+    })
+
+    it('increments pin count on successive clicks', () => {
+      setup()
+      const overlayEl = shadow.root.querySelector('.mtb-overlay')!
+
+      for (let i = 0; i < 3; i++) {
+        overlayEl.dispatchEvent(
+          new MouseEvent('mousedown', { clientX: 10 * i, clientY: 10 * i, bubbles: true }),
+        )
+        overlayEl.dispatchEvent(
+          new MouseEvent('mouseup', { clientX: 10 * i, clientY: 10 * i, bubbles: true }),
+        )
+      }
+
+      const pins = shadow.root.querySelectorAll('.mtb-pin')
+      expect(pins.length).toBe(3)
+      expect(pins[0].textContent).toBe('1')
+      expect(pins[1].textContent).toBe('2')
+      expect(pins[2].textContent).toBe('3')
+      session.destroy()
+    })
+
+    it('uses element name from elementFromPoint when an element is found', () => {
+      setup()
+      const btn = document.createElement('button')
+      btn.setAttribute('aria-label', 'Save')
+      ;(document.elementFromPoint as ReturnType<typeof vi.fn>).mockReturnValue(btn)
+
+      const overlayEl = shadow.root.querySelector('.mtb-overlay')!
+      overlayEl.dispatchEvent(
+        new MouseEvent('mousedown', { clientX: 50, clientY: 50, bubbles: true }),
+      )
+      overlayEl.dispatchEvent(
+        new MouseEvent('mouseup', { clientX: 50, clientY: 50, bubbles: true }),
+      )
+
+      const [annotation, targetName] = onReady.mock.calls[0]
+      expect(targetName).toBe('Save')
+      expect(annotation.targetName).toBe('Save')
+      session.destroy()
+    })
+
+    it('falls back to messages.annotation.element when no element under cursor', () => {
+      setup()
+      ;(document.elementFromPoint as ReturnType<typeof vi.fn>).mockReturnValue(null)
+
+      const overlayEl = shadow.root.querySelector('.mtb-overlay')!
+      overlayEl.dispatchEvent(
+        new MouseEvent('mousedown', { clientX: 50, clientY: 50, bubbles: true }),
+      )
+      overlayEl.dispatchEvent(
+        new MouseEvent('mouseup', { clientX: 50, clientY: 50, bubbles: true }),
+      )
+
+      const [, targetName] = onReady.mock.calls[0]
+      expect(targetName).toBe(messages.annotation.element)
+      session.destroy()
+    })
+  })
+
+  describe('draw annotation via drag', () => {
+    it('creates a draw annotation when enough points are collected', () => {
+      setup()
+      const overlayEl = shadow.root.querySelector('.mtb-overlay')!
+
+      overlayEl.dispatchEvent(
+        new MouseEvent('mousedown', { clientX: 0, clientY: 0, bubbles: true }),
+      )
+      for (let i = 1; i <= 5; i++) {
+        overlayEl.dispatchEvent(
+          new MouseEvent('mousemove', { clientX: i * 10, clientY: i * 10, bubbles: true }),
+        )
+      }
+      overlayEl.dispatchEvent(
+        new MouseEvent('mouseup', { clientX: 50, clientY: 50, bubbles: true }),
+      )
+
+      expect(onReady).toHaveBeenCalledOnce()
+      const [annotation, targetName] = onReady.mock.calls[0]
+      expect(annotation.type).toBe('draw')
+      expect(annotation.drawPath).toBeDefined()
+      expect(targetName).toBe(messages.annotation.drawing)
+      session.destroy()
+    })
+  })
+
+  describe('mouseleave', () => {
+    it('ends drawing when mouse leaves the overlay', () => {
+      setup()
+      const overlayEl = shadow.root.querySelector('.mtb-overlay')!
+
+      overlayEl.dispatchEvent(
+        new MouseEvent('mousedown', { clientX: 0, clientY: 0, bubbles: true }),
+      )
+      for (let i = 1; i <= 5; i++) {
+        overlayEl.dispatchEvent(
+          new MouseEvent('mousemove', { clientX: i * 10, clientY: i * 10, bubbles: true }),
+        )
+      }
+      overlayEl.dispatchEvent(new MouseEvent('mouseleave', { bubbles: true }))
+
+      expect(onReady).toHaveBeenCalledOnce()
+      session.destroy()
+    })
+  })
+
+  describe('dismissInteraction', () => {
+    it('removes overlay and highlighter but keeps pins and draw layer', () => {
+      setup()
+      session.dismissInteraction()
+
+      expect(shadow.root.querySelector('.mtb-overlay')).toBeNull()
+      expect(shadow.root.querySelector('.mtb-highlight')).toBeNull()
+      expect(shadow.root.querySelector(SVG_SEL)).toBeTruthy()
+      session.destroy()
+    })
+
+    it('is idempotent — second call does not throw', () => {
+      setup()
+      session.dismissInteraction()
+      expect(() => session.dismissInteraction()).not.toThrow()
+      session.destroy()
+    })
+  })
+
+  describe('destroy', () => {
+    it('removes all elements from the shadow root', () => {
+      setup()
+      session.destroy()
+
+      expect(shadow.root.querySelector('.mtb-overlay')).toBeNull()
+      expect(shadow.root.querySelector('.mtb-highlight')).toBeNull()
+      expect(shadow.root.querySelector('.mtb-pin')).toBeNull()
+      expect(shadow.root.querySelector(SVG_SEL)).toBeNull()
+    })
+
+    it('is safe to call after dismissInteraction', () => {
+      setup()
+      session.dismissInteraction()
+      expect(() => session.destroy()).not.toThrow()
+    })
+  })
+})

package/src/annotate/session.ts

@@ -0,0 +1,104 @@
+import type { ShadowContainer } from '../widget/shadow'
+import type { I18nMessages } from '../i18n'
+import type { Annotation } from '../types'
+import { AnnotationOverlay } from './overlay'
+import { ElementHighlighter, getElementName, getCssSelector } from './highlighter'
+import { PinMarker } from './pin'
+import { DrawLayer } from './draw'
+
+const DRAW_MIN_POINTS = 5
+
+export class AnnotationSession {
+  private overlay: AnnotationOverlay
+  private highlighter: ElementHighlighter
+  private pinMarker: PinMarker
+  private drawLayer: DrawLayer
+  private pinCount = 0
+  private interactionActive = true
+
+  constructor(
+    shadow: ShadowContainer,
+    private messages: I18nMessages,
+    private onReady: (annotation: Annotation, targetName: string) => void,
+  ) {
+    this.highlighter = new ElementHighlighter(shadow)
+    this.pinMarker = new PinMarker(shadow)
+    this.drawLayer = new DrawLayer(shadow, (annotation) => {
+      this.onReady(annotation, this.messages.annotation.drawing)
+    })
+    this.overlay = new AnnotationOverlay(shadow, {
+      onMouseDown: (e) => this.handleMouseDown(e),
+      onMouseMove: (e) => this.handleMouseMove(e),
+      onMouseUp: (e) => this.handleMouseUp(e),
+      onMouseLeave: () => {
+        if (this.drawLayer.isCurrentlyDrawing()) this.drawLayer.endDraw()
+        this.highlighter.hide()
+      },
+    })
+  }
+
+  private handleMouseDown(e: MouseEvent): void {
+    e.preventDefault()
+    this.drawLayer.startDraw(e.clientX, e.clientY)
+  }
+
+  private handleMouseMove(e: MouseEvent): void {
+    if (this.drawLayer.isCurrentlyDrawing()) {
+      this.drawLayer.continueDraw(e.clientX, e.clientY)
+      this.highlighter.hide()
+      return
+    }
+
+    const underEl = getElementUnder(e.clientX, e.clientY)
+    if (underEl) this.highlighter.highlight(underEl)
+    else this.highlighter.hide()
+  }
+
+  private handleMouseUp(e: MouseEvent): void {
+    if (!this.drawLayer.isCurrentlyDrawing()) return
+
+    if (this.drawLayer.getPointCount() >= DRAW_MIN_POINTS) {
+      this.drawLayer.endDraw()
+      return
+    }
+
+    this.drawLayer.cancelCurrentDraw()
+    const underEl = getElementUnder(e.clientX, e.clientY)
+    const targetName = underEl ? getElementName(underEl) : this.messages.annotation.element
+    const annotation: Annotation = {
+      type: 'pin',
+      x: e.clientX,
+      y: e.clientY,
+      targetSelector: underEl ? getCssSelector(underEl) : undefined,
+      targetText: underEl?.textContent?.trim().slice(0, 200) ?? '',
+      targetName,
+    }
+    this.pinMarker.addPin(e.clientX, e.clientY, ++this.pinCount)
+    this.drawLayer.clearAll()
+    this.highlighter.hide()
+    this.onReady(annotation, targetName)
+  }
+
+  dismissInteraction(): void {
+    if (!this.interactionActive) return
+    this.interactionActive = false
+    this.overlay.destroy()
+    this.highlighter.destroy()
+  }
+
+  destroy(): void {
+    this.dismissInteraction()
+    this.pinMarker.destroy()
+    this.drawLayer.destroy()
+  }
+}
+
+function getElementUnder(x: number, y: number): Element | null {
+  const host = document.getElementById('mtb-widget-host')
+  if (host) host.style.display = 'none'
+
+  const el = document.elementFromPoint(x, y)
+
+  if (host) host.style.display = ''
+  return el
+}