makethisbetter 1.0.0

package/src/styles.ts

@@ -0,0 +1,9 @@
+export const BRAND_COLOR = '#059669'
+
+export const DRAW_STROKE = {
+  color: BRAND_COLOR,
+  width: '3.5',
+  linecap: 'round',
+  linejoin: 'round',
+  filter: 'drop-shadow(0 1px 2px rgba(5,150,105,0.35))',
+} as const

package/src/types.ts

@@ -0,0 +1,46 @@
+export interface MakeThisBetterConfig {
+  projectKey: string
+  entryMode?: 'button' | 'pet'
+  locale?: string
+  position?: 'left' | 'right'
+  theme?: 'light' | 'dark' | 'auto'
+  apiUrl?: string
+  frustrationDetection?: boolean
+  user?: {
+    id?: string
+    email?: string
+    name?: string
+  }
+}
+
+export interface Annotation {
+  type: 'pin' | 'draw'
+  x: number
+  y: number
+  targetSelector?: string
+  targetText?: string
+  targetName?: string
+  drawPath?: string
+}
+
+export interface FeedbackPayload {
+  description: string
+  page_url: string
+  user_agent: string
+  browser: string
+  os: string
+  screen_width: number
+  screen_height: number
+  console_errors: string[]
+  annotations: Annotation[]
+  target_element?: {
+    selector: string
+    text: string
+    name: string
+  }
+  user_id?: string
+  user_email?: string
+  user_name?: string
+  recording_events?: Record<string, unknown>[]
+  recording_duration?: number
+}

package/src/vite-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="vite/client" />
+
+declare module '*.css?inline' {
+  const css: string
+  export default css
+}

package/src/widget/controller.test.ts

@@ -0,0 +1,62 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { MakeThisBetter } from '../index'
+
+vi.mock('html-to-image', () => ({
+  toPng: vi.fn(async () => 'data:image/png;base64,AA=='),
+}))
+
+describe('MakeThisBetter widget flow', () => {
+  afterEach(() => {
+    MakeThisBetter.destroy()
+    vi.restoreAllMocks()
+    document.body.innerHTML = ''
+  })
+
+  it('submits feedback from a pin annotation', async () => {
+    const target = document.createElement('button')
+    target.id = 'export-btn'
+    target.textContent = 'Export PDF'
+    document.body.appendChild(target)
+
+    document.elementFromPoint = vi.fn(() => target)
+
+    let capturedBody: FormData | null = null
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url: RequestInfo | URL, init?: RequestInit) => {
+      capturedBody = init?.body instanceof FormData ? init.body : null
+      return new Response(JSON.stringify({ id: 'fb_1' }), { status: 201 })
+    })
+
+    MakeThisBetter.init({
+      projectKey: 'proj_test',
+      apiUrl: 'https://api.example.com/api/v1',
+      user: { id: 'user_1', email: 'user@example.com', name: 'User One' },
+    })
+
+    const shadow = document.getElementById('mtb-widget-host')!.shadowRoot!
+    shadow.querySelector<HTMLButtonElement>('.mtb-tab')!.click()
+
+    const overlay = shadow.querySelector<HTMLDivElement>('.mtb-overlay')!
+    overlay.dispatchEvent(new MouseEvent('mousedown', { clientX: 20, clientY: 30, bubbles: true }))
+    overlay.dispatchEvent(new MouseEvent('mouseup', { clientX: 20, clientY: 30, bubbles: true }))
+
+    const textarea = shadow.querySelector<HTMLTextAreaElement>('.mtb-textarea')!
+    textarea.value = 'Export is broken'
+    textarea.dispatchEvent(new Event('input'))
+    shadow.querySelector<HTMLButtonElement>('.mtb-submit-btn')!.click()
+
+    await vi.waitFor(() => {
+      expect(fetchSpy).toHaveBeenCalled()
+    })
+
+    const formData = capturedBody as unknown as FormData
+    expect(formData.get('feedback[description]')).toBe('Export is broken')
+    expect(formData.get('feedback[user_id]')).toBe('user_1')
+    expect(formData.get('feedback[screenshot]')).toBeInstanceOf(File)
+    expect(formData.get('feedback[target_element]')).toBe(JSON.stringify({
+      selector: '#export-btn',
+      text: 'Export PDF',
+      name: 'Export PDF',
+    }))
+    expect(shadow.querySelector('.mtb-success-title')?.textContent).toBe('Thanks!')
+  })
+})

