@obsrviq/tracker 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@obsrviq/tracker",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -27,7 +27,7 @@
     "@rrweb/types": "2.0.1",
     "fflate": "^0.8.2",
     "rrweb": "2.0.1",
-    "@obsrviq/types": "0.3.0"
+    "@obsrviq/types": "0.4.0"
   },
   "devDependencies": {
     "tsup": "^8.3.5",

package/src/context.ts

@@ -24,6 +24,8 @@ export interface ResolvedConfig {
   requireConsent: boolean;
   askPermission: boolean;
   showRecording: boolean;
+  /** Auto-start recording on init(). False = manual (startRecording()/stopRecording()). */
+  autoStart: boolean;
   consentText?: { title?: string; body?: string; allow?: string; deny?: string };
   beforeSend?: (batch: IngestBatch) => IngestBatch | null;
   maxArgBytes: number;

package/src/forms.ts

@@ -16,6 +16,11 @@ import { uuid } from './util.js';
  * `form_submit` event is emitted when a form is submitted; the last field
  * touched in a session whose form never submitted is the drop-off point.
  *
+ * Each event also carries optional naming hints — `autocomplete`, `near` (the
+ * field's visible label text), and `formTitle` (the form's heading) — so the
+ * server can turn opaque keys (a React `useId()`, a CSS-selector path) into
+ * human names like "Work email". Hints are static UI chrome, never values.
+ *
  * Privacy: values are never read. `filled` is a boolean derived from value
  * length (or `checked`); the field key comes from structural attributes
  * (name / id / label), exactly as form-analytics tools do. Controls inside a
@@ -27,6 +32,7 @@ const TRACKED = new Set(['INPUT', 'TEXTAREA', 'SELECT']);
 // measuring (and file is privacy-adjacent), so they're left out.
 const SKIP_INPUT_TYPES = new Set(['hidden', 'submit', 'button', 'reset', 'image', 'file']);
 const MAX_KEY = 80;
+const MAX_HINT = 60; // naming hints are short labels, not keys
 const MAX_FOCUS_MS = 300_000; // cap idle-inflated focus time (walked-away tab)
 const MIN_FOCUS_MS = 100; // ignore sub-100ms programmatic focus blips
 
@@ -80,6 +86,74 @@ function fieldKey(el: FormControl): string {
   return clip(cssPath(el));
 }
 
+function clipHint(s: string | null | undefined): string | undefined {
+  if (!s) return undefined;
+  const t = s.trim().replace(/\s+/g, ' ');
+  if (!t) return undefined;
+  return t.length > MAX_HINT ? t.slice(0, MAX_HINT) : t;
+}
+
+/**
+ * Visible text a human reads as this field's label — used ONLY as a naming hint
+ * for the server's AI pass, never as the stable key. It reads static UI chrome
+ * (a <label>, a wrapper's own text, a preceding label element) so opaque keys
+ * like a React `useId()` or a CSS-selector path can still be named "Work email".
+ * The control's value is never read; tracked controls and buttons are skipped so
+ * a sibling input's contents can't leak in.
+ */
+function nearbyText(el: FormControl): string | undefined {
+  if (el.labels && el.labels.length) {
+    const t = clipHint(el.labels[0]!.textContent);
+    if (t) return t;
+  }
+  const aria = clipHint(el.getAttribute('aria-label'));
+  if (aria) return aria;
+  // A label rendered as a plain element just before the control.
+  let sib: Element | null = el.previousElementSibling;
+  for (let hops = 0; sib && hops < 3; hops++, sib = sib.previousElementSibling) {
+    if (TRACKED.has(sib.tagName) || /^(BUTTON|SCRIPT|STYLE|SVG)$/.test(sib.tagName)) continue;
+    const t = clipHint(sib.textContent);
+    if (t) return t;
+  }
+  // <div class="field">Label <input/></div> — the wrapper's own direct text.
+  const parent = el.parentElement;
+  if (parent) {
+    const direct = clipHint(
+      Array.from(parent.childNodes).filter((n) => n.nodeType === 3).map((n) => n.textContent || '').join(' '),
+    );
+    if (direct) return direct;
+    const lbl = clipHint(parent.querySelector('label,legend')?.textContent);
+    if (lbl) return lbl;
+  }
+  return clipHint(el.getAttribute('placeholder'));
+}
+
+/** The nearest heading/legend a user sees over the owning form — a naming hint. */
+function formTitleHint(el: FormControl): string | undefined {
+  const scope = el.closest('form,fieldset,section,[role="form"],[role="group"]');
+  if (scope) {
+    const heading = clipHint(scope.querySelector('legend,h1,h2,h3,h4,[role="heading"]')?.textContent);
+    if (heading) return heading;
+    const al = clipHint(scope.getAttribute('aria-label'));
+    if (al) return al;
+  }
+  return clipHint(typeof document !== 'undefined' ? document.title : undefined);
+}
+
+/** Privacy-safe descriptive hints (label text, autocomplete intent, form heading)
+ *  attached to each interaction so the server can name opaque fields/forms. Only
+ *  present keys are emitted, keeping the wire small. */
+function namingHints(el: FormControl): Record<string, string> {
+  const out: Record<string, string> = {};
+  const ac = (el.getAttribute('autocomplete') || '').trim().toLowerCase();
+  if (ac && ac !== 'off' && ac !== 'on') out.autocomplete = ac.slice(0, MAX_HINT);
+  const near = nearbyText(el);
+  if (near) out.near = near;
+  const ft = formTitleHint(el);
+  if (ft) out.formTitle = ft;
+  return out;
+}
+
 /** A stable identity for the owning form (or a per-page bucket for loose fields). */
 function formKey(el: FormControl): string {
   const form = el.form;
@@ -142,6 +216,7 @@ export function instrumentForms(ctx: InstrumentCtx): Teardown {
       ms,
       changed,
       filled: isFilled(el),
+      ...namingHints(el),
     });
   };
 

package/src/global.ts

@@ -5,9 +5,12 @@
  *           data-obsrviq-key="pk_live_xxx"
  *           data-obsrviq-endpoint="https://in.lumera.app"
  *           data-obsrviq-mask-inputs="true"
- *           data-obsrviq-require-consent="false"></script>
+ *           data-obsrviq-require-consent="false"
+ *           data-obsrviq-auto-start="true"></script>
  *
  * Exposes `window.Obsrviq` for manual identify()/track()/setConsent() calls.
+ * For manual recording control, set data-obsrviq-auto-start="false" and call
+ * Obsrviq.startRecording() / Obsrviq.stopRecording() yourself.
  */
 import { Obsrviq } from './index.js';
 import type { ObsrviqInitConfig } from '@obsrviq/types';
@@ -37,6 +40,7 @@ if (current) {
       askPermission: bool(current.getAttribute('data-obsrviq-ask-permission'), false),
       showRecording: bool(current.getAttribute('data-obsrviq-show-recording'), false),
       recordCanvas: bool(current.getAttribute('data-obsrviq-record-canvas'), false),
+      autoStart: bool(current.getAttribute('data-obsrviq-auto-start'), true),
     };
     const rate = current.getAttribute('data-obsrviq-sample-rate');
     if (rate) cfg.sampleRate = Number(rate);

package/src/index.ts

@@ -29,6 +29,7 @@ const DEFAULTS = {
   requireConsent: false,
   askPermission: false,
   showRecording: false,
+  autoStart: true,
   maxArgBytes: 8 * 1024,
 };
 
@@ -50,6 +51,9 @@ class ObsrviqClient {
   private recording = false;
   private consent: boolean | null = null;
   private sampledIn = true;
+  /** Manual-control intent. In autoStart:false mode, recording only begins once
+   *  the host calls startRecording() (which sets this); stopRecording() clears it. */
+  private manualStartRequested = false;
   private lastActivity = 0;
   /** The userId this session is attributed to (for the shared-device split). */
   private currentUserId: string | undefined;
@@ -198,6 +202,8 @@ class ObsrviqClient {
 
   private maybeStart(): void {
     if (this.recording || !this.config || !this.clock || !this.transport) return;
+    // Manual mode: hold off until the host explicitly calls startRecording().
+    if (this.config.autoStart === false && !this.manualStartRequested) return;
     if (this.config.requireConsent && this.consent !== true) return;
     if (this.consent === false) return;
     if (!this.sampledIn) return;
@@ -393,6 +399,24 @@ class ObsrviqClient {
     else if (this.recording) this.teardown();
   }
 
+  /** Begin recording now. The trigger for `autoStart: false` (manual) mode —
+   *  nothing records until this is called. Idempotent: a no-op while already
+   *  recording. Consent, GPC/DNT and sampling still apply (so a consent-gated or
+   *  sampled-out session won't start just because this was called). After a
+   *  stopRecording(), this resumes the SAME session with the idle gap shown. */
+  startRecording(): void {
+    this.manualStartRequested = true;
+    this.maybeStart();
+  }
+
+  /** Stop recording and flush the final batch. Recording stays off until
+   *  startRecording() is called again. (Friendlier name for stop(), and it also
+   *  clears the manual-start intent so recording won't silently resume.) */
+  stopRecording(): void {
+    this.manualStartRequested = false;
+    if (this.recording) this.teardown();
+  }
+
   /** Hard stop + flush. */
   stop(): void {
     this.teardown();

package/src/interactions.ts

@@ -44,6 +44,30 @@ export function instrumentInteractions(ctx: InstrumentCtx): Teardown {
     const t = ctx.clock.now();
     const selector = cssPath(target);
 
+    // ── Click heatmap: one event per click, anchored to the exact element ──
+    // Stored against (path, selector, device) and rolled up server-side. rx/ry are
+    // the click position WITHIN the element (0..1) so heat re-projects at any size.
+    {
+      const rect = target.getBoundingClientRect();
+      const rx = rect.width > 0 ? Math.min(1, Math.max(0, (ev.clientX - rect.left) / rect.width)) : 0.5;
+      const ry = rect.height > 0 ? Math.min(1, Math.max(0, (ev.clientY - rect.top) / rect.height)) : 0.5;
+      const label = (target.textContent || '').replace(/\s+/g, ' ').trim().slice(0, 40);
+      emitCustom(
+        '_click',
+        {
+          selector,
+          path: location.pathname,
+          vw: window.innerWidth,
+          vh: window.innerHeight,
+          rx: Math.round(rx * 1000) / 1000,
+          ry: Math.round(ry * 1000) / 1000,
+          tag: target.tagName.toLowerCase(),
+          label,
+        },
+        t,
+      );
+    }
+
     // ── Rage click detection ──
     recent = recent.filter((r) => t - r.t <= RAGE_WINDOW_MS);
     recent.push({ el: target, t });

package/src/scroll.ts

@@ -8,13 +8,18 @@ import { uuid } from './util.js';
  * each session's max depth per page. Cheap (a handful of events per page at
  * most) and value-free. The page identity is the pathname; depth resets on SPA
  * route changes.
+ *
+ * Each event also carries the page height `h` (full document height, px) and
+ * viewport `vh` at that moment — so the server can tell apart "100% of a short
+ * stub" from "100% of a long article", report absolute pixels reached, and flag
+ * when a templated group blends pages of very different lengths.
  */
 export function instrumentScrollDepth(ctx: InstrumentCtx): Teardown {
   let path = location.pathname;
   let maxBand = 0; // deepest 10% band reached on the current path
   let scheduled = false;
 
-  const emit = (depth: number) => {
+  const emit = (depth: number, h: number, vh: number) => {
     const e: ObsrviqCustomEvent = {
       id: uuid(),
       sessionId: ctx.sessionId,
@@ -22,7 +27,7 @@ export function instrumentScrollDepth(ctx: InstrumentCtx): Teardown {
       t: ctx.clock.now(),
       ts: ctx.clock.wall(),
       name: '_scroll',
-      props: { path, depth },
+      props: { path, depth, h, vh },
     };
     ctx.emit(e);
   };
@@ -41,11 +46,12 @@ export function instrumentScrollDepth(ctx: InstrumentCtx): Teardown {
       maxBand = 0;
     }
     const vh = window.innerHeight || document.documentElement.clientHeight || 1;
-    const reached = Math.min(1, (window.scrollY + vh) / docHeight());
+    const h = docHeight();
+    const reached = Math.min(1, (window.scrollY + vh) / h);
     const band = Math.min(100, Math.round(reached * 10) * 10);
     if (band > maxBand) {
       maxBand = band;
-      emit(band);
+      emit(band, h, vh);
     }
   };