@holdyapp/sdk 1.5.0 → 1.9.0

package/src/friction.ts

@@ -79,7 +79,7 @@ export class NavLoopDetector {
 }
 
 export interface ElementLike {
-  tagName: string
+  tagName?: string
   id?: string
   disabled?: boolean
   textContent?: string | null
@@ -87,11 +87,15 @@ export interface ElementLike {
   closest?(selector: string): ElementLike | null
 }
 
+function tagOf(el: { tagName?: unknown } | null | undefined): string {
+  return typeof el?.tagName === 'string' ? el.tagName.toLowerCase() : ''
+}
+
 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()
+  const tag = tagOf(el)
   if (INTERACTIVE_TAGS.has(tag)) return el
   const role = el.getAttribute('role')
   if (role === 'button' || role === 'link' || role === 'menuitem' || role === 'tab') return el
@@ -104,7 +108,7 @@ export function isDeadClickTarget(el: ElementLike | null): boolean {
   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()
+  const tag = tagOf(target)
   if (tag === 'a') {
     const href = target.getAttribute('href')
     if (!href || href === '#' || href.startsWith('javascript:')) return true
@@ -115,7 +119,7 @@ export function isDeadClickTarget(el: ElementLike | null): boolean {
 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() }
+  const out: Record<string, string> = { element: tagOf(target) }
   if (target.id) out.element_id = target.id
   const role = target.getAttribute('role')
   if (role) out.element_role = role
@@ -146,6 +150,33 @@ export function errorMessage(reason: unknown): string {
   }
 }
 
+const STACK_MAX_FRAMES = 8
+const STACK_MAX_FRAME_CHARS = 200
+const STACK_FRAME = /^at\s|^\S*@\S+:\d+(?::\d+)?$/
+
+export function sanitizeStack(stack: unknown): string | null {
+  if (typeof stack !== 'string' || !stack) return null
+  const frames = stack
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && STACK_FRAME.test(line))
+    .slice(0, STACK_MAX_FRAMES)
+    .map((line) =>
+      line
+        .replace(/(https?:\/\/[^\s)?#]+)[?#][^\s)]*?(?=(?::\d+){0,2}\)?$)/, '$1')
+        .slice(0, STACK_MAX_FRAME_CHARS),
+    )
+  return frames.length > 0 ? frames.join('\n') : null
+}
+
+function withStack(stack: string | null): { stack?: string } {
+  return stack ? { stack } : {}
+}
+
+function stackOf(reason: unknown): string | null {
+  return typeof reason === 'object' && reason !== null ? sanitizeStack((reason as { stack?: unknown }).stack) : null
+}
+
 export function isAbortError(err: unknown): boolean {
   return typeof err === 'object' && err !== null && (err as { name?: unknown }).name === 'AbortError'
 }
@@ -278,13 +309,19 @@ export function installFrictionCapture(opts: FrictionCaptureOptions): FrictionCa
       message: String(ev.message ?? '').slice(0, 200),
       ...(ev.filename ? { source: stripRequestUrl(ev.filename, location.href) } : {}),
       ...(ev.lineno ? { line: ev.lineno } : {}),
+      ...(ev.colno ? { column: ev.colno } : {}),
+      ...withStack(stackOf(ev.error)),
     })
   }
   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 })
+    emit('js_error', {
+      message: errorMessage(ev.reason).slice(0, 200),
+      unhandled_rejection: true,
+      ...withStack(stackOf(ev.reason)),
+    })
   }
   window.addEventListener('unhandledrejection', onRejection)
   cleanups.push(() => window.removeEventListener('unhandledrejection', onRejection))
@@ -378,11 +415,11 @@ export function installFrictionCapture(opts: FrictionCaptureOptions): FrictionCa
 
   const onFocusIn = (ev: FocusEvent): void => {
     const el = ev.target as HTMLElement | null
-    if (!el || !FORM_CONTROL_TAGS.has(el.tagName.toLowerCase())) return
+    if (!el || !FORM_CONTROL_TAGS.has(tagOf(el))) 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()
+    const field = (el as HTMLInputElement).name || el.id || tagOf(el)
     entry.fields.add(field)
     touched.set(form, entry)
   }