package/src/widget/controller.ts

@@ -0,0 +1,249 @@
+import { ShadowContainer } from './shadow'
+import { FeedbackTab } from './tab'
+import { PetEntry } from './pet'
+import { FrustrationPromptCard } from './frustration-prompt'
+import { AnnotationToolbar } from '../annotate/toolbar'
+import type { ToolbarMode } from '../annotate/toolbar'
+import { AnnotationSession } from '../annotate/session'
+import { CommentPopup } from '../popup/comment'
+import { SuccessCard } from '../popup/success'
+import { captureScreenshot } from '../screenshot/capture'
+import { ConsoleErrorCollector } from '../context/console'
+import { FrustrationDetector } from '../context/frustration'
+import { collectPageContext } from '../context/collector'
+import { ApiClient } from '../api/client'
+import { buildPayload } from './payload'
+import { getMessages } from '../i18n'
+import { RecordSession } from '../record/session'
+import type { RecordingResult } from '../record/session'
+import { RecordControlBar } from '../record/control-bar'
+import type { MakeThisBetterConfig, Annotation } from '../types'
+
+type Mode = 'idle' | 'annotating' | 'recording' | 'popup'
+
+export class WidgetController {
+  private config: MakeThisBetterConfig
+  private shadow!: ShadowContainer
+  private tab: FeedbackTab | null = null
+  private pet: PetEntry | null = null
+  private toolbar: AnnotationToolbar | null = null
+  private session: AnnotationSession | null = null
+  private popup: CommentPopup | null = null
+  private success: SuccessCard | null = null
+  private frustrationPrompt: FrustrationPromptCard | null = null
+  private apiClient: ApiClient
+  private consoleCollector: ConsoleErrorCollector
+  private frustrationDetector: FrustrationDetector | null = null
+  private messages: ReturnType<typeof getMessages>
+  private mode: Mode = 'idle'
+  private currentAnnotation: Annotation | null = null
+  private recordSession: RecordSession | null = null
+  private recordBar: RecordControlBar | null = null
+  private currentRecording: RecordingResult | null = null
+
+  constructor(config: MakeThisBetterConfig) {
+    this.config = config
+    this.messages = getMessages(config.locale ?? 'en')
+    this.apiClient = new ApiClient(config.projectKey, config.apiUrl)
+    this.consoleCollector = new ConsoleErrorCollector()
+    this.consoleCollector.start()
+    this.buildUI()
+
+    if (config.frustrationDetection !== false) {
+      this.frustrationDetector = new FrustrationDetector(() => this.handleFrustration())
+      this.frustrationDetector.start()
+    }
+  }
+
+  private buildUI(): void {
+    this.shadow = new ShadowContainer(this.config.theme ?? 'auto')
+
+    if ((this.config.entryMode ?? 'button') === 'pet') {
+      this.pet = new PetEntry(this.shadow, this.messages, () => this.handleTabClick())
+    } else {
+      this.tab = new FeedbackTab(
+        this.shadow,
+        this.messages,
+        this.config.position ?? 'right',
+        () => this.handleTabClick(),
+      )
+    }
+  }
+
+  private handleTabClick(): void {
+    if (this.mode === 'idle') {
+      this.dismissFrustrationPrompt()
+      this.enterAnnotationMode()
+    } else {
+      this.exitAll()
+    }
+  }
+
+  private handleFrustration(): void {
+    if (this.mode !== 'idle' || this.frustrationPrompt) return
+
+    this.frustrationPrompt = new FrustrationPromptCard(this.shadow, this.messages, {
+      onTell: () => {
+        this.dismissFrustrationPrompt()
+        this.enterAnnotationMode()
+      },
+      onDismiss: () => this.dismissFrustrationPrompt(),
+    })
+  }
+
+  private dismissFrustrationPrompt(): void {
+    this.frustrationPrompt?.destroy()
+    this.frustrationPrompt = null
+  }
+
+  private enterAnnotationMode(): void {
+    this.mode = 'annotating'
+    this.tab?.setActive(true)
+    this.pet?.setActive(true)
+
+    this.toolbar = new AnnotationToolbar(
+      this.shadow,
+      this.messages,
+      () => this.exitAll(),
+      (mode: ToolbarMode) => this.handleToolbarModeChange(mode),
+    )
+    this.session = new AnnotationSession(this.shadow, this.messages, (annotation, targetName) => {
+      this.currentAnnotation = annotation
+      this.showPopup(annotation.x, annotation.y, targetName)
+    })
+  }
+
+  private handleToolbarModeChange(mode: ToolbarMode): void {
+    if (mode === 'record') {
+      this.enterRecordingMode()
+    } else {
+      this.exitRecordingMode()
+      if (!this.session) {
+        this.session = new AnnotationSession(this.shadow, this.messages, (annotation, targetName) => {
+          this.currentAnnotation = annotation
+          this.showPopup(annotation.x, annotation.y, targetName)
+        })
+      }
+      this.mode = 'annotating'
+    }
+  }
+
+  private async enterRecordingMode(): Promise<void> {
+    this.mode = 'recording'
+    this.session?.destroy()
+    this.session = null
+
+    this.recordSession = new RecordSession(this.shadow, () => this.stopRecording())
+    this.recordBar = new RecordControlBar(
+      this.shadow,
+      this.messages,
+      () => this.recordSession?.getDuration() ?? 0,
+      () => this.stopRecording(),
+    )
+
+    await this.recordSession.start()
+  }
+
+  private stopRecording(): void {
+    if (!this.recordSession) return
+    this.currentRecording = this.recordSession.stop()
+    this.exitRecordingMode()
+    this.showPopup(
+      window.innerWidth / 2,
+      window.innerHeight / 2,
+      this.messages.record.timer_label,
+    )
+  }
+
+  private exitRecordingMode(): void {
+    this.recordSession?.destroy()
+    this.recordSession = null
+    this.recordBar?.destroy()
+    this.recordBar = null
+  }
+
+  private showPopup(x: number, y: number, targetName: string): void {
+    this.mode = 'popup'
+    this.session?.dismissInteraction()
+
+    this.popup = new CommentPopup(this.shadow, {
+      targetName,
+      x,
+      y,
+      messages: this.messages,
+      onSubmit: (description) => this.handleSubmit(description),
+      onClose: () => this.exitAll(),
+    })
+  }
+
+  private async handleSubmit(description: string): Promise<void> {
+    if (!this.popup) return
+    this.popup.setLoading(true)
+    const annotation = this.currentAnnotation
+    const recording = this.currentRecording ?? undefined
+
+    const [screenshot, pageContext] = await Promise.all([
+      captureScreenshot(annotation ? [annotation] : []),
+      Promise.resolve(collectPageContext()),
+    ])
+
+    const payload = buildPayload(
+      description,
+      pageContext,
+      this.consoleCollector.getErrors(),
+      annotation,
+      this.config.user,
+      recording,
+    )
+
+    try {
+      await this.apiClient.submitFeedback(payload, screenshot)
+      this.popup?.destroy()
+      this.popup = null
+      this.session?.destroy()
+      this.session = null
+      this.currentRecording = null
+      this.showSuccess()
+    } catch {
+      this.popup?.setLoading(false)
+      this.popup?.setError(this.messages.error.submit)
+    }
+  }
+
+  private showSuccess(): void {
+    this.mode = 'idle'
+    this.tab?.setActive(false)
+    this.pet?.setActive(false)
+    this.success = new SuccessCard(this.shadow, this.messages, () => {
+      this.success?.destroy()
+      this.success = null
+    })
+  }
+
+  private exitAll(): void {
+    this.mode = 'idle'
+    this.tab?.setActive(false)
+    this.pet?.setActive(false)
+    this.toolbar?.destroy()
+    this.toolbar = null
+    this.session?.destroy()
+    this.session = null
+    this.popup?.destroy()
+    this.popup = null
+    this.currentAnnotation = null
+    this.currentRecording = null
+    this.exitRecordingMode()
+  }
+
+  destroy(): void {
+    this.exitAll()
+    this.consoleCollector.stop()
+    this.frustrationDetector?.stop()
+    this.dismissFrustrationPrompt()
+    this.success?.destroy()
+    this.tab?.destroy()
+    this.pet?.destroy()
+    this.exitRecordingMode()
+    this.shadow.destroy()
+  }
+}

