@holdyapp/sdk 1.1.0 → 1.6.0

package/src/friction.test.ts

@@ -0,0 +1,223 @@
+import { describe, it, expect } from 'vitest'
+import {
+  RageClickDetector,
+  NavLoopDetector,
+  isDeadClickTarget,
+  describeElement,
+  stripRequestUrl,
+  errorMessage,
+  installFrictionCapture,
+  classifyRequest,
+  documentStatus,
+  isAbortError,
+  isIgnoredUrl,
+  isFirstPartyRequest,
+  registrableDomain,
+  type ElementLike,
+} from './friction'
+
+describe('classifyRequest', () => {
+  it('status ≥ 400 ou sem resposta é erro, mesmo quando é rápido', () => {
+    expect(classifyRequest({ status: 404, durationMs: 120, slowMs: 3000 })).toBe('http_error')
+    expect(classifyRequest({ status: 500, durationMs: 5000, slowMs: 3000 })).toBe('http_error')
+    expect(classifyRequest({ status: null, durationMs: 40, slowMs: 3000 })).toBe('http_error')
+  })
+
+  it('lento com resposta ok segue lento; abortado e opaco nunca são erro', () => {
+    expect(classifyRequest({ status: 200, durationMs: 4000, slowMs: 3000 })).toBe('slow_request')
+    expect(classifyRequest({ status: 204, durationMs: 90, slowMs: 3000 })).toBeNull()
+    expect(classifyRequest({ status: null, durationMs: 10, slowMs: 3000, aborted: true })).toBeNull()
+    expect(classifyRequest({ status: 0, durationMs: 10, slowMs: 3000, opaque: true })).toBeNull()
+    expect(classifyRequest({ status: 0, durationMs: 3500, slowMs: 3000, opaque: true })).toBe('slow_request')
+  })
+})
+
+describe('registrableDomain', () => {
+  it('reduz o host aos dois últimos rótulos', () => {
+    expect(registrableDomain('app.acme.com')).toBe('acme.com')
+    expect(registrableDomain('acme.com')).toBe('acme.com')
+    expect(registrableDomain('a.b.c.acme.com')).toBe('acme.com')
+    expect(registrableDomain('localhost')).toBe('localhost')
+  })
+})
+
+describe('isFirstPartyRequest', () => {
+  const page = 'https://app.acme.com/relatorios'
+
+  it('mesmo host e mesmo domínio contam como produto', () => {
+    expect(isFirstPartyRequest('https://app.acme.com/api/v1/x', page)).toBe(true)
+    expect(isFirstPartyRequest('https://api.acme.com/v1/x', page)).toBe(true)
+    expect(isFirstPartyRequest('/api/v1/x', page)).toBe(true)
+  })
+
+  it('terceiro não é fricção do produto — foi o que inflou a fricção em 2026-09-17', () => {
+    expect(isFirstPartyRequest('https://www.google-analytics.com/g/collect', page)).toBe(false)
+    expect(isFirstPartyRequest('https://www.google.com/g/collect', page)).toBe(false)
+    expect(isFirstPartyRequest('https://cdn.segment.io/analytics.js', page)).toBe(false)
+  })
+
+  it('apiOrigins recupera a API que mora em outro domínio', () => {
+    expect(isFirstPartyRequest('https://acme-api.io/v1/x', page)).toBe(false)
+    expect(isFirstPartyRequest('https://acme-api.io/v1/x', page, ['https://acme-api.io'])).toBe(true)
+  })
+
+  it('localhost e porta diferente seguem sendo o próprio produto', () => {
+    expect(isFirstPartyRequest('http://localhost:4000/api', 'http://localhost:3000/x')).toBe(true)
+  })
+
+  it('esquema que não é http não é julgado', () => {
+    expect(isFirstPartyRequest('data:text/plain,oi', page)).toBe(true)
+    expect(isFirstPartyRequest('blob:https://outro.com/abc', page)).toBe(true)
+  })
+
+  it('url impossível de parsear volta como própria, nunca descartada em silêncio', () => {
+    expect(isFirstPartyRequest(':::', page)).toBe(true)
+  })
+})
+
+describe('isIgnoredUrl', () => {
+  it('ignora pelo prefixo e nunca por prefixo vazio', () => {
+    expect(isIgnoredUrl('https://holdy.chat/api/v1/events/bulk', ['https://holdy.chat/api/v1'])).toBe(true)
+    expect(isIgnoredUrl('https://app.cliente.com/files/a.pdf', ['https://holdy.chat/api/v1'])).toBe(false)
+    expect(isIgnoredUrl('https://app.cliente.com/x', [''])).toBe(false)
+  })
+})
+
+describe('documentStatus', () => {
+  it('lê o status da navegação e cala quando o browser não sabe', () => {
+    expect(documentStatus({ getEntriesByType: () => [{ responseStatus: 404 }] })).toBe(404)
+    expect(documentStatus({ getEntriesByType: () => [{ responseStatus: 0 }] })).toBeNull()
+    expect(documentStatus({ getEntriesByType: () => [] })).toBeNull()
+    expect(
+      documentStatus({
+        getEntriesByType: () => {
+          throw new Error('sem suporte')
+        },
+      }),
+    ).toBeNull()
+    expect(documentStatus(undefined)).toBeNull()
+  })
+})
+
+describe('isAbortError', () => {
+  it('reconhece o cancelamento pelo nome', () => {
+    expect(isAbortError({ name: 'AbortError' })).toBe(true)
+    expect(isAbortError(new TypeError('Failed to fetch'))).toBe(false)
+    expect(isAbortError(null)).toBe(false)
+  })
+})
+
+function el(
+  tag: string,
+  attrs: Record<string, string | null> = {},
+  extra: Partial<ElementLike> = {},
+): ElementLike {
+  return {
+    tagName: tag.toUpperCase(),
+    getAttribute: (name) => attrs[name] ?? null,
+    ...extra,
+  }
+}
+
+describe('RageClickDetector', () => {
+  it('dispara na 3ª batida dentro de 1s e 30px, depois zera', () => {
+    const d = new RageClickDetector()
+    expect(d.push(100, 100, 0)).toBe(false)
+    expect(d.push(105, 102, 300)).toBe(false)
+    expect(d.push(110, 98, 700)).toBe(true)
+    expect(d.push(110, 98, 800)).toBe(false)
+  })
+
+  it('cliques espalhados ou lentos não são raiva', () => {
+    const d = new RageClickDetector()
+    d.push(0, 0, 0)
+    d.push(200, 200, 100)
+    expect(d.push(0, 0, 200)).toBe(false)
+    d.push(0, 0, 5000)
+    expect(d.push(0, 0, 5100)).toBe(false)
+  })
+})
+
+describe('NavLoopDetector', () => {
+  it('A→B→A→B em menos de 60s é loop; devolve o par', () => {
+    const d = new NavLoopDetector()
+    expect(d.push('/a', 0)).toBeNull()
+    expect(d.push('/b', 1000)).toBeNull()
+    expect(d.push('/a', 2000)).toBeNull()
+    expect(d.push('/b', 3000)).toEqual({ from: '/a', to: '/b' })
+    expect(d.push('/a', 4000)).toBeNull()
+  })
+
+  it('A→A→A→A não é loop, e visitas velhas caem da janela', () => {
+    const d = new NavLoopDetector()
+    ;['/a', '/a', '/a'].forEach((p, i) => d.push(p, i * 1000))
+    expect(d.push('/a', 3000)).toBeNull()
+    const slow = new NavLoopDetector(10_000)
+    slow.push('/a', 0)
+    slow.push('/b', 1000)
+    slow.push('/a', 2000)
+    expect(slow.push('/b', 20_000)).toBeNull()
+  })
+})
+
+describe('isDeadClickTarget', () => {
+  it('botão desabilitado, aria-disabled e âncora sem href são cliques mortos', () => {
+    expect(isDeadClickTarget(el('button', {}, { disabled: true }))).toBe(true)
+    expect(isDeadClickTarget(el('button', { disabled: '' }))).toBe(true)
+    expect(isDeadClickTarget(el('div', { role: 'button', 'aria-disabled': 'true' }))).toBe(true)
+    expect(isDeadClickTarget(el('a', { href: null }))).toBe(true)
+    expect(isDeadClickTarget(el('a', { href: '#' }))).toBe(true)
+  })
+
+  it('controle habilitado e texto solto não são', () => {
+    expect(isDeadClickTarget(el('button', {}, { disabled: false }))).toBe(false)
+    expect(isDeadClickTarget(el('a', { href: '/x' }))).toBe(false)
+    expect(isDeadClickTarget(el('p'))).toBe(false)
+    expect(isDeadClickTarget(null)).toBe(false)
+  })
+
+  it('resolve pelo ancestral interativo (clique no ícone dentro do botão)', () => {
+    const button = el('button', {}, { disabled: true })
+    const icon = el('svg', {}, { closest: () => button })
+    expect(isDeadClickTarget(icon)).toBe(true)
+  })
+})
+
+describe('describeElement', () => {
+  it('tag + id + texto colapsado e cortado em 60', () => {
+    const long = 'Convidar   time '.repeat(10)
+    const out = describeElement(el('button', { name: 'invite' }, { id: 'cta', textContent: long }))
+    expect(out.element).toBe('button')
+    expect(out.element_id).toBe('cta')
+    expect(out.element_name).toBe('invite')
+    expect(out.element_text.length).toBeLessThanOrEqual(60)
+    expect(out.element_text.startsWith('Convidar time Convidar')).toBe(true)
+  })
+
+  it('aria-label vence o texto', () => {
+    const out = describeElement(el('button', { 'aria-label': 'Fechar' }, { textContent: '×' }))
+    expect(out.element_text).toBe('Fechar')
+  })
+})
+
+describe('stripRequestUrl / errorMessage', () => {
+  it('tira query e hash, resolve relativa contra a base', () => {
+    expect(stripRequestUrl('https://api.x.com/v1/users?limit=5#top')).toBe('https://api.x.com/v1/users')
+    expect(stripRequestUrl('/api/items?id=1', 'https://app.x.com/page')).toBe('https://app.x.com/api/items')
+    expect(stripRequestUrl('not a url ?x=1')).toBe('not a url ')
+  })
+
+  it('mensagem de erro de qualquer forma de reason', () => {
+    expect(errorMessage(new Error('boom'))).toBe('boom')
+    expect(errorMessage('str')).toBe('str')
+    expect(errorMessage({ code: 1 })).toBe('{"code":1}')
+  })
+})
+
+describe('installFrictionCapture fora do browser', () => {
+  it('é no-op e nunca lança', () => {
+    const capture = installFrictionCapture({ onFriction: () => undefined })
+    expect(() => capture.onNavigate('/x')).not.toThrow()
+    expect(() => capture.teardown()).not.toThrow()
+  })
+})