package/src/skeleton.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest'
+import { collectSkeleton, describeSkeletonElement, fnv1a, SKELETON_MAX_ELEMENTS, type SkeletonElementLike } from './skeleton'
+
+function el(tag: string, attrs: Record<string, string> = {}, rect = { x: 10, y: 20, width: 100, height: 40 }): SkeletonElementLike {
+  return {
+    tagName: tag.toUpperCase(),
+    getAttribute: (name) => attrs[name] ?? null,
+    getBoundingClientRect: () => rect,
+  }
+}
+
+const viewport = { width: 1000, height: 2000, scrollY: 0 }
+
+describe('fnv1a', () => {
+  it('é estável e conhecido', () => {
+    expect(fnv1a('')).toBe('811c9dc5')
+    expect(fnv1a('a')).toBe('e40c292c')
+    expect(fnv1a('holdy')).toBe(fnv1a('holdy'))
+  })
+})
+
+describe('describeSkeletonElement', () => {
+  it('guarda tag, role, data-testid, name, aria-label e tipo, nunca texto nem valor', () => {
+    const out = describeSkeletonElement(
+      el('input', { type: 'Email', name: 'email', 'aria-label': '  Seu   e-mail ', value: 'segredo@x.com', placeholder: 'Digite' }),
+      viewport,
+    )
+    expect(out).toEqual({ t: 'input', n: 'email', l: 'Seu e-mail', k: 'email', b: [1, 1, 10, 2] })
+    expect(JSON.stringify(out)).not.toContain('segredo')
+  })
+
+  it('sem viewport não há geometria', () => {
+    expect(describeSkeletonElement(el('button', { 'data-testid': 'continue' }), null)).toEqual({ t: 'button', id: 'continue' })
+  })
+})
+
+describe('collectSkeleton', () => {
+  const root = (items: SkeletonElementLike[]) => ({ querySelectorAll: () => items })
+
+  it('o hash ignora a geometria e muda com a estrutura', () => {
+    const a = collectSkeleton(root([el('button', { 'data-testid': 'go' }, { x: 0, y: 0, width: 50, height: 20 })]), '/x', viewport)
+    const b = collectSkeleton(root([el('button', { 'data-testid': 'go' }, { x: 300, y: 900, width: 80, height: 30 })]), '/x', viewport)
+    const c = collectSkeleton(root([el('button', { 'data-testid': 'stop' })]), '/x', viewport)
+    expect(a.hash).toBe(b.hash)
+    expect(a.hash).not.toBe(c.hash)
+    expect(a.elements[0].b).toEqual([0, 0, 5, 1])
+  })
+
+  it('deixa fora input hidden e elemento sem tamanho, e conta o total antes do teto', () => {
+    const many = Array.from({ length: SKELETON_MAX_ELEMENTS + 10 }, (_, i) => el('a', { href: `/p/${i}` }))
+    const out = collectSkeleton(
+      root([el('input', { type: 'hidden', name: 'csrf' }), el('button', {}, { x: 0, y: 0, width: 0, height: 0 }), ...many]),
+      '/lista',
+      viewport,
+    )
+    expect(out.count).toBe(SKELETON_MAX_ELEMENTS + 10)
+    expect(out.elements).toHaveLength(SKELETON_MAX_ELEMENTS)
+    expect(out.elements.every((e) => e.t === 'a')).toBe(true)
+  })
+})

package/src/skeleton.ts

