@scalebun/web 1.0.0

package/dist/features/exit-intent/engine.js

@@ -0,0 +1,227 @@
+import { scrollDepthPct } from '../../core/scrollDepth';
+export const EXIT_WEIGHTS = {
+    top_exit: 0.8, // pointer leaves the document at the top edge (toward the tab bar/URL)
+    scroll_reversal: 0.5, // fast scroll-up after having scrolled down (works on touch)
+};
+export const EXIT_THRESHOLD = 0.5;
+const COOLDOWN_MS = 30000;
+const MAX_FIRES = 3;
+/**
+ * How close to the top edge the pointer must be when it leaves the document.
+ *
+ * WAS 12, which is a sampling bug dressed as a threshold. `mouseout` reports the pointer's LAST SAMPLED
+ * position, and pointer samples arrive per frame: someone flicking toward the tab bar at ~1500 px/s
+ * covers ~25px between samples, so the final coordinate before the pointer leaves is routinely 20–40px
+ * down — outside a 12px band. The faster and more deliberate the exit gesture, the more likely it was
+ * to be missed, which is precisely backwards for a detector whose subject IS a deliberate fast gesture.
+ *
+ * 40 is a frame of travel plus margin. Widening this cannot cause false positives on its own: the
+ * `relatedTarget === null` test already establishes that the pointer left the DOCUMENT, and this only
+ * decides whether it left near enough to the top to mean "heading for the browser chrome".
+ */
+const TOP_EDGE_PX = 40;
+export const REVERSAL_DEFAULTS = {
+    windowMs: 120,
+    minDistancePx: 80,
+    minVelocityPxMs: 0.7,
+    minDepthPct: 25,
+    sustainSamples: 3,
+    topEdgePx: TOP_EDGE_PX,
+};
+/** Pointer left the document (no relatedTarget) near the top edge → heading for the chrome. */
+export function isTopExit(relatedTargetNull, clientY, topEdge = TOP_EDGE_PX) {
+    return relatedTargetNull && clientY <= topEdge;
+}
+/**
+ * Upward distance + velocity across the trailing `windowMs` of samples.
+ *
+ * THIS REPLACES a two-sample delta (`lastY - y >= 240`), which was a velocity threshold written as a
+ * per-event delta. Browsers fire `scroll` per animation frame at frame-sized increments, so that delta
+ * measured ~16ms of travel rather than the gesture — whether it tripped depended on how many scroll
+ * events the compositor happened to emit. Measured live: it never did, on any app, ever.
+ *
+ * Returns null when there is no measurable interval: fewer than two samples, or two samples in the same
+ * millisecond (dividing by that yields Infinity, which would fire on noise).
+ */
+export function reversalMetrics(buf, windowMs) {
+    const cur = buf[buf.length - 1];
+    // `noUncheckedIndexedAccess` — an index read is `T | undefined`, and a length check does not narrow it.
+    if (buf.length < 2 || !cur)
+        return null;
+    // The oldest sample still inside the window. Scanned rather than assumed, so this stays correct
+    // regardless of the caller's pruning discipline.
+    let oldest = cur;
+    for (const s of buf) {
+        if (cur.t - s.t <= windowMs) {
+            oldest = s;
+            break;
+        }
+    }
+    const dt = cur.t - oldest.t;
+    if (dt <= 0)
+        return null;
+    const distancePx = oldest.y - cur.y; // positive = upward
+    return { distancePx, velocityPxMs: distancePx / dt };
+}
+/**
+ * Stateful reversal detector — DOM-free on purpose, so the decision logic is testable by pushing a
+ * synthetic scroll trace rather than by simulating a browser.
+ *
+ * Hysteresis (§3): a single qualifying sample is not intent. Mobile scrolling contains constant small
+ * reversals — finger repositioning, rubber-band at the ends, momentum settling, sticky headers shifting
+ * perceived offset. Requiring N consecutive qualifying samples costs ~50ms at 60fps and removes them.
+ *
+ * Consecutive SAMPLES rather than a wall-clock duration, deliberately: a duration timer can be satisfied
+ * by a single sample that happens to straddle the interval — the same class of mistake as the bug this
+ * replaces.
+ */
+export class ScrollReversalDetector {
+    constructor(tuning = REVERSAL_DEFAULTS) {
+        this.tuning = tuning;
+        this.buf = [];
+        this.sustained = 0;
+        this.maxY = 0;
+        /**
+         * Already reported the gesture currently in progress.
+         *
+         * Without this, a 600ms flick reports on frame 3 and then again every 3rd frame after it — measured:
+         * 11 hits for one gesture. The 30s cooldown would swallow them downstream, which is exactly the
+         * problem: over-detection would be invisible during tuning. Cleared when a sample stops qualifying,
+         * i.e. when the gesture ends.
+         */
+        this.latched = false;
+    }
+    /** Deepest scroll reached — the "did they engage before leaving" input. */
+    get maxScrollY() {
+        return this.maxY;
+    }
+    /** Consecutive qualifying samples so far. Exposed for tests + diagnostics, not for control flow. */
+    get sustainedSamples() {
+        return this.sustained;
+    }
+    /**
+     * Feed one scroll sample. Returns metrics ONLY on the sample that completes a qualifying gesture.
+     *
+     * `depthPct` and `viewportH` are passed in rather than read from the DOM so this stays pure.
+     */
+    push(y, t, depthPct, viewportH) {
+        if (y > this.maxY)
+            this.maxY = y;
+        this.buf.push({ y, t });
+        // Keep exactly one sample older than the window, so a full-width measurement is always available.
+        // (`buf[1]!` — length > 2 guarantees it; `noUncheckedIndexedAccess` cannot see that.)
+        while (this.buf.length > 2 && t - this.buf[1].t > this.tuning.windowMs)
+            this.buf.shift();
+        const m = reversalMetrics(this.buf, this.tuning.windowMs);
+        const qualifies = m !== null &&
+            m.distancePx >= this.tuning.minDistancePx &&
+            m.velocityPxMs >= this.tuning.minVelocityPxMs;
+        if (!qualifies) {
+            // Gesture over (or never started) — reset the streak AND release the latch.
+            this.sustained = 0;
+            this.latched = false;
+            return null;
+        }
+        this.sustained += 1;
+        if (this.latched)
+            return null; // one gesture = one detection
+        if (this.sustained < this.tuning.sustainSamples)
+            return null;
+        /**
+         * Engagement floor — BOTH conditions, not either.
+         *
+         * "Past the fold" is the original test and is right on long pages. The percentage is right on short
+         * ones. Neither alone works: one viewport is ~5% of a 20-screen article but 50% of a 2-screen page,
+         * so using the percentage ALONE would make short pages EASIER to trigger than they are today — the
+         * wrong direction for a detector that currently over-fires nothing and under-fires everything.
+         */
+        if (this.maxY <= viewportH || depthPct < this.tuning.minDepthPct)
+            return null;
+        // Latch only on an ACTUAL report — latching on a rejected depth check would suppress a later,
+        // legitimate hit within the same gesture.
+        this.latched = true;
+        return m;
+    }
+}
+/** Cooldown + per-session cap gate — pure so it's fixture-tested. */
+export function canFire(now, lastFire, fires, opts = {}) {
+    if (fires >= (opts.maxFires ?? MAX_FIRES))
+        return false;
+    if (lastFire > 0 && now - lastFire < (opts.cooldownMs ?? COOLDOWN_MS))
+        return false;
+    return true;
+}
+const now = () => (typeof performance !== 'undefined' && performance.now ? performance.now() : Date.now());
+export function startExitIntent(ctx, tuning) {
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+        return { stop: () => { }, fires: () => 0 };
+    }
+    let fires = 0;
+    let lastFire = 0;
+    const tune = { ...REVERSAL_DEFAULTS, ...(tuning ?? {}) };
+    const detector = new ScrollReversalDetector(tune);
+    const depthPct = () => {
+        try {
+            // Shared definition — see core/scrollDepth. Matters here too: the reversal detector gates on
+            // `depthPct >= minDepthPct`, so the old under-reporting suppressed legitimate exit intents.
+            return scrollDepthPct(window.scrollY || 0, document.documentElement.scrollHeight, window.innerHeight || 0);
+        }
+        catch {
+            return 0;
+        }
+    };
+    const fire = (trigger, extra) => {
+        const confidence = EXIT_WEIGHTS[trigger];
+        if (confidence === undefined || confidence < EXIT_THRESHOLD)
+            return;
+        if (!canFire(now(), lastFire, fires))
+            return;
+        fires++;
+        lastFire = now();
+        const props = { confidence, trigger, path: location.pathname, scroll_depth_pct: depthPct(), ...extra };
+        /**
+         * TWO lanes, deliberately, and this used to be one.
+         *
+         * `trackEvent` puts the event on the SESSION lane, where it lands beside the replay timeline — that
+         * is what makes "watch the moment they tried to leave" work, and it is why the call was written this
+         * way. But the session lane is not the analytics store: every aggregate read (`$pageview`,
+         * `$deadclick`, `$rageclick`, `$web_vital`, `$exception`) comes off the ANALYTICS lane, which is fed
+         * by AnalyticsFeature. So a signal that only ever went to the session lane was captured correctly and
+         * was simultaneously invisible to every dashboard that aggregates — measured: 125 real detections
+         * recorded over 8 days while the exit-intent page read zero.
+         *
+         * The signal carries `props` so AnalyticsFeature can promote it, exactly as ErrorsFeature's detail is
+         * promoted to `$exception`. Sending detail is also what the engage / #21 exit-offer subscribers need
+         * to decide anything — previously they were told only that an exit happened, not where or how.
+         */
+        ctx.trackEvent('$exit_intent', props);
+        ctx.signal('exit_intent', props); // → AnalyticsFeature promotes to the analytics lane; arms engage / #21
+    };
+    const onMouseOut = (e) => {
+        // `exit_y` is reported so the band can be retuned from measured exits rather than guessed a third
+        // time — the same reason the reversal trigger carries its velocity and distance.
+        if (isTopExit(!e.relatedTarget, e.clientY, tune.topEdgePx)) {
+            fire('top_exit', { x: e.clientX | 0, y: e.clientY | 0, exit_y: Math.round(e.clientY) });
+        }
+    };
+    const onScroll = () => {
+        const hit = detector.push(window.scrollY || 0, now(), depthPct(), window.innerHeight || 0);
+        if (!hit)
+            return;
+        // Emitted so the thresholds above can be retuned from real distributions rather than guessed twice.
+        fire('scroll_reversal', {
+            velocity_px_ms: Math.round(hit.velocityPxMs * 1000) / 1000,
+            distance_px: Math.round(hit.distancePx),
+        });
+    };
+    document.addEventListener('mouseout', onMouseOut);
+    window.addEventListener('scroll', onScroll, { passive: true });
+    return {
+        fires: () => fires,
+        stop: () => {
+            document.removeEventListener('mouseout', onMouseOut);
+            window.removeEventListener('scroll', onScroll);
+        },
+    };
+}
+//# sourceMappingURL=engine.js.map

