@holdyapp/sdk 1.5.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holdyapp/sdk",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Holdy SDK · track/identify/group/page → POST /api/v1/events (entry-contract v1) · auto-capture web",
   "license": "MIT",
   "homepage": "https://holdy.chat",

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,173 @@
+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[]
+}
+
+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): 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 }
+}
+
+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 skeleton = collectSkeleton(document, path, viewport)
+      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/web.ts

@@ -14,6 +14,7 @@
 import { HoldyCore } from './core'
 import { installAutoCapture, type NavigationKind } from './auto-capture'
 import { installFrictionCapture, type FrictionCapture, type FrictionCaptureOptions } from './friction'
+import { installSkeletonCapture, type SkeletonCapture } from './skeleton'
 import { buildWebContext } from './web-context'
 import { installProductChanges, type ProductChangesHandle } from './changes'
 import type { HoldyOptions, Properties } from './types'
@@ -40,12 +41,20 @@ export interface HoldyWebOptions extends HoldyOptions {
    * identificada (`group()` ou `accountKey`) nada é aplicado.
    */
   productChanges?: boolean
+  /**
+   * Mandar o esqueleto da página · default true. Uma vez por (rota, estrutura)
+   * por aba: `$page_skeleton` com os elementos interativos (tag, role,
+   * data-testid, name, aria-label, tipo, posição relativa). Sem texto livre,
+   * sem valor de input, sem pixel.
+   */
+  skeleton?: boolean
 }
 
 export class HoldyWeb extends HoldyCore {
   private teardownAutoCapture: (() => void) | null = null
   private friction: FrictionCapture | null = null
   private changes: ProductChangesHandle | null = null
+  private skeleton: SkeletonCapture | null = null
 
   constructor(opts: HoldyWebOptions) {
     super('sdk_web', opts)
@@ -67,12 +76,20 @@ export class HoldyWeb extends HoldyCore {
       })
     }
 
+    if (opts.skeleton !== false) {
+      this.skeleton = installSkeletonCapture({
+        onSkeleton: (skeleton) => this.track('$page_skeleton', { ...skeleton }),
+      })
+    }
+
     if (opts.autoCapture !== false) {
       this.teardownAutoCapture = installAutoCapture({
         onNavigate: (kind: NavigationKind) => {
           this.page(undefined, { navigation: kind })
-          this.friction?.onNavigate(typeof location !== 'undefined' ? location.pathname : '/')
+          const path = typeof location !== 'undefined' ? location.pathname : '/'
+          this.friction?.onNavigate(path)
           this.changes?.onNavigate()
+          this.skeleton?.onNavigate(path)
         },
       })
     }
@@ -128,6 +145,8 @@ export class HoldyWeb extends HoldyCore {
     this.friction = null
     this.changes?.teardown()
     this.changes = null
+    this.skeleton?.teardown()
+    this.skeleton = null
     await super.shutdown()
   }