@@ -0,0 +1,182 @@
+import { readTheme, type PageTheme } from './theme'
+
+export const SKELETON_SELECTOR =
+  'a[href], button, input, select, textarea, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="checkbox"], [role="radio"], [role="switch"], [data-testid]'
+export const SKELETON_MAX_ELEMENTS = 80
+export const SKELETON_DELAY_MS = 1500
+const SENT_STORAGE_KEY = 'holdy_skeletons'
+const SENT_STORAGE_MAX = 200
+
+export interface SkeletonRect {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+export interface SkeletonElementLike {
+  tagName: string
+  getAttribute(name: string): string | null
+  getBoundingClientRect?(): SkeletonRect
+}
+
+export interface SkeletonRootLike {
+  querySelectorAll(selector: string): ArrayLike<SkeletonElementLike>
+}
+
+export interface SkeletonViewport {
+  width: number
+  height: number
+  scrollY: number
+}
+
+export interface SkeletonElement {
+  t: string
+  r?: string
+  id?: string
+  n?: string
+  l?: string
+  k?: string
+  b?: [number, number, number, number]
+}
+
+export interface PageSkeleton {
+  path: string
+  hash: string
+  count: number
+  elements: SkeletonElement[]
+  theme?: PageTheme
+}
+
+export function fnv1a(input: string): string {
+  let hash = 0x811c9dc5
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i)
+    hash = Math.imul(hash, 0x01000193) >>> 0
+  }
+  return hash.toString(16).padStart(8, '0')
+}
+
+function attr(el: SkeletonElementLike, name: string, max: number): string | undefined {
+  const value = el.getAttribute(name)
+  if (!value) return undefined
+  const trimmed = value.replace(/\s+/g, ' ').trim().slice(0, max)
+  return trimmed || undefined
+}
+
+function isVisible(el: SkeletonElementLike): boolean {
+  if (!el.getBoundingClientRect) return true
+  const rect = el.getBoundingClientRect()
+  return rect.width > 0 && rect.height > 0
+}
+
+function relativeBox(rect: SkeletonRect, viewport: SkeletonViewport): [number, number, number, number] {
+  const pct = (value: number, base: number) => (base > 0 ? Math.max(0, Math.min(100, Math.round((value / base) * 100))) : 0)
+  return [pct(rect.x, viewport.width), pct(rect.y + viewport.scrollY, viewport.height), pct(rect.width, viewport.width), pct(rect.height, viewport.height)]
+}
+
+export function describeSkeletonElement(el: SkeletonElementLike, viewport: SkeletonViewport | null): SkeletonElement {
+  const out: SkeletonElement = { t: el.tagName.toLowerCase() }
+  const role = attr(el, 'role', 40)
+  if (role) out.r = role
+  const testid = attr(el, 'data-testid', 80)
+  if (testid) out.id = testid
+  const name = attr(el, 'name', 80)
+  if (name) out.n = name
+  const label = attr(el, 'aria-label', 80)
+  if (label) out.l = label
+  if (out.t === 'input' || out.t === 'button') {
+    const type = attr(el, 'type', 20)
+    if (type) out.k = type.toLowerCase()
+  }
+  if (viewport && el.getBoundingClientRect) out.b = relativeBox(el.getBoundingClientRect(), viewport)
+  return out
+}
+
+export function collectSkeleton(
+  root: SkeletonRootLike,
+  path: string,
+  viewport: SkeletonViewport | null,
+  theme: PageTheme | null = null,
+): PageSkeleton {
+  const found = root.querySelectorAll(SKELETON_SELECTOR)
+  const visible: SkeletonElementLike[] = []
+  for (let i = 0; i < found.length; i++) {
+    const el = found[i]
+    if (el.tagName.toLowerCase() === 'input' && (el.getAttribute('type') ?? '').toLowerCase() === 'hidden') continue
+    if (!isVisible(el)) continue
+    visible.push(el)
+  }
+  const elements = visible.slice(0, SKELETON_MAX_ELEMENTS).map((el) => describeSkeletonElement(el, viewport))
+  const structural = elements.map(({ b: _b, ...rest }) => rest)
+  return { path, hash: fnv1a(JSON.stringify(structural)), count: visible.length, elements, ...(theme ? { theme } : {}) }
+}
+
+export interface SkeletonCaptureOptions {
+  onSkeleton: (skeleton: PageSkeleton) => void
+  delayMs?: number
+}
+
+export interface SkeletonCapture {
+  onNavigate: (path: string) => void
+  teardown: () => void
+}
+
+function loadSent(): Set<string> {
+  try {
+    const raw = sessionStorage.getItem(SENT_STORAGE_KEY)
+    const list = raw ? (JSON.parse(raw) as unknown) : []
+    return new Set(Array.isArray(list) ? list.filter((x): x is string => typeof x === 'string') : [])
+  } catch {
+    return new Set()
+  }
+}
+
+function saveSent(sent: Set<string>): void {
+  try {
+    sessionStorage.setItem(SENT_STORAGE_KEY, JSON.stringify([...sent].slice(-SENT_STORAGE_MAX)))
+  } catch {
+    return
+  }
+}
+
+export function installSkeletonCapture(opts: SkeletonCaptureOptions): SkeletonCapture {
+  if (typeof window === 'undefined' || typeof document === 'undefined') {
+    return { onNavigate: () => undefined, teardown: () => undefined }
+  }
+  const delay = opts.delayMs ?? SKELETON_DELAY_MS
+  const sent = loadSent()
+  let pending: ReturnType<typeof setTimeout> | null = null
+
+  const capture = (path: string): void => {
+    pending = null
+    if (location.pathname !== path) return
+    try {
+      const viewport: SkeletonViewport = {
+        width: window.innerWidth,
+        height: Math.max(document.documentElement.scrollHeight, window.innerHeight),
+        scrollY: window.scrollY,
+      }
+      const theme = readTheme(document, (el) => window.getComputedStyle(el as Element))
+      const skeleton = collectSkeleton(document, path, viewport, theme)
+      const key = `${path}:${skeleton.hash}`
+      if (sent.has(key)) return
+      sent.add(key)
+      saveSent(sent)
+      opts.onSkeleton(skeleton)
+    } catch {
+      return
+    }
+  }
+
+  return {
+    onNavigate: (path: string) => {
+      if (pending) clearTimeout(pending)
+      pending = setTimeout(() => capture(path), delay)
+    },
+    teardown: () => {
+      if (pending) clearTimeout(pending)
+      pending = null
+    },
+  }
+}