package/src/friction.ts

@@ -0,0 +1,419 @@
+export type FrictionKind =
+  | 'dead_click'
+  | 'rage_click'
+  | 'form_abandon'
+  | 'js_error'
+  | 'slow_request'
+  | 'nav_loop'
+  | 'http_error'
+
+export interface FrictionSignal {
+  kind: FrictionKind
+  properties: Record<string, unknown>
+}
+
+export interface FrictionCaptureOptions {
+  onFriction: (signal: FrictionSignal) => void
+  slowRequestMs?: number
+  rageClicks?: number
+  rageWindowMs?: number
+  rageRadiusPx?: number
+  navLoopWindowMs?: number
+  ignoreUrls?: string[]
+  /**
+   * Origens que contam como o próprio produto além do domínio da página —
+   * pro caso em que a API mora em outro domínio (`acme-api.io` servindo
+   * `acme.com`). O subdomínio já entra sozinho.
+   */
+  apiOrigins?: string[]
+}
+
+export interface FrictionCapture {
+  onNavigate: (path: string) => void
+  teardown: () => void
+}
+
+const INSTALLED_FLAG = '__holdy_friction__'
+const INTERACTIVE_SELECTOR =
+  'button, a, input, select, textarea, summary, [role="button"], [role="link"], [role="menuitem"], [role="tab"]'
+const INTERACTIVE_TAGS = new Set(['button', 'a', 'input', 'select', 'textarea', 'summary'])
+const FORM_CONTROL_TAGS = new Set(['input', 'select', 'textarea'])
+
+export class RageClickDetector {
+  private clicks: Array<{ x: number; y: number; t: number }> = []
+
+  constructor(
+    private readonly threshold = 3,
+    private readonly windowMs = 1000,
+    private readonly radiusPx = 30,
+  ) {}
+
+  push(x: number, y: number, t: number): boolean {
+    this.clicks = this.clicks.filter(
+      (c) => t - c.t <= this.windowMs && Math.hypot(c.x - x, c.y - y) <= this.radiusPx,
+    )
+    this.clicks.push({ x, y, t })
+    if (this.clicks.length >= this.threshold) {
+      this.clicks = []
+      return true
+    }
+    return false
+  }
+}
+
+export class NavLoopDetector {
+  private visits: Array<{ path: string; t: number }> = []
+
+  constructor(private readonly windowMs = 60_000) {}
+
+  push(path: string, t: number): { from: string; to: string } | null {
+    this.visits = [...this.visits, { path, t }].filter((v) => t - v.t <= this.windowMs).slice(-4)
+    if (this.visits.length < 4) return null
+    const [a, b, c, d] = this.visits.map((v) => v.path)
+    if (a === c && b === d && a !== b) {
+      this.visits = []
+      return { from: a, to: b }
+    }
+    return null
+  }
+}
+
+export interface ElementLike {
+  tagName: string
+  id?: string
+  disabled?: boolean
+  textContent?: string | null
+  getAttribute(name: string): string | null
+  closest?(selector: string): ElementLike | null
+}
+
+export function resolveInteractive(el: ElementLike | null): ElementLike | null {
+  if (!el) return null
+  const viaClosest = el.closest?.(INTERACTIVE_SELECTOR) ?? null
+  if (viaClosest) return viaClosest
+  const tag = el.tagName.toLowerCase()
+  if (INTERACTIVE_TAGS.has(tag)) return el
+  const role = el.getAttribute('role')
+  if (role === 'button' || role === 'link' || role === 'menuitem' || role === 'tab') return el
+  return null
+}
+
+export function isDeadClickTarget(el: ElementLike | null): boolean {
+  const target = resolveInteractive(el)
+  if (!target) return false
+  if (target.disabled === true) return true
+  if (target.getAttribute('disabled') !== null) return true
+  if (target.getAttribute('aria-disabled') === 'true') return true
+  const tag = target.tagName.toLowerCase()
+  if (tag === 'a') {
+    const href = target.getAttribute('href')
+    if (!href || href === '#' || href.startsWith('javascript:')) return true
+  }
+  return false
+}
+
+export function describeElement(el: ElementLike | null): Record<string, string> {
+  const target = resolveInteractive(el) ?? el
+  if (!target) return {}
+  const out: Record<string, string> = { element: target.tagName.toLowerCase() }
+  if (target.id) out.element_id = target.id
+  const role = target.getAttribute('role')
+  if (role) out.element_role = role
+  const label = target.getAttribute('aria-label') ?? target.textContent ?? ''
+  const text = label.replace(/\s+/g, ' ').trim().slice(0, 60)
+  if (text) out.element_text = text
+  const name = target.getAttribute('name') ?? target.getAttribute('data-testid')
+  if (name) out.element_name = name
+  return out
+}
+
+export function stripRequestUrl(input: string, base?: string): string {
+  try {
+    const url = new URL(input, base)
+    return `${url.origin}${url.pathname}`
+  } catch {
+    return input.split('?')[0].split('#')[0]
+  }
+}
+
+export function errorMessage(reason: unknown): string {
+  if (reason instanceof Error) return reason.message
+  if (typeof reason === 'string') return reason
+  try {
+    return JSON.stringify(reason)
+  } catch {
+    return String(reason)
+  }
+}
+
+export function isAbortError(err: unknown): boolean {
+  return typeof err === 'object' && err !== null && (err as { name?: unknown }).name === 'AbortError'
+}
+
+export function isIgnoredUrl(url: string, ignore: readonly string[]): boolean {
+  return ignore.some((prefix) => prefix.length > 0 && url.startsWith(prefix))
+}
+
+/**
+ * Domínio registrável aproximado — os dois últimos rótulos do host.
+ *
+ * `app.acme.com` e `api.acme.com` → `acme.com`: produto que fala com a própria
+ * API em outro subdomínio continua sendo primeira parte. Sem lista de sufixos
+ * públicos, `foo.co.uk` e `bar.co.uk` colidem — e a colisão erra pro lado
+ * seguro, incluindo como próprio o que hoje já é incluído.
+ */
+export function registrableDomain(host: string): string {
+  const labels = host.toLowerCase().split('.').filter(Boolean)
+  if (labels.length <= 2) return labels.join('.')
+  return labels.slice(-2).join('.')
+}
+
+/**
+ * A requisição é do produto de quem instalou, ou de um terceiro?
+ *
+ * Fricção é fricção DO PRODUTO. Um `google-analytics.com/g/collect` morto por
+ * ad blocker não é o produto falhando — é o navegador do visitante recusando
+ * um script que nem é seu. Em 2026-09-17 esses dois domínios respondiam por 36
+ * dos eventos de fricção da janela: num cliente com GA instalado e usuários com
+ * bloqueador, isso infla a fricção e pode abrir oportunidade em cima de nada.
+ *
+ * Localhost e IP entram pela comparação de host exato — em desenvolvimento não
+ * há domínio registrável que valha.
+ */
+export function isFirstPartyRequest(url: string, pageUrl: string, extraOrigins: readonly string[] = []): boolean {
+  let target: URL
+  let page: URL
+  try {
+    target = new URL(url, pageUrl)
+    page = new URL(pageUrl)
+  } catch {
+    return true
+  }
+  if (target.protocol !== 'http:' && target.protocol !== 'https:') return true
+  if (target.host === page.host) return true
+  if (extraOrigins.some((o) => o.length > 0 && target.origin === o)) return true
+  const targetDomain = registrableDomain(target.hostname)
+  return targetDomain.length > 0 && targetDomain === registrableDomain(page.hostname)
+}
+
+export interface RequestOutcome {
+  status: number | null
+  durationMs: number
+  slowMs: number
+  aborted?: boolean
+  opaque?: boolean
+}
+
+export function classifyRequest(outcome: RequestOutcome): 'http_error' | 'slow_request' | null {
+  if (outcome.aborted) return null
+  if (!outcome.opaque && (outcome.status === null || outcome.status >= 400)) return 'http_error'
+  return outcome.durationMs >= outcome.slowMs ? 'slow_request' : null
+}
+
+export function documentStatus(
+  perf: { getEntriesByType?: (type: string) => unknown[] } | undefined,
+): number | null {
+  try {
+    const entry = perf?.getEntriesByType?.('navigation')?.[0] as { responseStatus?: unknown } | undefined
+    const status = entry?.responseStatus
+    return typeof status === 'number' && status > 0 ? status : null
+  } catch {
+    return null
+  }
+}
+
+interface FormTouch {
+  form: string
+  fields: Set<string>
+}
+
+function formKey(form: HTMLFormElement): string {
+  return (
+    form.id ||
+    form.getAttribute('name') ||
+    form.getAttribute('data-testid') ||
+    stripRequestUrl(form.getAttribute('action') ?? '', location.href).replace(location.origin, '') ||
+    'form'
+  )
+}
+
+function currentPath(): string {
+  return typeof location === 'undefined' ? '/' : location.pathname || '/'
+}
+
+export function installFrictionCapture(opts: FrictionCaptureOptions): FrictionCapture {
+  const noop: FrictionCapture = { onNavigate: () => undefined, teardown: () => undefined }
+  if (typeof window === 'undefined' || typeof document === 'undefined') return noop
+
+  const w = window as unknown as Record<string, boolean | undefined>
+  if (w[INSTALLED_FLAG]) return noop
+  w[INSTALLED_FLAG] = true
+
+  const emit = (kind: FrictionKind, properties: Record<string, unknown>): void => {
+    try {
+      opts.onFriction({ kind, properties: { path: currentPath(), ...properties } })
+    } catch {
+      return
+    }
+  }
+
+  const cleanups: Array<() => void> = []
+  const rage = new RageClickDetector(opts.rageClicks, opts.rageWindowMs, opts.rageRadiusPx)
+  const navLoop = new NavLoopDetector(opts.navLoopWindowMs)
+  const slowMs = opts.slowRequestMs ?? 3000
+  const touched = new Map<HTMLFormElement, FormTouch>()
+
+  const onClick = (ev: MouseEvent): void => {
+    const el = ev.target instanceof Element ? (ev.target as unknown as ElementLike) : null
+    if (isDeadClickTarget(el)) emit('dead_click', describeElement(el))
+    if (rage.push(ev.clientX, ev.clientY, ev.timeStamp || Date.now())) {
+      emit('rage_click', describeElement(el))
+    }
+  }
+  document.addEventListener('click', onClick, true)
+  cleanups.push(() => document.removeEventListener('click', onClick, true))
+
+  const onError = (ev: ErrorEvent): void => {
+    emit('js_error', {
+      message: String(ev.message ?? '').slice(0, 200),
+      ...(ev.filename ? { source: stripRequestUrl(ev.filename, location.href) } : {}),
+      ...(ev.lineno ? { line: ev.lineno } : {}),
+    })
+  }
+  window.addEventListener('error', onError)
+  cleanups.push(() => window.removeEventListener('error', onError))
+
+  const onRejection = (ev: PromiseRejectionEvent): void => {
+    emit('js_error', { message: errorMessage(ev.reason).slice(0, 200), unhandled_rejection: true })
+  }
+  window.addEventListener('unhandledrejection', onRejection)
+  cleanups.push(() => window.removeEventListener('unhandledrejection', onRejection))
+
+  const ignore = (opts.ignoreUrls ?? []).map((url) => stripRequestUrl(url, location.href))
+  const apiOrigins = (opts.apiOrigins ?? []).map((o) => {
+    try {
+      return new URL(o, location.href).origin
+    } catch {
+      return ''
+    }
+  })
+  const reportRequest = (
+    url: string,
+    method: string,
+    started: number,
+    status: number | null,
+    flags: { aborted?: boolean; opaque?: boolean } = {},
+  ): void => {
+    const target = stripRequestUrl(url, location.href)
+    if (isIgnoredUrl(target, ignore)) return
+    if (!isFirstPartyRequest(target, location.href, apiOrigins)) return
+    const durationMs = performance.now() - started
+    const kind = classifyRequest({ status, durationMs, slowMs, ...flags })
+    if (!kind) return
+    emit(kind, {
+      url: target,
+      method,
+      duration_ms: Math.round(durationMs),
+      ...(flags.opaque ? {} : status !== null ? { status } : { failed: true }),
+    })
+  }
+
+  const originalFetch = window.fetch
+  if (typeof originalFetch === 'function') {
+    const patched: typeof window.fetch = async (input, init) => {
+      const started = performance.now()
+      const url =
+        typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
+      const method = (init?.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase()
+      try {
+        const res = await originalFetch(input, init)
+        reportRequest(url, method, started, res.status, {
+          opaque: res.type === 'opaque' || res.type === 'opaqueredirect',
+        })
+        return res
+      } catch (err) {
+        reportRequest(url, method, started, null, { aborted: isAbortError(err) })
+        throw err
+      }
+    }
+    window.fetch = patched
+    cleanups.push(() => {
+      window.fetch = originalFetch
+    })
+  }
+
+  const xhrProto = typeof XMLHttpRequest === 'function' ? XMLHttpRequest.prototype : null
+  if (xhrProto) {
+    const originalOpen = xhrProto.open
+    const originalSend = xhrProto.send
+    const requests = new WeakMap<XMLHttpRequest, { method: string; url: string }>()
+    xhrProto.open = function (this: XMLHttpRequest, method: string, url: string | URL, ...rest: unknown[]) {
+      requests.set(this, { method: String(method).toUpperCase(), url: String(url) })
+      return (originalOpen as (...args: unknown[]) => void).apply(this, [method, url, ...rest])
+    } as typeof xhrProto.open
+    xhrProto.send = function (this: XMLHttpRequest, body?: Document | XMLHttpRequestBodyInit | null) {
+      const request = requests.get(this)
+      if (request) {
+        const started = performance.now()
+        let aborted = false
+        this.addEventListener('abort', () => {
+          aborted = true
+        })
+        this.addEventListener('loadend', () => {
+          reportRequest(request.url, request.method, started, this.status === 0 ? null : this.status, { aborted })
+        })
+      }
+      return originalSend.call(this, body)
+    }
+    cleanups.push(() => {
+      xhrProto.open = originalOpen
+      xhrProto.send = originalSend
+    })
+  }
+
+  const loadStatus = documentStatus(typeof performance === 'undefined' ? undefined : performance)
+  if (loadStatus !== null && loadStatus >= 400) {
+    emit('http_error', { document: true, status: loadStatus, url: stripRequestUrl(location.href) })
+  }
+
+  const onFocusIn = (ev: FocusEvent): void => {
+    const el = ev.target as HTMLElement | null
+    if (!el || !FORM_CONTROL_TAGS.has(el.tagName.toLowerCase())) return
+    const form = (el as HTMLInputElement).form
+    if (!form) return
+    const entry = touched.get(form) ?? { form: formKey(form), fields: new Set<string>() }
+    const field = (el as HTMLInputElement).name || el.id || el.tagName.toLowerCase()
+    entry.fields.add(field)
+    touched.set(form, entry)
+  }
+  document.addEventListener('focusin', onFocusIn, true)
+  cleanups.push(() => document.removeEventListener('focusin', onFocusIn, true))
+
+  const onSubmit = (ev: Event): void => {
+    if (ev.target instanceof HTMLFormElement) touched.delete(ev.target)
+  }
+  document.addEventListener('submit', onSubmit, true)
+  cleanups.push(() => document.removeEventListener('submit', onSubmit, true))
+
+  const flushAbandons = (): void => {
+    for (const entry of touched.values()) {
+      emit('form_abandon', { form: entry.form, fields_touched: entry.fields.size })
+    }
+    touched.clear()
+  }
+  window.addEventListener('pagehide', flushAbandons)
+  cleanups.push(() => window.removeEventListener('pagehide', flushAbandons))
+
+  return {
+    onNavigate: (path: string) => {
+      flushAbandons()
+      const loop = navLoop.push(path, Date.now())
+      if (loop) emit('nav_loop', { from: loop.from, to: loop.to })
+    },
+    teardown: () => {
+      for (const cleanup of cleanups) cleanup()
+      touched.clear()
+      w[INSTALLED_FLAG] = false
+    },
+  }
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 export { Holdy, HoldyCore, DEFAULT_BASE_URL } from './server'
 export { HoldyWeb, initHoldy } from './web'
 export type { HoldyWebOptions } from './web'
+export type { FrictionKind, FrictionSignal, FrictionCaptureOptions } from './friction'
 export type { HoldyOptions, Properties, TrackOverrides, CanonicalEvent } from './types'

package/src/run.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest'
+import { runEventName, withRun, type TrackFn } from './run'
+import type { TrackOverrides } from './types'
+
+function recorder() {
+  const calls: Array<{ name: string; properties?: Record<string, unknown>; overrides?: TrackOverrides }> = []
+  const track: TrackFn = (name, properties, overrides) => calls.push({ name, properties, overrides })
+  return { calls, track }
+}
+
+describe('withRun', () => {
+  it('carimba a mesma ai_run_id em início, passos e fim, com a conta em cada evento', async () => {
+    const { calls, track } = recorder()
+    const out = await withRun(track, { name: 'support_agent', accountKey: 'acme' }, async (run) => {
+      run.track('ticket_drafted', { ai_tokens: 1200 })
+      return 'ok'
+    })
+    expect(out).toBe('ok')
+    expect(calls.map((c) => c.name)).toEqual(['support_agent.started', 'ticket_drafted', 'support_agent.completed'])
+    const ids = new Set(calls.map((c) => c.properties?.ai_run_id))
+    expect(ids.size).toBe(1)
+    expect(calls.every((c) => c.overrides?.accountKey === 'acme')).toBe(true)
+    expect(calls[1].properties?.ai_tokens).toBe(1200)
+  })
+
+  it('o erro propaga e sai um .failed só com o nome do erro', async () => {
+    const { calls, track } = recorder()
+    await expect(
+      withRun(track, { name: 'agent', runId: 'trace-77' }, () => {
+        throw new TypeError('dado do cliente')
+      }),
+    ).rejects.toThrow(TypeError)
+    const failed = calls.find((c) => c.name === 'agent.failed')
+    expect(failed?.properties?.error).toBe('TypeError')
+    expect(calls.every((c) => c.properties?.ai_run_id === 'trace-77')).toBe(true)
+  })
+
+  it('a chave da execução não é sobrescrita por propriedade do passo', async () => {
+    const { calls, track } = recorder()
+    await withRun(track, { name: 'agent', runId: 'r1' }, (run) => run.track('step', { ai_run_id: 'outro' }))
+    expect(calls.every((c) => c.properties?.ai_run_id === 'r1')).toBe(true)
+  })
+
+  it('não duplica o sufixo quando o nome termina em ponto', () => {
+    expect(runEventName('agent.', 'started')).toBe('agent.started')
+  })
+})