package/src/widget/frustration-prompt.test.ts

@@ -0,0 +1,86 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { FrustrationPromptCard } from './frustration-prompt'
+import { ShadowContainer } from './shadow'
+import { getMessages } from '../i18n'
+
+function setupPrompt() {
+  const shadow = new ShadowContainer()
+  const onTell = vi.fn()
+  const onDismiss = vi.fn()
+  const messages = getMessages('en')
+  const card = new FrustrationPromptCard(shadow, messages, { onTell, onDismiss })
+
+  return { shadow, card, onTell, onDismiss, messages }
+}
+
+describe('FrustrationPromptCard', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('renders prompt text and action buttons', () => {
+    const { shadow, card, messages } = setupPrompt()
+
+    expect(shadow.root.querySelector('.mtb-frustration-text')?.textContent).toBe(messages.frustration.prompt)
+    expect(shadow.root.querySelector('.mtb-frustration-tell')?.textContent).toBe(messages.frustration.action)
+    expect(shadow.root.querySelector('.mtb-frustration-dismiss')?.textContent).toBe(messages.frustration.dismiss)
+
+    card.destroy()
+    shadow.destroy()
+  })
+
+  it('renders warning icon', () => {
+    const { shadow, card } = setupPrompt()
+
+    const icon = shadow.root.querySelector('.mtb-frustration-icon')
+    expect(icon).toBeTruthy()
+
+    card.destroy()
+    shadow.destroy()
+  })
+
+  it('calls onTell when tell button is clicked', () => {
+    const { shadow, card, onTell } = setupPrompt()
+
+    shadow.root.querySelector<HTMLButtonElement>('.mtb-frustration-tell')!.click()
+    expect(onTell).toHaveBeenCalledOnce()
+
+    card.destroy()
+    shadow.destroy()
+  })
+
+  it('calls onDismiss when dismiss button is clicked', () => {
+    const { shadow, card, onDismiss } = setupPrompt()
+
+    shadow.root.querySelector<HTMLButtonElement>('.mtb-frustration-dismiss')!.click()
+    expect(onDismiss).toHaveBeenCalledOnce()
+
+    card.destroy()
+    shadow.destroy()
+  })
+
+  it('auto-dismisses after 8 seconds', () => {
+    const { shadow, card, onDismiss } = setupPrompt()
+
+    expect(onDismiss).not.toHaveBeenCalled()
+    vi.advanceTimersByTime(8000)
+    expect(onDismiss).toHaveBeenCalled()
+
+    card.destroy()
+    shadow.destroy()
+  })
+
+  it('destroy removes element from shadow root', () => {
+    const { shadow, card } = setupPrompt()
+
+    expect(shadow.root.querySelector('.mtb-frustration-prompt')).toBeTruthy()
+    card.destroy()
+    expect(shadow.root.querySelector('.mtb-frustration-prompt')).toBeNull()
+
+    shadow.destroy()
+  })
+})