package/src/theme.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest'
+import { collectSkeleton } from './skeleton'
+import { applyThemeVars, cleanColor, cleanFont, cleanPx, readTheme, themeVars, type ThemeElementLike } from './theme'
+
+type Styles = Record<string, string>
+
+function el(tagName: string, styles: Styles, size = 1): ThemeElementLike & { styles: Styles } {
+  return { tagName, styles, getBoundingClientRect: () => ({ width: size, height: size }) }
+}
+
+const style = (e: ThemeElementLike) => ({ getPropertyValue: (name: string) => (e as unknown as { styles: Styles }).styles[name] ?? '' })
+
+function doc(body: Styles, buttons: Array<ReturnType<typeof el>> = [], root: Styles = {}) {
+  return {
+    body: el('body', body),
+    documentElement: el('html', root),
+    querySelectorAll: () => buttons,
+  }
+}
+
+describe('readTheme', () => {
+  it('lê fonte, tamanho, cores do body e o botão primário com o raio', () => {
+    const primary = el('button', { 'background-color': 'rgb(37, 99, 235)', color: 'rgb(255, 255, 255)', 'border-top-left-radius': '6px' })
+    const theme = readTheme(
+      doc({ 'font-family': '"Inter", ui-sans-serif, system-ui', 'font-size': '14px', color: 'rgb(23, 23, 23)', 'background-color': 'rgb(255, 255, 255)' }, [primary]),
+      style,
+    )
+    expect(theme).toEqual({
+      font: 'Inter',
+      size: '14px',
+      fg: 'rgb(23, 23, 23)',
+      bg: 'rgb(255, 255, 255)',
+      accent: 'rgb(37, 99, 235)',
+      accentFg: 'rgb(255, 255, 255)',
+      radius: '6px',
+    })
+  })
+
+  it('body transparente cai pro fundo do html; botão invisível ou da cor do fundo não vira acento', () => {
+    const ghost = el('button', { 'background-color': 'rgb(250, 250, 250)', color: 'rgb(0, 0, 0)' })
+    const hidden = el('button', { 'background-color': 'rgb(0, 0, 0)', color: 'rgb(255, 255, 255)' }, 0)
+    const theme = readTheme(doc({ 'background-color': 'rgba(0, 0, 0, 0)', color: 'rgb(10, 10, 10)' }, [hidden, ghost], { 'background-color': 'rgb(250, 250, 250)' }), style)
+    expect(theme).toEqual({ fg: 'rgb(10, 10, 10)', bg: 'rgb(250, 250, 250)' })
+  })
+
+  it('entre vários botões vence o que mais contrasta com o fundo; botão branco em fundo claro não é acento', () => {
+    const white = el('button', { 'background-color': 'rgb(255, 255, 255)', color: 'rgb(8, 8, 10)', 'border-top-left-radius': '7px' })
+    const black = el('button', { 'background-color': 'rgb(23, 23, 26)', color: 'rgb(255, 255, 255)', 'border-top-left-radius': '7px' })
+    const theme = readTheme(doc({ 'background-color': 'rgb(246, 246, 244)' }, [white, black]), style)
+    expect(theme?.accent).toBe('rgb(23, 23, 26)')
+    expect(theme?.accentFg).toBe('rgb(255, 255, 255)')
+    const only = readTheme(doc({ 'background-color': 'rgb(246, 246, 244)' }, [white]), style)
+    expect(only?.accent).toBeUndefined()
+  })
+
+  it('o raio vem do próprio elemento âncora quando ele é um botão', () => {
+    const primary = el('button', { 'background-color': 'rgb(0, 0, 0)', color: 'rgb(255, 255, 255)', 'border-top-left-radius': '999px' })
+    const anchor = el('button', { 'border-top-left-radius': '4px' })
+    const theme = readTheme(doc({ 'background-color': 'rgb(255, 255, 255)' }, [primary]), style, anchor)
+    expect(theme?.radius).toBe('4px')
+    expect(theme?.accent).toBe('rgb(0, 0, 0)')
+  })
+
+  it('sem body ou sem nada legível devolve null', () => {
+    expect(readTheme({ body: null, documentElement: el('html', {}), querySelectorAll: () => [] }, style)).toBeNull()
+    expect(readTheme(doc({}), style)).toBeNull()
+  })
+})
+
+describe('limpeza dos valores', () => {
+  it('cor só em formato de computed style, nunca texto livre', () => {
+    expect(cleanColor('rgb(1, 2, 3)')).toBe('rgb(1, 2, 3)')
+    expect(cleanColor('oklch(0.6 0.1 250)')).toBe('oklch(0.6 0.1 250)')
+    expect(cleanColor('transparent')).toBeUndefined()
+    expect(cleanColor('rgba(0, 0, 0, 0)')).toBeUndefined()
+    expect(cleanColor('url(javascript:alert(1))')).toBeUndefined()
+    expect(cleanColor('red; background: url(x)')).toBeUndefined()
+  })
+
+  it('fonte é a primeira família, sem aspas, e só letras', () => {
+    expect(cleanFont('"Söhne", sans-serif')).toBeUndefined()
+    expect(cleanFont("'Geist Sans', system-ui")).toBe('Geist Sans')
+    expect(cleanFont('Inter')).toBe('Inter')
+    expect(cleanFont('')).toBeUndefined()
+  })
+
+  it('pixel dentro da faixa, arredondado', () => {
+    expect(cleanPx('13.5px', 10, 20)).toBe('14px')
+    expect(cleanPx('32px', 10, 20)).toBeUndefined()
+    expect(cleanPx('1rem', 10, 20)).toBeUndefined()
+  })
+})
+
+describe('themeVars e applyThemeVars', () => {
+  it('vira variáveis --holdy-* só com o que foi lido, e limpa o que havia antes', () => {
+    expect(themeVars({ font: 'Inter', accent: 'rgb(0, 0, 0)' })).toEqual([
+      ['--holdy-font', 'Inter'],
+      ['--holdy-accent', 'rgb(0, 0, 0)'],
+    ])
+    const set: Record<string, string> = { '--holdy-bg': 'old' }
+    const host = { style: { setProperty: (n: string, v: string) => void (set[n] = v), removeProperty: (n: string) => void delete set[n] } }
+    applyThemeVars(host, { fg: 'rgb(1, 1, 1)' })
+    expect(set).toEqual({ '--holdy-fg': 'rgb(1, 1, 1)' })
+    applyThemeVars(host, null)
+    expect(set).toEqual({})
+  })
+})
+
+describe('esqueleto com tema', () => {
+  it('o tema viaja no esqueleto sem entrar no hash', () => {
+    const root = { querySelectorAll: () => [{ tagName: 'BUTTON', getAttribute: (n: string) => (n === 'data-testid' ? 'save' : null) }] }
+    const plain = collectSkeleton(root, '/x', null)
+    const themed = collectSkeleton(root, '/x', null, { font: 'Inter' })
+    expect(themed.hash).toBe(plain.hash)
+    expect(themed.theme).toEqual({ font: 'Inter' })
+    expect(plain.theme).toBeUndefined()
+  })
+})

