@obsrviq/tracker 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -18,6 +18,9 @@ declare class ObsrviqClient {
     private recording;
     private consent;
     private sampledIn;
+    /** Manual-control intent. In autoStart:false mode, recording only begins once
+     *  the host calls startRecording() (which sets this); stopRecording() clears it. */
+    private manualStartRequested;
     private lastActivity;
     /** The userId this session is attributed to (for the shared-device split). */
     private currentUserId;
@@ -84,6 +87,16 @@ declare class ObsrviqClient {
     /** Gate recording (PRIV-2). true starts; false stops + flushes. Dismisses the
      *  built-in consent prompt if one is showing. */
     setConsent(granted: boolean): void;
+    /** 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;
+    /** 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;
     /** Hard stop + flush. */
     stop(): void;
     /** Force a flush now (returns when send is attempted). */

package/dist/index.js

@@ -1025,6 +1025,26 @@ function instrumentInteractions(ctx) {
     if (!target || !(target instanceof Element)) return;
     const t = ctx.clock.now();
     const selector = cssPath(target);
+    {
+      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 * 1e3) / 1e3,
+          ry: Math.round(ry * 1e3) / 1e3,
+          tag: target.tagName.toLowerCase(),
+          label
+        },
+        t
+      );
+    }
     recent = recent.filter((r) => t - r.t <= RAGE_WINDOW_MS);
     recent.push({ el: target, t });
     const sameTarget = recent.filter((r) => r.el === target);
@@ -1049,6 +1069,7 @@ function instrumentInteractions(ctx) {
 var TRACKED = /* @__PURE__ */ new Set(["INPUT", "TEXTAREA", "SELECT"]);
 var SKIP_INPUT_TYPES = /* @__PURE__ */ new Set(["hidden", "submit", "button", "reset", "image", "file"]);
 var MAX_KEY = 80;
+var MAX_HINT = 60;
 var MAX_FOCUS_MS = 3e5;
 var MIN_FOCUS_MS = 100;
 function isTracked(el) {
@@ -1092,6 +1113,56 @@ function fieldKey(el) {
   if (ph) return clip(ph);
   return clip(cssPath(el));
 }
+function clipHint(s) {
+  if (!s) return void 0;
+  const t = s.trim().replace(/\s+/g, " ");
+  if (!t) return void 0;
+  return t.length > MAX_HINT ? t.slice(0, MAX_HINT) : t;
+}
+function nearbyText(el) {
+  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;
+  let sib = 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;
+  }
+  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"));
+}
+function formTitleHint(el) {
+  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 : void 0);
+}
+function namingHints(el) {
+  const out = {};
+  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;
+}
 function formKey(el) {
   const form = el.form;
   if (form) {
@@ -1145,7 +1216,8 @@ function instrumentForms(ctx) {
       type: controlType(el),
       ms,
       changed,
-      filled: isFilled(el)
+      filled: isFilled(el),
+      ...namingHints(el)
     });
   };
   const onFocusIn = (ev) => {
@@ -1188,7 +1260,7 @@ function instrumentScrollDepth(ctx) {
   let path = location.pathname;
   let maxBand = 0;
   let scheduled = false;
-  const emit = (depth) => {
+  const emit = (depth, h, vh) => {
     const e = {
       id: uuid(),
       sessionId: ctx.sessionId,
@@ -1196,7 +1268,7 @@ function instrumentScrollDepth(ctx) {
       t: ctx.clock.now(),
       ts: ctx.clock.wall(),
       name: "_scroll",
-      props: { path, depth }
+      props: { path, depth, h, vh }
     };
     ctx.emit(e);
   };
@@ -1212,11 +1284,12 @@ function instrumentScrollDepth(ctx) {
       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);
     }
   };
   const onScroll = () => {
@@ -1498,6 +1571,7 @@ var DEFAULTS = {
   requireConsent: false,
   askPermission: false,
   showRecording: false,
+  autoStart: true,
   maxArgBytes: 8 * 1024
 };
 var ObsrviqClient = class {
@@ -1510,6 +1584,9 @@ var ObsrviqClient = class {
     this.recording = false;
     this.consent = null;
     this.sampledIn = true;
+    /** Manual-control intent. In autoStart:false mode, recording only begins once
+     *  the host calls startRecording() (which sets this); stopRecording() clears it. */
+    this.manualStartRequested = false;
     this.lastActivity = 0;
     /** Next batch seq — mirrored from the transport so we can persist continuation. */
     this.nextSeq = 0;
@@ -1630,6 +1707,7 @@ var ObsrviqClient = class {
   }
   maybeStart() {
     if (this.recording || !this.config || !this.clock || !this.transport) return;
+    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;
@@ -1787,6 +1865,22 @@ var ObsrviqClient = class {
     if (granted) this.maybeStart();
     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() {
+    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() {
+    this.manualStartRequested = false;
+    if (this.recording) this.teardown();
+  }
   /** Hard stop + flush. */
   stop() {
     this.teardown();