package/dist/features/exit-intent/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../../src/features/exit-intent/engine.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,MAAM,CAAC,MAAM,YAAY,GAA2B;IAClD,QAAQ,EAAE,GAAG,EAAE,uEAAuE;IACtF,eAAe,EAAE,GAAG,EAAE,6DAA6D;CACpF,CAAC;AACF,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC;AAClC,MAAM,WAAW,GAAG,KAAM,CAAC;AAC3B,MAAM,SAAS,GAAG,CAAC,CAAC;AAEpB;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,GAAG,EAAE,CAAC;AAiCvB,MAAM,CAAC,MAAM,iBAAiB,GAAmB;IAC/C,QAAQ,EAAE,GAAG;IACb,aAAa,EAAE,EAAE;IACjB,eAAe,EAAE,GAAG;IACpB,WAAW,EAAE,EAAE;IACf,cAAc,EAAE,CAAC;IACjB,SAAS,EAAE,WAAW;CACvB,CAAC;AAaF,+FAA+F;AAC/F,MAAM,UAAU,SAAS,CAAC,iBAA0B,EAAE,OAAe,EAAE,OAAO,GAAG,WAAW;IAC1F,OAAO,iBAAiB,IAAI,OAAO,IAAI,OAAO,CAAC;AACjD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,GAAmB,EAAE,QAAgB;IACnE,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAChC,wGAAwG;IACxG,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACxC,gGAAgG;IAChG,iDAAiD;IACjD,IAAI,MAAM,GAAiB,GAAG,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;QACpB,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,QAAQ,EAAE,CAAC;YAC5B,MAAM,GAAG,CAAC,CAAC;YACX,MAAM;QACR,CAAC;IACH,CAAC;IACD,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;IAC5B,IAAI,EAAE,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACzB,MAAM,UAAU,GAAG,MAAM,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,oBAAoB;IACzD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,GAAG,EAAE,EAAE,CAAC;AACvD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,sBAAsB;IAcjC,YAA6B,SAAyB,iBAAiB;QAA1C,WAAM,GAAN,MAAM,CAAoC;QAb/D,QAAG,GAAmB,EAAE,CAAC;QACzB,cAAS,GAAG,CAAC,CAAC;QACd,SAAI,GAAG,CAAC,CAAC;QACjB;;;;;;;WAOG;QACK,YAAO,GAAG,KAAK,CAAC;IAEkD,CAAC;IAE3E,2EAA2E;IAC3E,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED,oGAAoG;IACpG,IAAI,gBAAgB;QAClB,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED;;;;OAIG;IACH,IAAI,CAAC,CAAS,EAAE,CAAS,EAAE,QAAgB,EAAE,SAAiB;QAC5D,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI;YAAE,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACxB,kGAAkG;QAClG,sFAAsF;QACtF,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAE,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ;YAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC;QAE1F,MAAM,CAAC,GAAG,eAAe,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC1D,MAAM,SAAS,GACb,CAAC,KAAK,IAAI;YACV,CAAC,CAAC,UAAU,IAAI,IAAI,CAAC,MAAM,CAAC,aAAa;YACzC,CAAC,CAAC,YAAY,IAAI,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC;QAEhD,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,4EAA4E;YAC5E,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;YACnB,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;YACrB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC;QACpB,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC,CAAC,8BAA8B;QAC7D,IAAI,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc;YAAE,OAAO,IAAI,CAAC;QAE7D;;;;;;;WAOG;QACH,IAAI,IAAI,CAAC,IAAI,IAAI,SAAS,IAAI,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW;YAAE,OAAO,IAAI,CAAC;QAE9E,8FAA8F;QAC9F,0CAA0C;QAC1C,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,OAAO,CAAC,CAAC;IACX,CAAC;CACF;AAED,qEAAqE;AACrE,MAAM,UAAU,OAAO,CAAC,GAAW,EAAE,QAAgB,EAAE,KAAa,EAAE,OAAmD,EAAE;IACzH,IAAI,KAAK,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,SAAS,CAAC;QAAE,OAAO,KAAK,CAAC;IACxD,IAAI,QAAQ,GAAG,CAAC,IAAI,GAAG,GAAG,QAAQ,GAAG,CAAC,IAAI,CAAC,UAAU,IAAI,WAAW,CAAC;QAAE,OAAO,KAAK,CAAC;IACpF,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,GAAG,GAAG,GAAW,EAAE,CAAC,CAAC,OAAO,WAAW,KAAK,WAAW,IAAI,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;AAOnH,MAAM,UAAU,eAAe,CAAC,GAAmB,EAAE,MAAgC;IACnF,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE,CAAC;QACrE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC;IAC5C,CAAC;IAED,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,MAAM,IAAI,GAAmB,EAAE,GAAG,iBAAiB,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC;IACzE,MAAM,QAAQ,GAAG,IAAI,sBAAsB,CAAC,IAAI,CAAC,CAAC;IAElD,MAAM,QAAQ,GAAG,GAAW,EAAE;QAC5B,IAAI,CAAC;YACH,6FAA6F;YAC7F,4FAA4F;YAC5F,OAAO,cAAc,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,EAAE,QAAQ,CAAC,eAAe,CAAC,YAAY,EAAE,MAAM,CAAC,WAAW,IAAI,CAAC,CAAC,CAAC;QAC7G,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,CAAC,CAAC;QACX,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,IAAI,GAAG,CAAC,OAAkC,EAAE,KAA8B,EAAQ,EAAE;QACxF,MAAM,UAAU,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;QACzC,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,GAAG,cAAc;YAAE,OAAO;QACpE,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC;YAAE,OAAO;QAC7C,KAAK,EAAE,CAAC;QACR,QAAQ,GAAG,GAAG,EAAE,CAAC;QACjB,MAAM,KAAK,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,EAAE,QAAQ,EAAE,EAAE,GAAG,KAAK,EAAE,CAAC;QACvG;;;;;;;;;;;;;;WAcG;QACH,GAAG,CAAC,UAAU,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;QACtC,GAAG,CAAC,MAAM,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC,CAAC,uEAAuE;IAC3G,CAAC,CAAC;IAEF,MAAM,UAAU,GAAG,CAAC,CAAa,EAAQ,EAAE;QACzC,kGAAkG;QAClG,iFAAiF;QACjF,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YAC3D,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,OAAO,GAAG,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC1F,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,QAAQ,GAAG,GAAS,EAAE;QAC1B,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,EAAE,MAAM,CAAC,WAAW,IAAI,CAAC,CAAC,CAAC;QAC3F,IAAI,CAAC,GAAG;YAAE,OAAO;QACjB,oGAAoG;QACpG,IAAI,CAAC,iBAAiB,EAAE;YACtB,cAAc,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,IAAI;YAC1D,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC;SACxC,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,QAAQ,CAAC,gBAAgB,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;IAClD,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IAE/D,OAAO;QACL,KAAK,EAAE,GAAG,EAAE,CAAC,KAAK;QAClB,IAAI,EAAE,GAAS,EAAE;YACf,QAAQ,CAAC,mBAAmB,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;YACrD,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QACjD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/features/forms/index.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Form analytics (F-FORM) — which field costs you money.
+ *
+ * Answers the CRO staple questions — completion rate, time per field, error fields, and above all
+ * *where people give up* — by watching ordinary DOM events and emitting a handful of analytics events
+ * onto the EXISTING lane. No parallel pipeline, no new backend table: `$form_*` events ride
+ * `/batch` → `events` exactly like `$submit` already does, so replay correlation, the Event Debugger
+ * and Explore work on them from day one.
+ *
+ * PRIVACY IS THE HARD RULE: **field VALUES are never read.** We record metadata only — a field KEY
+ * (name/id/type), how long it was focused, whether it changed, whether it errored. Password / hidden /
+ * card / one-time-code inputs are skipped entirely, as is any subtree under
+ * `[data-scalebun-no-capture]` (the same opt-out autocapture honours).
+ *
+ * BUNDLE: this module is a LAZY chunk, dynamically imported from the already-lazy autocapture chunk —
+ * so it costs the eager core ZERO bytes. (The 30 KB gate has ~470 B of headroom; nothing here may
+ * touch it.)
+ *
+ * VOLUME: terminal-summary model — `$form_start` plus ONE terminal event (`$submit` enriched, or
+ * `$form_abandon`) carrying a per-field summary. ~2–3 events per form, not one per field.
+ */
+export interface FormEvent {
+    name: string;
+    props: Record<string, unknown>;
+}
+export interface FormHandlers {
+    onEvent: (e: FormEvent) => void;
+}
+/** True for inputs whose mere presence in an event would be a privacy problem. Exported for tests. */
+export declare function isSensitiveField(el: Element): boolean;
+/** A field we should measure: a real data control, not sensitive, not a button. Exported for tests. */
+export declare function isTrackableField(el: Element | null): el is HTMLElement;
+/**
+ * A stable, PII-safe key for a field: `name` → `id` → `type[index]`.
+ * NEVER derived from a value or placeholder — those carry user data. Exported for tests.
+ */
+export declare function fieldKeyOf(el: Element, form: HTMLFormElement): string;
+/**
+ * The field's VISIBLE name, for display only — never its identity.
+ *
+ * `fieldKeyOf` falls back to `type[index]` when a control has neither `name` nor `id`, which is
+ * correct as an identifier and useless to read: a dashboard row saying `tel[1]` cannot tell anyone
+ * which box on the page that is. This reads the field's accessible name instead, so the same row can
+ * say "Mobile number" while still being keyed on `tel[1]`.
+ *
+ * WHY THESE SOURCES AND NOT `placeholder`. `aria-label`, `<label>` and `aria-labelledby` are the
+ * platform's own definition of what a control is called — authored markup, the same class of data as
+ * `name` and `id`. `placeholder` is deliberately excluded here because `fieldKeyOf` already excludes
+ * it on the grounds that it can carry user data, and re-litigating that call as a side effect of a
+ * display change would be the wrong place to do it.
+ *
+ * Scrubbed and truncated regardless: a site CAN render user content into a label, and this is the one
+ * form string that reaches our servers, so it goes through the same redaction as any other free text.
+ */
+export declare function fieldLabelOf(el: Element): string | undefined;
+/**
+ * A form's identity: `id` → `name` → a STRUCTURAL hash (tag + action path + sorted field names).
+ * The hash keeps dashboards stable for forms without an id/name, and never uses user data.
+ * Exported for tests.
+ */
+export declare function formIdOf(form: HTMLFormElement): string;
+/**
+ * Author-declared multi-step marker: `data-scalebun-step` on the form (or an ancestor). Read LIVE per
+ * event so a wizard that mutates the attribute as the user advances yields step-level drop-off — you
+ * see *which step* people give up on, not just the form. Author-provided ⇒ non-PII by construction.
+ * Exported for tests.
+ */
+export declare function stepOf(form: HTMLFormElement): string | undefined;
+/**
+ * Validation-heatmap anchor for an errored field: its viewport-space box + opt-in component name, in
+ * the SAME shape the journey tracker (H7) stamps on clicks — `{ ex, ey, ew, eh, component }`. That
+ * lets a validation heatmap re-project error markers onto the real-DOM backdrop with the existing
+ * anchoring machinery, no new plumbing. Integers only — never text or values. `undefined` when the
+ * field is detached/zero-sized so we don't emit a meaningless (0,0,0,0). Exported for tests.
+ */
+export declare function anchorOf(el: Element): Record<string, number | string> | undefined;
+export interface FormAnalytics {
+    /** Called by autocapture on submit: marks the form complete and returns props to ENRICH `$submit`. */
+    onSubmit: (form: HTMLFormElement) => Record<string, unknown>;
+    stop: () => void;
+}
+export declare function installFormAnalytics(h: FormHandlers): FormAnalytics;
+//# sourceMappingURL=index.d.ts.map

package/dist/features/forms/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/features/forms/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AACD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,CAAC,CAAC,EAAE,SAAS,KAAK,IAAI,CAAC;CACjC;AAYD,sGAAsG;AACtG,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAKrD;AAED,uGAAuG;AACvG,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,GAAG,EAAE,IAAI,WAAW,CAKtE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,CAYrE;AAKD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAyB5D;AASD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAoBtD;AAKD;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAOhE;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,SAAS,CAWjF;AAmCD,MAAM,WAAW,aAAa;IAC5B,sGAAsG;IACtG,QAAQ,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7D,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,YAAY,GAAG,aAAa,CAsLnE"}