package/src/theme.ts

@@ -0,0 +1,120 @@
+export interface PageTheme {
+  font?: string
+  size?: string
+  fg?: string
+  bg?: string
+  accent?: string
+  accentFg?: string
+  radius?: string
+}
+
+export interface ThemeStyleLike {
+  getPropertyValue(name: string): string
+}
+
+export interface ThemeElementLike {
+  tagName: string
+  getBoundingClientRect?(): { width: number; height: number }
+}
+
+export interface ThemeDocLike {
+  body: ThemeElementLike | null
+  documentElement: ThemeElementLike
+  querySelectorAll(selector: string): ArrayLike<ThemeElementLike>
+}
+
+export const THEME_BUTTON_SELECTOR = 'button[type="submit"],[data-testid*="primary"],.btn-primary,button,[role="button"],a.button'
+export const THEME_MAX_BUTTONS = 40
+export const THEME_KEYS: readonly (keyof PageTheme)[] = ['font', 'size', 'fg', 'bg', 'accent', 'accentFg', 'radius']
+
+const COLOR = /^(rgba?\([\d.,\s%/]{1,40}\)|#[0-9a-fA-F]{3,8}|(?:color|oklch|oklab|hsla?|lab|lch)\([^()]{1,60}\))$/
+/** Distância mínima entre o botão e o fundo pra valer como cor primária: um botão branco em fundo claro não é acento. */
+export const MIN_ACCENT_CONTRAST = 60
+const RGB = /^rgba?\(\s*(\d+)[\s,]+(\d+)[\s,]+(\d+)/
+
+export function colorDistance(a: string, b: string | undefined): number {
+  const x = RGB.exec(a)
+  const y = b ? RGB.exec(b) : null
+  if (!x) return MIN_ACCENT_CONTRAST + 1
+  if (!y) return MIN_ACCENT_CONTRAST + 1
+  return Math.abs(+x[1] - +y[1]) + Math.abs(+x[2] - +y[2]) + Math.abs(+x[3] - +y[3])
+}
+
+const TRANSPARENT = /^(transparent|rgba\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*,\s*0\s*\)|rgba?\(\s*\d+\s+\d+\s+\d+\s*\/\s*0\s*\))$/
+
+export function themeVarName(key: keyof PageTheme): string {
+  return `--holdy-${key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`
+}
+
+export function cleanColor(value: string | null | undefined): string | undefined {
+  const v = (value ?? '').trim()
+  return v && v.length <= 80 && !TRANSPARENT.test(v) && COLOR.test(v) ? v : undefined
+}
+
+export function cleanFont(value: string | null | undefined): string | undefined {
+  const first = (value ?? '').split(',')[0].trim().replace(/^["']|["']$/g, '').trim()
+  return /^[\w\s-]{1,60}$/.test(first) ? first : undefined
+}
+
+export function cleanPx(value: string | null | undefined, min: number, max: number): string | undefined {
+  const m = /^(\d+(?:\.\d+)?)px/.exec((value ?? '').trim())
+  const n = m ? Math.round(Number(m[1])) : NaN
+  return n >= min && n <= max ? `${n}px` : undefined
+}
+
+function visible(el: ThemeElementLike): boolean {
+  const r = el.getBoundingClientRect?.()
+  return !r || (r.width > 0 && r.height > 0)
+}
+
+export function readTheme(
+  doc: ThemeDocLike,
+  getStyle: (el: ThemeElementLike) => ThemeStyleLike,
+  anchor: ThemeElementLike | null = null,
+): PageTheme | null {
+  const body = doc.body
+  if (!body) return null
+  const bodyStyle = getStyle(body)
+  const theme: PageTheme = {}
+  const put = (key: keyof PageTheme, value: string | undefined) => {
+    if (value) theme[key] = value
+  }
+  put('font', cleanFont(bodyStyle.getPropertyValue('font-family')))
+  put('size', cleanPx(bodyStyle.getPropertyValue('font-size'), 10, 20))
+  put('fg', cleanColor(bodyStyle.getPropertyValue('color')))
+  put('bg', cleanColor(bodyStyle.getPropertyValue('background-color')) ?? cleanColor(getStyle(doc.documentElement).getPropertyValue('background-color')))
+
+  const candidates = doc.querySelectorAll(THEME_BUTTON_SELECTOR)
+  let button: ThemeElementLike | null = null
+  let best = MIN_ACCENT_CONTRAST
+  for (let i = 0; i < candidates.length && i < THEME_MAX_BUTTONS; i++) {
+    const el = candidates[i]
+    if (!visible(el)) continue
+    const s = getStyle(el)
+    const accent = cleanColor(s.getPropertyValue('background-color'))
+    if (!accent || accent === theme.bg) continue
+    const contrast = colorDistance(accent, theme.bg)
+    if (contrast <= best) continue
+    best = contrast
+    put('accent', accent)
+    put('accentFg', cleanColor(s.getPropertyValue('color')))
+    button = el
+  }
+  const radiusSource = anchor && anchor.tagName.toLowerCase() === 'button' ? anchor : button
+  if (radiusSource) put('radius', cleanPx(getStyle(radiusSource).getPropertyValue('border-top-left-radius'), 0, 24))
+  return Object.keys(theme).length > 0 ? theme : null
+}
+
+export function themeVars(theme: PageTheme | null | undefined): Array<[string, string]> {
+  const out: Array<[string, string]> = []
+  for (const key of THEME_KEYS) {
+    const value = theme?.[key]
+    if (value) out.push([themeVarName(key), value])
+  }
+  return out
+}
+
+export function applyThemeVars(el: { style: { setProperty(name: string, value: string): void; removeProperty(name: string): void } }, theme: PageTheme | null | undefined): void {
+  for (const key of THEME_KEYS) el.style.removeProperty(themeVarName(key))
+  for (const [name, value] of themeVars(theme)) el.style.setProperty(name, value)
+}

package/src/tip-css.ts

@@ -0,0 +1,32 @@
+/**
+ * O card da dica e da pergunta, como o SDK desenha no produto do cliente.
+ * O painel da Holdy importa daqui pra prévia: a mesma folha, nunca uma cópia.
+ * As variáveis --holdy-* chegam do tema lido na página (theme.ts): fonte,
+ * cores, raio e cor do botão primário do produto do cliente. Sem tema, o
+ * card cai no visual próprio (escuro no claro, claro no escuro).
+ */
+export const TIP_CSS = `:host{all:initial;--h-bg:#111;--h-fg:#fff;--h-accent:#fff;--h-accent-fg:#111;--h-border:transparent}
+@media (prefers-color-scheme:dark){:host{--h-bg:#fff;--h-fg:#111;--h-accent:#111;--h-accent-fg:#fff}}
+.tip{position:fixed;box-sizing:border-box;max-width:280px;padding:10px 12px;border-radius:var(--holdy-radius,8px);background:var(--holdy-bg,var(--h-bg));color:var(--holdy-fg,var(--h-fg));border:1px solid color-mix(in srgb,var(--holdy-fg,var(--h-fg)) 14%,transparent);font:var(--holdy-size,13px)/1.45 var(--holdy-font,system-ui),system-ui,-apple-system,sans-serif;box-shadow:0 8px 24px rgba(0,0,0,.18);pointer-events:auto;display:flex;gap:10px;align-items:flex-start}
+.tip p{margin:0;flex:1}
+.tip button{all:unset;cursor:pointer;opacity:.7;font-size:15px;line-height:1;color:inherit}
+.tip button:hover,.tip button:focus-visible{opacity:1}
+.ask{flex-direction:column;width:300px;max-width:calc(100vw - 16px);gap:8px}
+.ask .head{display:flex;gap:10px;align-items:flex-start;width:100%}
+.ask textarea{all:unset;box-sizing:border-box;width:100%;min-height:56px;padding:8px;border-radius:calc(var(--holdy-radius,8px) * .75);background:color-mix(in srgb,var(--holdy-fg,var(--h-fg)) 8%,transparent);color:inherit;font:inherit;white-space:pre-wrap;overflow-wrap:anywhere;cursor:text}
+.ask textarea:focus-visible{outline:2px solid color-mix(in srgb,var(--holdy-fg,var(--h-fg)) 45%,transparent)}
+.ask .send{align-self:flex-end;padding:5px 12px;border-radius:calc(var(--holdy-radius,8px) * .75);background:var(--holdy-accent,var(--h-accent));color:var(--holdy-accent-fg,var(--h-accent-fg));font-size:12.5px;font-weight:500;opacity:1}
+.ask .send[disabled]{opacity:.4;cursor:default}
+.list{flex-direction:column;width:300px;max-width:calc(100vw - 16px);gap:8px}
+.list .head{display:flex;gap:10px;align-items:flex-start;width:100%}
+.list .head p{display:flex;justify-content:space-between;gap:10px;align-items:baseline}
+.list .count{opacity:.7;font-size:12px;white-space:nowrap}
+.list ul{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:6px;width:100%}
+.list li{display:flex;gap:8px;align-items:flex-start}
+.list li.done{opacity:.55;text-decoration:line-through}
+.list .mark{flex:none;width:16px;height:16px;border-radius:4px;border:1px solid color-mix(in srgb,var(--holdy-fg,var(--h-fg)) 45%,transparent);font-size:11px;line-height:16px;text-align:center}
+.list li.done .mark{background:var(--holdy-accent,var(--h-accent));color:var(--holdy-accent-fg,var(--h-accent-fg));border-color:var(--holdy-accent,var(--h-accent))}
+.list.folded ul{display:none}
+.list.folded{width:auto}
+.preview{flex:none;order:-1;width:100%;font-size:11px;opacity:.7}
+.tip:has(.preview){flex-wrap:wrap;row-gap:4px}`

package/src/types.ts

@@ -35,6 +35,12 @@ export interface HoldyOptions {
    * declarar a account COM traits.
    */
   accountKey?: string
+  /**
+   * Versão do produto no ar (sha do commit, tag ou número do build). Vai em
+   * `context.release` de todo evento, pra Holdy dizer em que versão um erro
+   * apareceu.
+   */
+  release?: string
   /** Logs de debug no console. */
   debug?: boolean
 }

package/src/web-context.test.ts

@@ -69,3 +69,21 @@ describe('parseUserAgent', () => {
     expect(parseUserAgent('')).toEqual({})
   })
 })
+
+describe('clearSessionId', () => {
+  it('reset encerra a sessão: a próxima pessoa na mesma aba não herda a anterior', async () => {
+    const guardado = new Map<string, string>()
+    const janela = globalThis as unknown as { sessionStorage?: unknown }
+    janela.sessionStorage = {
+      getItem: (k: string) => guardado.get(k) ?? null,
+      setItem: (k: string, v: string) => void guardado.set(k, v),
+      removeItem: (k: string) => void guardado.delete(k),
+    }
+    const { clearSessionId, resolveSessionId } = await import('./web-context')
+    const primeira = resolveSessionId()
+    expect(resolveSessionId()).toBe(primeira)
+    clearSessionId()
+    expect(resolveSessionId()).not.toBe(primeira)
+    delete janela.sessionStorage
+  })
+})

package/src/web-context.ts

@@ -148,6 +148,14 @@ function randomId(): string {
   }
 }
 
+export function clearSessionId(): void {
+  try {
+    sessionStorage.removeItem(SESSION_STORAGE_KEY)
+  } catch {
+    // storage indisponível (SSR/privacy mode) — ok
+  }
+}
+
 /** ID da sessão de browser · vive enquanto a aba viver. */
 export function resolveSessionId(): string {
   const existing = readStorage('session', SESSION_STORAGE_KEY)