@corbado/observe 1.8.0 → 1.9.0

package/dist/analysis/low-events/input-tracker.mjs

@@ -1,12 +1,31 @@
 // src/low-events/input-tracker.ts
 import { InputChangeRecorder } from "./input-change-recorder.mjs";
-import { InputPasteObserver } from "./input-paste-observer.mjs";
+import { InputPasteObserver } from "../readers/input-paste.mjs";
+import { observeInputField, readFocusedField, readInputContentLength } from "../readers/input.mjs";
+import { listenWindow } from "../readers/page.mjs";
 import { readPasswordManagerDomSignals } from "../readers/password-manager-dom.mjs";
 var MOUNT_PROBE_DELAY_MS = 500;
 var FOCUS_PROBE_DELAY_MS = 250;
 function fieldContentLength(field) {
-  if (field.type === "checkbox" || field.type === "radio") return field.checked ? 1 : 0;
-  return field.value.length;
+  return readInputContentLength(
+    {
+      key: "dom:input.content",
+      title: "Length of the text in tracked input fields",
+      accessNote: "input value length only; the value itself does not leave the reader",
+      group: "Input interaction",
+      origin: "observe-external",
+      fields: [
+        { path: "value.length", label: "Length of the entered text", exposure: "size" },
+        {
+          path: "checked",
+          label: "Whether a checkbox or option is selected",
+          exposure: "enum",
+          transform: { values: [true, false], note: "checkbox and radio only" }
+        }
+      ]
+    },
+    field
+  );
 }
 var LowEventInputTracker = class {
   constructor(logger, inputField, sink) {
@@ -20,6 +39,27 @@ var LowEventInputTracker = class {
       sink.reserveCaptureSeq
     );
     this.pasteObserver = new InputPasteObserver(
+      {
+        key: "dom:input.paste",
+        title: "Paste into tracked input fields",
+        accessNote: "paste events on the input elements the integration passes to Observe; pasted values never leave the reader",
+        group: "Input interaction",
+        origin: "observe-external",
+        fields: [
+          {
+            path: "event.paste",
+            label: "Paste into the field",
+            exposure: "presence",
+            transform: { note: "trusted paste events only" }
+          },
+          {
+            path: "value",
+            label: "Length of the pasted text",
+            exposure: "size",
+            transform: { note: "inserted length only; values are compared in memory and discarded" }
+          }
+        ]
+      },
       [inputField],
       logger,
       (ts, _inserted, captureSeq) => {
@@ -36,27 +76,13 @@ var LowEventInputTracker = class {
       },
       sink.reserveCaptureSeq
     );
-    this.boundHandlers = {
-      focus: this.wrapHandler("focus", () => this.handleFocus()),
-      blur: this.wrapHandler("blur", () => this.handleBlur()),
-      pointerdown: this.wrapHandler("pointerdown", () => this.enqueueNonInputEvent("pointerdown")),
-      pointerup: this.wrapHandler("pointerup", () => this.enqueueNonInputEvent("pointerup")),
-      click: this.wrapHandler("click", () => this.enqueueNonInputEvent("click")),
-      input: (event) => {
-        try {
-          this.handleInput(event);
-        } catch (error) {
-          this.logger.error("Failed to observe input", error);
-        }
-      },
-      keyup: this.wrapKeyboardHandler("keyup", (event) => this.handleKeyUp(event)),
-      pageHide: this.wrapHandler("pagehide", () => this.flushForTeardown())
-    };
     this.unregisterInputs = sink.registerInputs?.([inputField], () => this.flushPending());
     this.capturePrefill();
     this.attach();
   }
   unregisterInputs;
+  removeFieldListeners;
+  removePageHide;
   changes;
   pasteObserver;
   emittedSignals = /* @__PURE__ */ new Set();
@@ -64,7 +90,6 @@ var LowEventInputTracker = class {
   mountProbeTimer = null;
   focusProbeTimer = null;
   destroyed = false;
-  boundHandlers;
   destroy() {
     if (this.destroyed) {
       return;
@@ -89,18 +114,93 @@ var LowEventInputTracker = class {
   }
   attach() {
     const input = this.inputField;
-    input.addEventListener("focus", this.boundHandlers.focus);
-    input.addEventListener("blur", this.boundHandlers.blur);
-    input.addEventListener("pointerdown", this.boundHandlers.pointerdown);
-    input.addEventListener("pointerup", this.boundHandlers.pointerup);
-    input.addEventListener("click", this.boundHandlers.click);
-    input.addEventListener("input", this.boundHandlers.input);
-    input.addEventListener("keyup", this.boundHandlers.keyup);
+    this.removeFieldListeners = observeInputField(
+      {
+        key: "dom:input.events",
+        title: "Interaction with tracked input fields",
+        accessNote: "focus, blur, pointerdown, pointerup, click, input and keyup events on the input elements the integration passes to Observe, reduced to booleans and identities",
+        group: "Input interaction",
+        origin: "observe-external",
+        fields: [
+          { path: "event.focus", label: "Field selected", exposure: "presence" },
+          { path: "event.blur", label: "Field left", exposure: "presence" },
+          { path: "event.pointerdown", label: "Pointer pressed on the field", exposure: "presence" },
+          { path: "event.pointerup", label: "Pointer released on the field", exposure: "presence" },
+          { path: "event.click", label: "Click on the field", exposure: "presence" },
+          { path: "event.input", label: "Typing in the field", exposure: "presence" },
+          {
+            path: "event.input.isComposing",
+            label: "Whether text is being composed with an input method",
+            exposure: "enum",
+            transform: { values: [true, false] }
+          },
+          {
+            path: "event.keyup.key",
+            label: "Escape key pressed",
+            exposure: "enum",
+            transform: { values: ["Escape", "other"] }
+          }
+        ]
+      },
+      input,
+      {
+        focus: () => this.handleFocus(),
+        blur: () => this.handleBlur(),
+        pointerdown: () => this.enqueueNonInputEvent("pointerdown"),
+        pointerup: () => this.enqueueNonInputEvent("pointerup"),
+        click: () => this.enqueueNonInputEvent("click"),
+        input: (composing, event) => this.handleInput(event, composing),
+        keyupEscape: () => this.enqueueNonInputEvent("keyup-escape")
+      },
+      (name, run) => {
+        try {
+          run();
+        } catch (error) {
+          if (name === "input") this.logger.error("Failed to observe input", error);
+          else this.logger.error(`Failed to handle low event "${name}"`, error);
+        }
+      }
+    );
     if (typeof window !== "undefined") {
-      window.addEventListener("pagehide", this.boundHandlers.pageHide);
+      this.removePageHide = listenWindow(
+        {
+          key: "page:lifecycle.pagehide",
+          title: "Leaving the page",
+          accessNote: "pagehide event on window",
+          group: "Page lifecycle",
+          origin: "observe-external",
+          fields: [
+            {
+              path: "event.pagehide",
+              label: "Leaving the page",
+              exposure: "presence",
+              transform: { note: "flushes pending input low events on unload" }
+            }
+          ]
+        },
+        "pagehide",
+        this.wrapHandler("pagehide", () => this.flushForTeardown())
+      );
     }
     if (typeof document !== "undefined") {
-      if (document.activeElement === input) {
+      if (readFocusedField(
+        {
+          key: "dom:input.focused",
+          title: "Whether a tracked input field has focus",
+          accessNote: "document.activeElement compared with the passed input elements",
+          group: "Input interaction",
+          origin: "observe-external",
+          fields: [
+            {
+              path: "focused",
+              label: "Whether the field is selected",
+              exposure: "enum",
+              transform: { values: [true, false] }
+            }
+          ]
+        },
+        [input]
+      )) {
         this.handleFocus();
       }
     }
@@ -109,16 +209,9 @@ var LowEventInputTracker = class {
     }
   }
   detach() {
-    const input = this.inputField;
-    input.removeEventListener("focus", this.boundHandlers.focus);
-    input.removeEventListener("blur", this.boundHandlers.blur);
-    input.removeEventListener("pointerdown", this.boundHandlers.pointerdown);
-    input.removeEventListener("pointerup", this.boundHandlers.pointerup);
-    input.removeEventListener("click", this.boundHandlers.click);
-    input.removeEventListener("input", this.boundHandlers.input);
-    input.removeEventListener("keyup", this.boundHandlers.keyup);
+    this.removeFieldListeners?.();
     if (typeof window !== "undefined") {
-      window.removeEventListener("pagehide", this.boundHandlers.pageHide);
+      this.removePageHide?.();
     }
   }
   pushLow = (low) => {
@@ -129,9 +222,14 @@ var LowEventInputTracker = class {
       if (typeof __CBO_DATA_PMD__ === "boolean" ? __CBO_DATA_PMD__ : this.sink.passwordManagerDomScan?.() !== false) {
         const matches = readPasswordManagerDomSignals({
           key: "dom:password-managers.dom-signals",
+          title: "Password manager traces in the page",
+          accessNote: "DOM markers that password manager extensions insert (attributes, elements, styles)",
+          group: "Password manager detection",
+          origin: "observe-external",
           fields: [
             {
               path: "signals[]",
+              label: "Password manager traces found",
               exposure: "enum",
               transform: { values: ["pa-1", "pa-2", "pa-3", "pa-4", "pa-5", "pa-6"] }
             }
@@ -179,19 +277,9 @@ var LowEventInputTracker = class {
     this.pasteObserver.flush();
     this.enqueueNonInputEvent("blur");
   }
-  handleInput(event) {
+  handleInput(event, composing) {
     if (this.pasteObserver.handlesInput(event)) return;
-    this.changes.record(
-      fieldContentLength(this.inputField),
-      Date.now(),
-      event.isComposing || event.inputType === "insertCompositionText"
-    );
-  }
-  handleKeyUp(event) {
-    if (event.key !== "Escape") {
-      return;
-    }
-    this.enqueueNonInputEvent("keyup-escape");
+    this.changes.record(fieldContentLength(this.inputField), Date.now(), composing);
   }
   flushForTeardown() {
     this.pasteObserver.flush();
@@ -207,15 +295,6 @@ var LowEventInputTracker = class {
       }
     };
   }
-  wrapKeyboardHandler(name, fn) {
-    return (event) => {
-      try {
-        fn(event);
-      } catch (error) {
-        this.logger.error(`Failed to handle low event "${name}"`, error);
-      }
-    };
-  }
 };
 export {
   LowEventInputTracker,

package/dist/analysis/low-events/shared-window-observer.mjs

@@ -2,64 +2,124 @@
 import { reserveCaptureSeq } from "./capture-sequence.mjs";
 import { v7 as uuidv7 } from "uuid";
 import { createViewportBatcher } from "./viewport-batcher.mjs";
+import { observeWindowLowEvents, readActiveFocus, readFocusedChain } from "../readers/window-events.mjs";
 var documentPageId;
 var getCapturePageId = () => documentPageId ??= uuidv7();
-var focusedElements = () => {
-  const chain = [];
-  for (let active = document.activeElement; active; active = active.shadowRoot?.activeElement ?? null) {
-    chain.push(active);
-  }
-  return chain;
-};
 var SharedWindowObserver = class {
   constructor(logger, enqueue, flushKeepalive) {
     this.logger = logger;
     this.enqueue = enqueue;
     this.flushKeepalive = flushKeepalive;
     if (typeof window === "undefined" || typeof document === "undefined") return;
-    this.listen(window, "blur", () => {
-      this.flushInputs();
-      this.bracket = this.context();
-      this.emit({ lowType: "window-blur", ts: Date.now() }, this.bracket);
-    });
-    this.listen(window, "focus", () => {
-      this.flushInputs();
-      this.emit({ lowType: "window-focus", ts: Date.now() }, this.bracket ?? this.context());
-      this.bracket = void 0;
-    });
-    this.listen(document, "visibilitychange", () => {
-      this.flushInputs();
-      this.emit({
-        lowType: `document-visibilitychange-${document.visibilityState === "hidden" ? "hidden" : "visible"}`,
-        ts: Date.now()
-      });
-    });
-    this.listen(document, "focusout", (event) => {
-      const registration = this.findInput(event.target);
-      this.lastBlur = registration && !event.relatedTarget && Date.now() - this.unrelatedPointerAt > 250 ? { registration, ts: Date.now() } : void 0;
-    });
-    this.listen(document, "focusin", (event) => {
-      this.lastBlur = void 0;
-      const field = this.inputFocusListeners.size > 0 && event.composedPath().find((target) => this.findInput(target));
-      if (field) this.notifyInputFocus(field);
-    });
-    this.listen(document, "pointerdown", (event) => {
-      if (!this.findInput(event.target)) {
-        this.lastBlur = void 0;
-        this.unrelatedPointerAt = Date.now();
-      } else this.unrelatedPointerAt = -Infinity;
-    });
-    if (window.visualViewport) {
-      this.listen(window.visualViewport, "resize", () => this.extendViewport("resize"));
-      this.listen(window.visualViewport, "scroll", () => this.extendViewport("scroll"));
-    }
-    this.listen(window, "pagehide", () => {
-      this.flushInputs();
-      this.resize.flush();
-      this.scroll.flush();
-      this.flushKeepalive();
-    });
-    this.observeNavigation();
+    this.removers = observeWindowLowEvents(
+      {
+        key: "page:window.low-events",
+        title: "Window focus, visibility, size and back navigation",
+        accessNote: "window blur/focus, document visibilitychange/focusin/focusout/pointerdown, visualViewport resize/scroll, pagehide, Navigation API currententrychange (traverse)",
+        group: "Window interaction",
+        origin: "observe-external",
+        fields: [
+          { path: "event.blur", label: "Window left", exposure: "presence" },
+          { path: "event.focus", label: "Window selected", exposure: "presence" },
+          {
+            path: "event.visibilitychange",
+            label: "Page hidden or shown again",
+            exposure: "enum",
+            transform: { values: ["hidden", "visible"] }
+          },
+          {
+            path: "event.focusout",
+            label: "Whether a tracked field lost focus",
+            exposure: "computed",
+            transform: { note: "only whether a handed-over input lost focus to nothing" }
+          },
+          {
+            path: "event.focusin",
+            label: "Which tracked field gained focus",
+            exposure: "computed",
+            transform: { note: "only which handed-over input gained focus" }
+          },
+          {
+            path: "event.pointerdown",
+            label: "Whether a tracked field was pressed",
+            exposure: "computed",
+            transform: { note: "only whether the pointer went to a handed-over input" }
+          },
+          {
+            path: "event.visualviewport.resize",
+            label: "Duration of zooming or resizing",
+            exposure: "size",
+            transform: { note: "batched duration only" }
+          },
+          {
+            path: "event.visualviewport.scroll",
+            label: "Duration of scrolling",
+            exposure: "size",
+            transform: { note: "batched duration only" }
+          },
+          { path: "event.pagehide", label: "Leaving the page", exposure: "presence" },
+          {
+            path: "event.navigation.back",
+            label: "Going back within the page",
+            exposure: "enum",
+            transform: { values: [true, false], note: "committed same-document traverse to an earlier entry" }
+          }
+        ]
+      },
+      {
+        blur: () => {
+          this.flushInputs();
+          this.bracket = this.context();
+          this.emit({ lowType: "window-blur", ts: Date.now() }, this.bracket);
+        },
+        focus: () => {
+          this.flushInputs();
+          this.emit({ lowType: "window-focus", ts: Date.now() }, this.bracket ?? this.context());
+          this.bracket = void 0;
+        },
+        visibilityChange: (hidden) => {
+          this.flushInputs();
+          this.emit({
+            lowType: `document-visibilitychange-${hidden ? "hidden" : "visible"}`,
+            ts: Date.now()
+          });
+        },
+        focusOut: (target, hasRelatedTarget) => {
+          const registration = this.findInput(target);
+          this.lastBlur = registration && !hasRelatedTarget && Date.now() - this.unrelatedPointerAt > 250 ? { registration, ts: Date.now() } : void 0;
+        },
+        focusIn: (composedPath) => {
+          this.lastBlur = void 0;
+          const field = this.inputFocusListeners.size > 0 && composedPath().find((target) => this.findInput(target));
+          if (field) this.notifyInputFocus(field);
+        },
+        pointerDown: (target) => {
+          if (!this.findInput(target)) {
+            this.lastBlur = void 0;
+            this.unrelatedPointerAt = Date.now();
+          } else this.unrelatedPointerAt = -Infinity;
+        },
+        viewportResize: () => this.extendViewport("resize"),
+        viewportScroll: () => this.extendViewport("scroll"),
+        pageHide: () => {
+          this.flushInputs();
+          this.resize.flush();
+          this.scroll.flush();
+          this.flushKeepalive();
+        },
+        navigateBack: () => {
+          this.flushInputs();
+          this.emit({ lowType: "window-navigate-back", ts: Date.now() });
+        }
+      },
+      (name, run) => {
+        try {
+          run();
+        } catch (error) {
+          this.logger.error(`Failed to observe window ${name}`, error);
+        }
+      }
+    );
   }
   inputs = /* @__PURE__ */ new Set();
   inputFocusListeners = /* @__PURE__ */ new Set();
@@ -86,7 +146,21 @@ var SharedWindowObserver = class {
     const registration = { fields, context, flush };
     this.inputs.add(registration);
     if (this.inputFocusListeners.size > 0 && typeof document !== "undefined") {
-      const focused = focusedElements();
+      const focused = readFocusedChain({
+        key: "dom:window.focused-element",
+        title: "Which tracked input field has focus",
+        accessNote: "document.activeElement and the focus event path, matched against the passed input elements",
+        group: "Window interaction",
+        origin: "observe-external",
+        fields: [
+          {
+            path: "activeElement",
+            label: "Which tracked field is selected",
+            exposure: "computed",
+            transform: { note: "identity compared against handed-over inputs only" }
+          }
+        ]
+      });
       const field = fields.find((candidate) => focused.includes(candidate));
       if (field) this.notifyInputFocus(field);
     }
@@ -138,10 +212,31 @@ var SharedWindowObserver = class {
     const active = [...this.ceremonies].filter((item) => !item.settled);
     if (active.length === 1) return active[0].context;
     if (active.length > 1) return void 0;
-    const input = this.findInput(document.activeElement);
+    const focus = readActiveFocus({
+      key: "dom:window.focused-element",
+      title: "Which tracked input field has focus",
+      accessNote: "document.activeElement and the focus event path, matched against the passed input elements",
+      group: "Window interaction",
+      origin: "observe-external",
+      fields: [
+        {
+          path: "activeElement",
+          label: "Which tracked field is selected",
+          exposure: "computed",
+          transform: { note: "identity compared against handed-over inputs only" }
+        },
+        {
+          path: "activeElement.idle",
+          label: "Whether nothing is selected",
+          exposure: "enum",
+          transform: { values: [true, false], note: "nothing focused (body or none)" }
+        }
+      ]
+    });
+    const input = this.findInput(focus.active);
     if (input) return input.context();
     const previous = this.lastBlur;
-    if (previous && Date.now() - previous.ts <= 250 && (document.activeElement === document.body || !document.activeElement)) {
+    if (previous && Date.now() - previous.ts <= 250 && focus.idle) {
       return previous.registration.context();
     }
     return void 0;
@@ -174,17 +269,6 @@ var SharedWindowObserver = class {
       sessionId
     );
   }
-  listen(target, name, handler) {
-    const safe = (event) => {
-      try {
-        handler(event);
-      } catch (error) {
-        this.logger.error(`Failed to observe window ${name}`, error);
-      }
-    };
-    target.addEventListener(name, safe);
-    this.removers.push(() => target.removeEventListener(name, safe));
-  }
   extendViewport(kind) {
     const context = this.context();
     const previous = this.viewportContext[kind];
@@ -193,19 +277,6 @@ var SharedWindowObserver = class {
     this.viewportContext[kind] = context;
     this[kind].extend();
   }
-  observeNavigation() {
-    const navigation = window.navigation;
-    if (!navigation) return;
-    this.listen(navigation, "currententrychange", (event) => {
-      const change = event;
-      const from = change.from?.index;
-      const to = navigation.currentEntry?.index;
-      if (change.navigationType === "traverse" && typeof from === "number" && typeof to === "number" && from >= 0 && to >= 0 && to < from) {
-        this.flushInputs();
-        this.emit({ lowType: "window-navigate-back", ts: Date.now() });
-      }
-    });
-  }
   destroy() {
     if (this.destroyed) return;
     this.flushInputs();

package/dist/analysis/low-events/viewport-batcher.mjs

@@ -7,7 +7,7 @@ var createViewportBatcher = (pushLow, eventType, reserveCaptureSeq) => {
   let timeout = null;
   const flush = () => {
     if (timeout !== null) {
-      window.clearTimeout(timeout);
+      clearTimeout(timeout);
       timeout = null;
     }
     const ts = startTimestamp;
@@ -31,9 +31,9 @@ var createViewportBatcher = (pushLow, eventType, reserveCaptureSeq) => {
       captureSeq = sequence;
     }
     if (timeout !== null) {
-      window.clearTimeout(timeout);
+      clearTimeout(timeout);
     }
-    timeout = window.setTimeout(flush, VIEWPORT_BATCH_TIMEOUT_MS);
+    timeout = setTimeout(flush, VIEWPORT_BATCH_TIMEOUT_MS);
   };
   return { extend, flush };
 };