package/src/widget/frustration-prompt.ts

@@ -0,0 +1,34 @@
+import type { ShadowContainer } from './shadow'
+import type { I18nMessages } from '../i18n'
+
+const FRUSTRATION_DISMISS_MS = 8000
+
+export class FrustrationPromptCard {
+  private el: HTMLDivElement
+
+  constructor(
+    shadow: ShadowContainer,
+    messages: I18nMessages,
+    handlers: { onTell: () => void; onDismiss: () => void },
+  ) {
+    this.el = shadow.el<HTMLDivElement>('div', 'mtb-frustration-prompt')
+    this.el.innerHTML = `
+      <div class="mtb-frustration-icon">&#9888;&#65039;</div>
+      <span class="mtb-frustration-text">${messages.frustration.prompt}</span>
+      <div class="mtb-frustration-actions">
+        <button class="mtb-frustration-tell">${messages.frustration.action}</button>
+        <button class="mtb-frustration-dismiss">${messages.frustration.dismiss}</button>
+      </div>
+    `
+
+    this.el.querySelector('.mtb-frustration-tell')!.addEventListener('click', handlers.onTell)
+    this.el.querySelector('.mtb-frustration-dismiss')!.addEventListener('click', handlers.onDismiss)
+
+    shadow.append(this.el)
+    setTimeout(handlers.onDismiss, FRUSTRATION_DISMISS_MS)
+  }
+
+  destroy(): void {
+    this.el.remove()
+  }
+}

