@active-reach/web-sdk 1.10.0 → 1.11.1

package/dist/react.js

@@ -1,5 +1,5 @@
 import React, { createContext, useState, useEffect, useContext } from "react";
-import { A as Aegis } from "./analytics-Cc4-QQBf.mjs";
+import { A as Aegis } from "./analytics-6PR9ERDS.mjs";
 const AegisContext = createContext({
   aegis: null,
   isReady: false

package/dist/runtime/AegisMessageRuntime.d.ts

@@ -46,7 +46,6 @@ export declare class AegisMessageRuntime {
     readonly inApp: AegisInAppManager;
     readonly widgets: AegisWidgetManager;
     private initialized;
-    private ownedTriggerEngine;
     constructor(config: AegisMessageRuntimeConfig);
     /**
      * Boots both managers in parallel. Safe to call multiple times — the

package/dist/runtime/AegisMessageRuntime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AegisMessageRuntime.d.ts","sourceRoot":"","sources":["../../src/runtime/AegisMessageRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AACxF,OAAO,EAAE,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGxE,MAAM,WAAW,yBAA0B,SAAQ,gBAAgB;IACjE;;kEAE8D;IAC9D,aAAa,CAAC,EAAE,iBAAiB,CAAC,eAAe,CAAC,CAAC;IACnD;;sDAEkD;IAClD,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;0EACsE;IACtE,cAAc,CAAC,EAAE,iBAAiB,CAAC,gBAAgB,CAAC,CAAC;CACtD;AAED;;;;GAIG;AACH,qBAAa,mBAAmB;IAC9B,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,kBAAkB,CAA8B;gBAE5C,MAAM,EAAE,yBAAyB;IAoC7C;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IASjC;;;;;;;OAOG;IACG,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKvD;;;;;;OAMG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,IAAI;IAI/E;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAIxC;;;;;OAKG;IACH,OAAO,IAAI,IAAI;IAOf;;;;;OAKG;IACH,YAAY,IAAI,aAAa,EAAE;CAMhC"}
+{"version":3,"file":"AegisMessageRuntime.d.ts","sourceRoot":"","sources":["../../src/runtime/AegisMessageRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AACxF,OAAO,EAAE,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGxE,MAAM,WAAW,yBAA0B,SAAQ,gBAAgB;IACjE;;kEAE8D;IAC9D,aAAa,CAAC,EAAE,iBAAiB,CAAC,eAAe,CAAC,CAAC;IACnD;;sDAEkD;IAClD,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;0EACsE;IACtE,cAAc,CAAC,EAAE,iBAAiB,CAAC,gBAAgB,CAAC,CAAC;CACtD;AAED;;;;GAIG;AACH,qBAAa,mBAAmB;IAC9B,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,OAAO,CAAC,WAAW,CAAS;gBAEhB,MAAM,EAAE,yBAAyB;IAsC7C;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IASjC;;;;;;;OAOG;IACG,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKvD;;;;;;OAMG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,IAAI;IAI/E;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAIxC;;;;;OAKG;IACH,OAAO,IAAI,IAAI;IAMf;;;;;OAKG;IACH,YAAY,IAAI,aAAa,EAAE;CAMhC"}

package/dist/state/intent_ledger.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Micro-Intent Engine — anonymous-visitor cross-session ledger
+ * (P1 Task 7 + P2 Task 4 full implementation).
+ *
+ * Stores `cum_dwell_sku` (rolling cumulative time on PDP per SKU) and
+ * `session_count_for_sku` for anonymous visitors so the Returning
+ * Hover-Browser pattern (catalog ID 4) can fire when an unknown
+ * visitor has accumulated meaningful engagement across multiple sessions.
+ *
+ * ─────────────────────────────────────────────────────────────────────
+ * SAFARI / ITP ACKNOWLEDGEMENT (Robustness #2 — load-bearing)
+ * ─────────────────────────────────────────────────────────────────────
+ *
+ * Apple's Intelligent Tracking Prevention (ITP) caps client-side
+ * `localStorage` to **7 days** for non-interactive third-party browsing
+ * on iOS Safari + macOS Safari.
+ *
+ * The `aegis_intent_ledger` key persisted here decays for anonymous
+ * Safari users faster than for Chrome / Firefox users. Concrete
+ * downstream impact:
+ *
+ *   - Pattern 4 "Returning Hover-Browser" is the ONLY pattern whose
+ *     trigger depends on cross-session anonymous accumulation. On Safari
+ *     it is reliable only within a 7-day window. After that, an
+ *     anonymous returning visitor looks like a new visitor.
+ *
+ *   - All other patterns are session-scoped (Layer-2 only, in-tab) or
+ *     identified-contact-scoped (Layer-1 fetched per identify()), so
+ *     they are unaffected by ITP storage decay.
+ *
+ * DOCUMENTATION REQUIREMENT — when P3a ships the Pattern Detail screen
+ * for Returning Hover-Browser, its UI must carry the footnote:
+ *
+ *   "On Safari, this pattern is reliable for visitors who return within
+ *   7 days. For longer windows, consider identifying customers via
+ *   signed-in checkout."
+ *
+ * SERVER-SIDE FALLBACK (deferred to P5) — when a contact eventually
+ * identifies (sign-in / OTP / checkout), we promote this localStorage
+ * ledger to a server-side `contact_intent_ledger` row. That bypasses
+ * ITP entirely for identified users. Implementation tracked in
+ * MICRO_INTENT_ENGINE.md §"Robustness 2" → "Server-side fallback".
+ *
+ * ─────────────────────────────────────────────────────────────────────
+ * Implementation (P2 Task 4)
+ * ─────────────────────────────────────────────────────────────────────
+ *
+ * The IntentLedger class implements IIntentLedger with localStorage as
+ * the backing store. Capped-LRU at INTENT_LEDGER_MAX_SKUS, rolling
+ * INTENT_LEDGER_WINDOW_DAYS window, hydrate-on-construct, debounced
+ * persistence (250ms) to avoid write-amplification on rapid dwell
+ * ticks. In-memory state is always fresh for synchronous reads.
+ *
+ * The constructor accepts an optional Storage-shaped object for
+ * testability; in production it defaults to `globalThis.localStorage`.
+ * The P2 Task 4 forward-marker below remains so the drift-anchor
+ * test (test_intent_ledger_itp_doc.py) keeps tracking the right
+ * scope reference even after the class lands.
+ *
+ * P2 Task 4 implementation complete (2026-05-11). The acknowledgement
+ * comment above is retained so future engineers reading a Safari bug
+ * report can find the source-of-truth explanation here, not in a plan
+ * doc that may have rotted.
+ */
+/** localStorage key the ledger persists under. Same key in stub and
+ *  P2 Task 4 implementation so the stub-to-full upgrade is non-
+ *  breaking (no key migration). */
+export declare const INTENT_LEDGER_STORAGE_KEY = "aegis_intent_ledger";
+/** Max number of SKU entries persisted. Beyond this, the LRU evicts
+ *  least-recently-touched. Picked to stay well under typical Safari /
+ *  Chrome localStorage caps (~5MB origin quota; we use <2KB). */
+export declare const INTENT_LEDGER_MAX_SKUS = 50;
+/** Rolling window for `cum_dwell_sku` accumulation. Aligns with the
+ *  Safari ITP 7-day cap above — values older than this are dropped on
+ *  every read so the data set doesn't outlive the storage's own
+ *  reliability window. */
+export declare const INTENT_LEDGER_WINDOW_DAYS = 7;
+export interface SkuLedgerEntry {
+    /** Rolling cumulative dwell on this SKU's PDP, in milliseconds. */
+    cumDwellMs: number;
+    /** Distinct session count for this SKU. */
+    sessionCount: number;
+    /** Epoch ms of last update; used for LRU eviction + window pruning. */
+    lastSeenAt: number;
+}
+/** Storage interface — matches the surface of `window.localStorage` we
+ *  actually use. Allows injection in tests without depending on the
+ *  full DOM Storage type. */
+export interface LedgerStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** P1 Task 7 stub. P2 Task 4 fills in the methods. Defining the shape
+ *  here means TriggerEngine + IntentRuleEvaluator can begin importing
+ *  the type without waiting on the storage code. */
+export interface IIntentLedger {
+    /** Add dwell time on the current SKU. No-op on Safari past day 7 due
+     *  to ITP — see module docstring. */
+    addDwell(skuId: string, deltaMs: number): void;
+    /** Increment session count for a SKU. Called once per session per SKU. */
+    noteSession(skuId: string): void;
+    /** Read current accumulated values for a SKU. Returns null for
+     *  unknown / evicted / decayed-out SKUs. */
+    getEntry(skuId: string): SkuLedgerEntry | null;
+}
+export declare class IntentLedger implements IIntentLedger {
+    private readonly storage;
+    private readonly entries;
+    /** Now provider — injectable so tests can simulate time progression
+     *  without faking globalThis.Date.now. */
+    private readonly now;
+    private pendingFlush;
+    constructor(opts?: {
+        storage?: LedgerStorage | null;
+        now?: () => number;
+    });
+    addDwell(skuId: string, deltaMs: number): void;
+    noteSession(skuId: string): void;
+    getEntry(skuId: string): SkuLedgerEntry | null;
+    /** Force a synchronous persistence flush. Caller invokes from the
+     *  SDK's pagehide / beforeunload hook so in-flight dwell isn't lost
+     *  when the tab closes inside the debounce window. */
+    flush(): void;
+    /** Forget every entry — used by `aegis.reset()` and similar. Wipes
+     *  the localStorage row too. */
+    clear(): void;
+    /** Snapshot of all currently-known SKU ids. For tests + the SDK's
+     *  debug surface. */
+    knownSkus(): string[];
+    private hydrate;
+    private evictIfOverCap;
+    private schedulePersist;
+    private persistNow;
+}
+//# sourceMappingURL=intent_ledger.d.ts.map

package/dist/state/intent_ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent_ledger.d.ts","sourceRoot":"","sources":["../../src/state/intent_ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAEH;;mCAEmC;AACnC,eAAO,MAAM,yBAAyB,wBAAwB,CAAC;AAE/D;;iEAEiE;AACjE,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC;;;0BAG0B;AAC1B,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;6BAE6B;AAC7B,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACpC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;oDAEoD;AACpD,MAAM,WAAW,aAAa;IAC5B;yCACqC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/C,0EAA0E;IAC1E,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC;gDAC4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAAC;CAChD;AAsBD,qBAAa,YAAa,YAAW,aAAa;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAC7D;8CAC0C;IAC1C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,YAAY,CAA8C;gBAEtD,IAAI,GAAE;QAChB,OAAO,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;QAC/B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;KACf;IAaN,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAsB9C,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAoBhC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAe9C;;0DAEsD;IACtD,KAAK,IAAI,IAAI;IAQb;oCACgC;IAChC,KAAK,IAAI,IAAI;IAeb;yBACqB;IACrB,SAAS,IAAI,MAAM,EAAE;IAMrB,OAAO,CAAC,OAAO;IAwCf,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,UAAU;CAanB"}

package/dist/triggers/IntentRuleEvaluator.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Micro-Intent Engine — compound rule evaluator (P1 Task 4).
+ *
+ * Pure, side-effect-free evaluation of an IntentRule predicate tree against
+ * a current snapshot of Layer-1 (identity) + Layer-2 (session) signal values.
+ *
+ * Why a separate class from TriggerEngine
+ * ----------------------------------------
+ * TriggerEngine.ts owns signal CAPTURE (scroll, time-on-page, exit-intent,
+ * etc.) and emits named events like `scroll_depth_50`. IntentRuleEvaluator
+ * owns rule EVALUATION — given a compound predicate and the current state
+ * of all known signals, return whether the rule fires now. The two
+ * concerns separate cleanly: capture is global per-page (one engine
+ * instance), evaluation is per-rule (the manager re-runs every armed
+ * rule when a `fire_on` signal fires).
+ *
+ * Type strategy
+ * -------------
+ * Types are declared LOCALLY in this file rather than imported from
+ * `@aegis/shared-types`. The SDK is published standalone on npm and
+ * cannot pull in workspace packages at runtime. A drift-check test
+ * (`libs/web-sdk/tests/intent-evaluator-shared-types-drift.test.ts`)
+ * parses both files and asserts the local types and the canonical
+ * `libs/shared-types/src/intent.ts` declare the same set of signal /
+ * comparator values.
+ *
+ * Plan reference: docs/architecture/MICRO_INTENT_ENGINE.md §"Schemas"
+ */
+export type IntentSignal = 'scroll_depth' | 'time_on_page' | 'exit_intent' | 'back_button' | 'scroll_velocity' | 'inactivity' | 'visibility_change' | 'rage_click' | 'price_hover_ms' | 'cta_hover_ms' | 'cum_dwell_sku' | 'session_count_sku' | 'cart_value' | 'converted_in_session' | 'rfm_segment' | 'rfm_score' | 'lifecycle_stage' | 'purchase_intent_score' | 'purchase_intent_tier' | 'churn_risk_score' | 'churn_risk_tier' | 'predicted_ltv' | 'uninstall_risk_tier' | 'engagement_level' | 'price_tier' | 'price_sensitivity_score' | 'top_category' | 'avg_cart_value' | 'scoring_tier';
+export type Comparator = 'gte' | 'lte' | 'gt' | 'lt' | 'eq' | 'neq' | 'in' | 'nin';
+export type IntentLeafValue = number | string | boolean | ReadonlyArray<number | string | boolean>;
+export interface IntentLeaf {
+    signal: IntentSignal;
+    op: Comparator;
+    value: IntentLeafValue;
+}
+export interface IntentNode {
+    op: 'AND' | 'OR' | 'NOT';
+    operands: ReadonlyArray<IntentExpr>;
+}
+export type IntentExpr = IntentNode | IntentLeaf;
+export interface IntentRule {
+    fire_on: ReadonlyArray<IntentSignal>;
+    when: IntentExpr;
+    priority: number;
+    suppress_competing: boolean;
+}
+/** A scalar a signal can hold in the snapshot. null = signal not (yet)
+ *  populated — happens for Layer-1 scores on anonymous sessions and for
+ *  Layer-2 signals before the user triggers them. */
+export type SignalValue = number | string | boolean | null;
+/** Current state of every known signal. Missing keys are treated the
+ *  same as `null`. */
+export type IntentSnapshot = Partial<Record<IntentSignal, SignalValue>>;
+export declare function isIntentLeaf(expr: IntentExpr): expr is IntentLeaf;
+export declare function isIntentNode(expr: IntentExpr): expr is IntentNode;
+/**
+ * Evaluate a single leaf comparison against a snapshot.
+ *
+ * Missing-signal semantics (per the plan's "Graceful degradation rules"):
+ *   - The CALLER (evaluateExpr) decides AND/OR semantics on missing
+ *     operands; this function answers strictly for THIS leaf.
+ *   - When the signal is missing from the snapshot, the leaf is
+ *     "unknown" → return null so the parent node can interpret it.
+ *
+ * Comparator semantics:
+ *   - gte/lte/gt/lt: numeric only; comparing strings/bools returns false.
+ *   - eq/neq: any type; strict equality.
+ *   - in/nin: leaf value must be a list; membership test on the snapshot
+ *     value. `nin` returns true for missing snapshot values (the
+ *     contact's RFM segment is "not in" the forbidden list if we don't
+ *     know it yet — conservative).
+ */
+export declare function evaluateLeaf(leaf: IntentLeaf, snapshot: IntentSnapshot): boolean | null;
+/**
+ * Evaluate the full predicate tree.
+ *
+ * AND/OR/NOT semantics with missing-value handling (per plan §"Graceful
+ * degradation rules"):
+ *
+ *   AND(a, b, c) where any operand is null → false (conservative; the
+ *     rule doesn't fire when we can't prove all conditions).
+ *   OR(a, b, c) where some operands are null → if any non-null operand
+ *     is true, returns true. If all operands are null OR all are
+ *     false, returns false.
+ *   NOT(a) where a is null → null (parent decides). When this propagates
+ *     to the top-level evaluateExpr, the rule does NOT fire.
+ *
+ * The "AND treats missing as unmet" + "OR treats missing as inert" rule
+ * from the plan maps exactly onto this implementation: AND short-circuits
+ * to false on any null operand; OR ignores nulls and looks at the rest.
+ *
+ * Top-level: a null result from the root expression means the rule
+ * cannot be evaluated yet — do NOT fire.
+ */
+export declare function evaluateExpr(expr: IntentExpr, snapshot: IntentSnapshot): boolean | null;
+/** Top-level "does the rule fire right now?" check. Treats a null
+ *  evaluation result as "do not fire" (we can't prove the rule's
+ *  conditions are met). */
+export declare function evaluateRule(rule: IntentRule, snapshot: IntentSnapshot): boolean;
+/** A campaign carrying a compound rule, in the SDK's runtime shape.
+ *  Mirrors the cell-plane payload at /v1/in-app/active when
+ *  client_trigger.type === 'micro_intent'. */
+export interface ArmedCampaign {
+    id: string;
+    rule: IntentRule;
+}
+/** The decision the evaluator returns when a signal fires.
+ *
+ *  fire        : caller should display this campaign now.
+ *  suppress    : caller should silence the listed competing campaign IDs
+ *                for the rest of the session (the bouncing-researcher
+ *                pattern — a rule whose only job is to silence others).
+ *  none        : no rule matched, do nothing.
+ */
+export interface EvaluationDecision {
+    kind: 'fire' | 'suppress' | 'none';
+    campaignId?: string;
+    suppressIds?: ReadonlyArray<string>;
+}
+export declare class IntentRuleEvaluator {
+    /** All campaigns currently armed on this page. Caller (the
+     *  AegisInAppManager) replaces this on every refresh. */
+    private armed;
+    /** Latest signal values. Caller pushes updates via updateSignal /
+     *  updateSnapshot whenever TriggerEngine emits a state change or
+     *  contact-scores fetch completes. */
+    private snapshot;
+    /** Campaigns that have already fired this session — never re-fire. */
+    private firedThisSession;
+    /** Campaigns silenced by a prior `suppress_competing` win. The set
+     *  resets on session boundary (new tab / new pageview after timeout).
+     *  The AegisInAppManager owns durability semantics; this set is
+     *  in-memory only. */
+    private silencedThisSession;
+    updateSignal(signal: IntentSignal, value: SignalValue): void;
+    updateSnapshot(partial: IntentSnapshot): void;
+    getSnapshot(): Readonly<IntentSnapshot>;
+    setArmed(campaigns: ArmedCampaign[]): void;
+    getArmed(): ReadonlyArray<ArmedCampaign>;
+    markFired(campaignId: string): void;
+    /** Clear all per-session state. Caller invokes on logout or explicit
+     *  session reset. */
+    reset(): void;
+    /**
+     * Called every time a signal value changes meaningfully (e.g. a
+     * TriggerEngine `exit_intent` event, or a `scroll_depth_50` crossing
+     * threshold, or the Layer-1 fetch finishing). Returns the decision the
+     * caller should act on.
+     *
+     * Algorithm:
+     *   1. Filter armed campaigns to those whose `fire_on` includes the
+     *      signal that just changed.
+     *   2. Drop already-fired and silenced campaigns.
+     *   3. Sort the remainder by priority DESC, tie-broken by campaign id
+     *      lexicographic (per plan §"Pattern ordering rules").
+     *   4. Walk the sorted list:
+     *      - If a suppress_competing rule matches, emit a 'suppress'
+     *        decision listing every lower-priority armed campaign id.
+     *        Mark those as silenced internally too.
+     *      - Otherwise the first matching rule emits 'fire'.
+     *   5. If nothing matches, return 'none'.
+     */
+    onSignalChanged(signal: IntentSignal): EvaluationDecision;
+}
+export declare const MAX_RULE_DEPTH: 3;
+//# sourceMappingURL=IntentRuleEvaluator.d.ts.map

package/dist/triggers/IntentRuleEvaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IntentRuleEvaluator.d.ts","sourceRoot":"","sources":["../../src/triggers/IntentRuleEvaluator.ts"],"names":[],"mappings":"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"}

package/dist/triggers/IntentSnapshotCollector.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Micro-Intent Engine — pipeline integration (P2 Task 5).
+ *
+ * Wires the three signal-capture surfaces (SelectorBinder, TriggerEngine,
+ * IntentLedger) together and projects their current state onto the
+ * IntentRuleEvaluator's `IntentSnapshot`. The collector is the single
+ * place every Layer-2 signal flows through on its way into rule
+ * evaluation — adding a new signal means touching exactly one file.
+ *
+ * Wiring summary
+ * --------------
+ *   SelectorBinder.hover_start  →  TriggerEngine.noteHoverStart
+ *                               →  evaluator.updateSignal(price/cta_hover_ms, 0)
+ *   SelectorBinder.hover_end    →  TriggerEngine.noteHoverEnd
+ *                               →  evaluator.updateSignal(price/cta_hover_ms, getHoverMs)
+ *   SelectorBinder.click        →  TriggerEngine.noteClick
+ *                               →  evaluator.updateSignal(rage_click, getRageClickCount)
+ *   SelectorBinder.sku_change   →  IntentLedger.noteSession
+ *                               →  evaluator.updateSignal(cum_dwell_sku, session_count_sku)
+ *
+ *   window.mousemove (≤100ms)   →  TriggerEngine.noteMousePosition
+ *                               →  evaluator.updateSignal(mouse_velocity_to_top)
+ *
+ *   pagehide / beforeunload     →  ledger.flush()
+ *
+ * Why a separate class instead of putting this in AegisInAppManager:
+ * the manager already owns delivery + display rules + suppression.
+ * Adding "snapshot wrangling" on top would make it the SDK's
+ * everything-shaped object. The collector keeps signal flow isolated
+ * and unit-testable without spinning up the full manager.
+ *
+ * The collector is signal-name-agnostic in its core flow — the only
+ * place IntentSignal names appear is the `signalForIntent()` helper
+ * that maps the `price` intent to the `price_hover_ms` signal etc.
+ * If we add a new intent (e.g. `coupon_hover_ms`) the helper grows;
+ * everything else is reused.
+ */
+import type { SelectorBinder } from './SelectorBinder';
+import type { IntentRuleEvaluator, IntentSignal, EvaluationDecision } from './IntentRuleEvaluator';
+import type { IntentLedger } from '../state/intent_ledger';
+import { TriggerEngine } from './TriggerEngine';
+export interface IntentSnapshotCollectorConfig {
+    triggerEngine: TriggerEngine;
+    selectorBinder: SelectorBinder;
+    intentRuleEvaluator: IntentRuleEvaluator;
+    intentLedger?: IntentLedger;
+    /** Throttle floor for mousemove sampling, in ms. Plan default = 100. */
+    mouseSampleMs?: number;
+    /** Forwarded decisions from `evaluator.onSignalChanged` — the
+     *  AegisInAppManager subscribes here to drive the actual campaign
+     *  display / suppress side-effects. */
+    onDecision?: (decision: EvaluationDecision) => void;
+}
+export declare class IntentSnapshotCollector {
+    private readonly triggerEngine;
+    private readonly selectorBinder;
+    private readonly evaluator;
+    private readonly ledger;
+    private readonly mouseSampleMs;
+    private onDecision?;
+    private started;
+    private unsubscribeBinder?;
+    private lastMouseSampleAt;
+    private mouseMoveHandler?;
+    private flushHandler?;
+    constructor(cfg: IntentSnapshotCollectorConfig);
+    start(): void;
+    stop(): void;
+    /** Override the decision callback after construction — used by the
+     *  AegisInAppManager when it lazily wires up. */
+    setDecisionHandler(handler: (d: EvaluationDecision) => void): void;
+    /**
+     * Caller signals that a known trigger event happened (exit_intent,
+     * back_button, scroll_depth_50, etc.). The collector forwards to the
+     * evaluator and pushes any resulting decision through `onDecision`.
+     *
+     * The signal-name here must be a real IntentSignal — anything else is
+     * silently ignored (no-throw, the SDK can't crash a host page).
+     */
+    notifyTrigger(signal: IntentSignal): void;
+    private handleBinderEvent;
+}
+//# sourceMappingURL=IntentSnapshotCollector.d.ts.map

package/dist/triggers/IntentSnapshotCollector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IntentSnapshotCollector.d.ts","sourceRoot":"","sources":["../../src/triggers/IntentSnapshotCollector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAGV,cAAc,EACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EACV,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EACnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAQhD,MAAM,WAAW,6BAA6B;IAC5C,aAAa,EAAE,aAAa,CAAC;IAC7B,cAAc,EAAE,cAAc,CAAC;IAC/B,mBAAmB,EAAE,mBAAmB,CAAC;IACzC,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;2CAEuC;IACvC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,IAAI,CAAC;CACrD;AAED,qBAAa,uBAAuB;IAClC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAChD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,UAAU,CAAC,CAAkC;IAErD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,iBAAiB,CAAC,CAAa;IACvC,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,gBAAgB,CAAC,CAA0B;IACnD,OAAO,CAAC,YAAY,CAAC,CAAa;gBAEtB,GAAG,EAAE,6BAA6B;IAe9C,KAAK,IAAI,IAAI;IAyCb,IAAI,IAAI,IAAI;IAkBZ;qDACiD;IACjD,kBAAkB,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,kBAAkB,KAAK,IAAI,GAAG,IAAI;IAMlE;;;;;;;OAOG;IACH,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAOzC,OAAO,CAAC,iBAAiB;CA6C1B"}

package/dist/triggers/SelectorBinder.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Micro-Intent Engine — delegated event listeners (P1 Task 5, robustness #1).
+ *
+ * The problem
+ * -----------
+ * Static `document.querySelector('.price').addEventListener(...)` on SDK
+ * init detaches the moment Shopify themes, React/Next.js storefronts, or
+ * any SPA re-renders the price node. Element-scoped signals
+ * (price_hover_ms, cta_hover_ms, rage-click-on-coupon) then fail
+ * silently — the worst possible failure mode because nothing logs.
+ *
+ * The fix
+ * -------
+ * Bind ONCE to `document.body` (capture phase) and dispatch via
+ * `event.target.closest(selector)`. The handler runs globally; the
+ * configured intent selectors are evaluated per-event. Survives any
+ * framework re-render — there's never a stale reference because we
+ * never held one.
+ *
+ *   document.body.addEventListener('mouseenter', this.handleHover, true);
+ *   document.body.addEventListener('mouseleave', this.handleHover, true);
+ *   document.body.addEventListener('pointerdown', this.handleClick, true);
+ *
+ * Plus a `MutationObserver` that watches for changes to the configured
+ * SKU selector so a SPA navigating between PDPs without a full page
+ * load still updates the engine's `cum_dwell_sku` / `session_count_sku`
+ * context. The observer is NOT used to re-attach event listeners
+ * (delegation makes that unnecessary).
+ *
+ * What this file does NOT do
+ * --------------------------
+ * Compute `price_hover_ms` / `cta_hover_ms` dwell totals, or count
+ * rage-clicks. That arithmetic lives in TriggerEngine.ts (P2 Tasks
+ * 1-3) which subscribes to this binder via `onIntent(handler)` and
+ * accumulates into snapshot values. SelectorBinder is the I/O layer;
+ * the timing logic is downstream.
+ *
+ * Plan reference: docs/architecture/MICRO_INTENT_ENGINE.md §"Robustness
+ * 1 — DOM brittleness".
+ */
+/** Named element role the storefront marks. The selector config maps
+ *  each name to one or more CSS selectors; on every match, the binder
+ *  emits an IntentDomEvent with this name as `intent`. */
+export type IntentElementName = 'price' | 'cta' | 'coupon' | 'checkout' | 'sku';
+/** Event types the binder forwards. Keep narrow on purpose — every
+ *  type carried downstream is a real signal someone derives from. */
+export type IntentDomEventType = 'hover_start' | 'hover_end' | 'click' | 'sku_change';
+export interface IntentDomEvent {
+    type: IntentDomEventType;
+    intent: IntentElementName;
+    /** Best-effort: the matched element. Consumers shouldn't hold strong
+     *  references — the SPA may unmount it before the next event fires. */
+    target: Element | null;
+    /** For `sku_change`: the new SKU id (read from `data-aegis-sku` or the
+     *  matched element's `data-product-id` / `data-sku` attribute). For
+     *  other events: undefined. */
+    sku?: string;
+    timestamp: number;
+}
+export type IntentDomHandler = (evt: IntentDomEvent) => void;
+/** Map from intent name to a list of CSS selectors that mark elements
+ *  playing that role on the storefront. Multiple selectors per intent
+ *  so a single plugin config can cover all the themes / DOM variants
+ *  it knows about. */
+export type IntentSelectors = Partial<Record<IntentElementName, ReadonlyArray<string>>>;
+export interface SelectorBinderConfig {
+    /** Caller-supplied selectors, highest priority. */
+    intentSelectors?: IntentSelectors;
+    /** Server-pushed selectors from /v1/sdk/config (dashboard-managed).
+     *  Falls behind explicit init but ahead of platform defaults. */
+    serverSelectors?: IntentSelectors;
+    /** Platform-default map bundled with the plugin (Shopify / Woo /
+     *  Magento). Lowest non-fallback priority. */
+    platformDefaults?: IntentSelectors;
+}
+export declare class SelectorBinder {
+    private readonly selectors;
+    private readonly listeners;
+    private observer;
+    private boundRoot;
+    private currentSku;
+    /** Element-keyed memory of which intent is currently hovered, so we
+     *  can fire `hover_end` even if the matched DOM node unmounts in
+     *  between (the unmount path is `hover_start` → unmount → no
+     *  `hover_end`; we rely on `mouseleave` capture which fires on the
+     *  original target before unmount in most browsers). */
+    private hoverActive;
+    constructor(config?: SelectorBinderConfig);
+    /** Subscribe to delegated DOM events. Returns an unsubscribe fn. */
+    onIntent(handler: IntentDomHandler): () => void;
+    /** Attach listeners + MutationObserver. Idempotent — calling twice
+     *  is a no-op so a manager that re-initializes doesn't double-bind. */
+    start(doc?: Document): void;
+    /** Detach listeners and observer. Idempotent. The manager calls this
+     *  on `destroy()`. */
+    stop(): void;
+    /** Snapshot of the currently-active SKU on the page. Used by
+     *  TriggerEngine to attribute hover/click events to a product context.
+     *  Undefined when the page has no SKU element or it's been unmounted. */
+    getCurrentSku(): string | undefined;
+    /** Current selector resolution — useful for tests + editor "preview"
+     *  to show which selectors would match. */
+    getResolvedSelectors(): Readonly<Required<IntentSelectors>>;
+    /** Find the intent name a given event target belongs to (if any).
+     *  Walks the configured selectors in order; first match wins. Returns
+     *  null if none match (the event is for unrelated DOM and should be
+     *  ignored). */
+    private matchIntent;
+    private emit;
+    private handleHoverStart;
+    private handleHoverEnd;
+    private handleClick;
+    private handleMutation;
+    /** Re-resolve the current SKU from the page. Emits `sku_change` if
+     *  the value differs from the prior snapshot. */
+    private refreshCurrentSku;
+}
+//# sourceMappingURL=SelectorBinder.d.ts.map

package/dist/triggers/SelectorBinder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SelectorBinder.d.ts","sourceRoot":"","sources":["../../src/triggers/SelectorBinder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH;;0DAE0D;AAC1D,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,KAAK,GAAG,QAAQ,GAAG,UAAU,GAAG,KAAK,CAAC;AAEhF;qEACqE;AACrE,MAAM,MAAM,kBAAkB,GAC1B,aAAa,GACb,WAAW,GACX,OAAO,GACP,YAAY,CAAC;AAEjB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,EAAE,iBAAiB,CAAC;IAC1B;2EACuE;IACvE,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACvB;;mCAE+B;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,CAAC;AAE7D;;;sBAGsB;AACtB,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,iBAAiB,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AAmDxF,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC;qEACiE;IACjE,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC;kDAC8C;IAC9C,gBAAgB,CAAC,EAAE,eAAe,CAAC;CACpC;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4B;IACtD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA+B;IACzD,OAAO,CAAC,QAAQ,CAAiC;IACjD,OAAO,CAAC,SAAS,CAAyB;IAC1C,OAAO,CAAC,UAAU,CAAqB;IACvC;;;;4DAIwD;IACxD,OAAO,CAAC,WAAW,CAA6C;gBAEpD,MAAM,GAAE,oBAAyB;IAS7C,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,IAAI;IAO/C;2EACuE;IACvE,KAAK,CAAC,GAAG,GAAE,QAAqF,GAAG,IAAI;IAgCvG;0BACsB;IACtB,IAAI,IAAI,IAAI;IAcZ;;6EAEyE;IACzE,aAAa,IAAI,MAAM,GAAG,SAAS;IAInC;+CAC2C;IAC3C,oBAAoB,IAAI,QAAQ,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;IAM3D;;;oBAGgB;IAChB,OAAO,CAAC,WAAW;IAmBnB,OAAO,CAAC,IAAI;IAYZ,OAAO,CAAC,gBAAgB,CActB;IAEF,OAAO,CAAC,cAAc,CAapB;IAEF,OAAO,CAAC,WAAW,CAWjB;IAEF,OAAO,CAAC,cAAc,CAMpB;IAEF;qDACiD;IACjD,OAAO,CAAC,iBAAiB;CAyB1B"}