package/src/widget/payload.test.ts

@@ -0,0 +1,167 @@
+import { describe, expect, it } from 'vitest'
+import { buildPayload } from './payload'
+import type { PageContext } from '../context/collector'
+import type { Annotation, MakeThisBetterConfig } from '../types'
+import type { RecordingResult } from '../record/session'
+
+const pageContext: PageContext = {
+  page_url: 'https://example.com/dashboard',
+  user_agent: 'Mozilla/5.0',
+  browser: 'Chrome 120',
+  os: 'macOS',
+  screen_width: 1920,
+  screen_height: 1080,
+}
+
+describe('buildPayload', () => {
+  it('returns base payload without annotation, user, or recording', () => {
+    const result = buildPayload('Button is broken', pageContext, ['TypeError: x'], null, undefined)
+
+    expect(result.description).toBe('Button is broken')
+    expect(result.page_url).toBe('https://example.com/dashboard')
+    expect(result.user_agent).toBe('Mozilla/5.0')
+    expect(result.browser).toBe('Chrome 120')
+    expect(result.os).toBe('macOS')
+    expect(result.screen_width).toBe(1920)
+    expect(result.screen_height).toBe(1080)
+    expect(result.console_errors).toEqual(['TypeError: x'])
+    expect(result.annotations).toEqual([])
+    expect(result.target_element).toBeUndefined()
+    expect(result.user_id).toBeUndefined()
+    expect(result.user_email).toBeUndefined()
+    expect(result.user_name).toBeUndefined()
+    expect(result.recording_events).toBeUndefined()
+    expect(result.recording_duration).toBeUndefined()
+  })
+
+  it('includes annotation and target_element when annotation has targetSelector', () => {
+    const annotation: Annotation = {
+      type: 'pin',
+      x: 200,
+      y: 300,
+      targetSelector: '#export-btn',
+      targetText: 'Export PDF',
+      targetName: 'Export Button',
+    }
+
+    const result = buildPayload('Export fails', pageContext, [], annotation, undefined)
+
+    expect(result.annotations).toEqual([annotation])
+    expect(result.target_element).toEqual({
+      selector: '#export-btn',
+      text: 'Export PDF',
+      name: 'Export Button',
+    })
+  })
+
+  it('omits target_element when annotation has no targetSelector', () => {
+    const annotation: Annotation = {
+      type: 'draw',
+      x: 100,
+      y: 150,
+      drawPath: 'M0 0 L10 10',
+    }
+
+    const result = buildPayload('UI glitch', pageContext, [], annotation, undefined)
+
+    expect(result.annotations).toEqual([annotation])
+    expect(result.target_element).toBeUndefined()
+  })
+
+  it('defaults targetText and targetName to empty string when missing', () => {
+    const annotation: Annotation = {
+      type: 'pin',
+      x: 50,
+      y: 60,
+      targetSelector: '.header',
+    }
+
+    const result = buildPayload('Header issue', pageContext, [], annotation, undefined)
+
+    expect(result.target_element).toEqual({
+      selector: '.header',
+      text: '',
+      name: '',
+    })
+  })
+
+  it('includes user fields when user is provided', () => {
+    const user: MakeThisBetterConfig['user'] = {
+      id: 'usr_123',
+      email: 'alice@example.com',
+      name: 'Alice',
+    }
+
+    const result = buildPayload('Feedback', pageContext, [], null, user)
+
+    expect(result.user_id).toBe('usr_123')
+    expect(result.user_email).toBe('alice@example.com')
+    expect(result.user_name).toBe('Alice')
+  })
+
+  it('includes partial user fields', () => {
+    const user: MakeThisBetterConfig['user'] = {
+      email: 'bob@example.com',
+    }
+
+    const result = buildPayload('Feedback', pageContext, [], null, user)
+
+    expect(result.user_id).toBeUndefined()
+    expect(result.user_email).toBe('bob@example.com')
+    expect(result.user_name).toBeUndefined()
+  })
+
+  it('includes recording data when recording is provided', () => {
+    const recording: RecordingResult = {
+      events: [{ type: 3, data: { source: 2 } }],
+      duration: 12500,
+    }
+
+    const result = buildPayload('Screen issue', pageContext, [], null, undefined, recording)
+
+    expect(result.recording_events).toEqual([{ type: 3, data: { source: 2 } }])
+    expect(result.recording_duration).toBe(12500)
+  })
+
+  it('passes through empty console_errors array', () => {
+    const result = buildPayload('All good', pageContext, [], null, undefined)
+
+    expect(result.console_errors).toEqual([])
+  })
+
+  it('combines all optional fields together', () => {
+    const annotation: Annotation = {
+      type: 'pin',
+      x: 10,
+      y: 20,
+      targetSelector: '#save',
+      targetText: 'Save',
+      targetName: 'Save Button',
+    }
+    const user: MakeThisBetterConfig['user'] = {
+      id: 'usr_456',
+      email: 'carol@example.com',
+      name: 'Carol',
+    }
+    const recording: RecordingResult = {
+      events: [{ type: 2 }],
+      duration: 5000,
+    }
+
+    const result = buildPayload(
+      'Save broken',
+      pageContext,
+      ['Error: 500'],
+      annotation,
+      user,
+      recording,
+    )
+
+    expect(result.description).toBe('Save broken')
+    expect(result.annotations).toHaveLength(1)
+    expect(result.target_element?.selector).toBe('#save')
+    expect(result.user_id).toBe('usr_456')
+    expect(result.recording_duration).toBe(5000)
+    expect(result.console_errors).toEqual(['Error: 500'])
+  })
+})

package/src/widget/payload.ts

@@ -0,0 +1,31 @@
+import type { PageContext } from '../context/collector'
+import type { Annotation, FeedbackPayload, MakeThisBetterConfig } from '../types'
+import type { RecordingResult } from '../record/session'
+
+export function buildPayload(
+  description: string,
+  pageContext: PageContext,
+  consoleErrors: string[],
+  annotation: Annotation | null,
+  user: MakeThisBetterConfig['user'],
+  recording?: RecordingResult,
+): FeedbackPayload {
+  return {
+    description,
+    ...pageContext,
+    console_errors: consoleErrors,
+    annotations: annotation ? [annotation] : [],
+    target_element: annotation?.targetSelector
+      ? {
+          selector: annotation.targetSelector,
+          text: annotation.targetText ?? '',
+          name: annotation.targetName ?? '',
+        }
+      : undefined,
+    user_id: user?.id,
+    user_email: user?.email,
+    user_name: user?.name,
+    recording_events: recording?.events,
+    recording_duration: recording?.duration,
+  }
+}