@blotoutio/providers-evo-search-sdk 1.70.2 → 1.71.1

package/core.cjs.js

@@ -817,6 +817,16 @@ const uiActions = new Set([
     'evoSearchProductAddedToCart',
     'evoSearchProductPurchased',
     'evoSearchSearchIssued',
+    // Relevance-telemetry pair (PR2 task 3): one impressions beacon per
+    // finalized query, one click beacon per result click. Server handling
+    // (Task 4) wired in routes/user.ts.
+    'evoSearchImpressions',
+    'evoSearchResultClick',
+    // One beacon per Ask answer the assistant could not produce (generation
+    // failure, budget exhaustion) — the client-side counterpart to the worker's
+    // own degrade counters, and the only signal for a failure the worker never
+    // sees (the request never reaching it).
+    'evoSearchAskDegraded',
 ]);
 new Set([...uiActions]);
 
@@ -854,6 +864,172 @@ const logger = {
     },
 };
 
+// Pure, DOM-free session-context logic: what the shopper's tab has seen this
+// visit, kept small enough to ride along on every search request as a `ctx`
+// query param and every finalized-query beacon. No PII — ids, capped query
+// strings, and an enum page type only. Storage wiring (sessionStorage
+// read/write, entry page detection from location.pathname) lives in
+// utils.ts; this module only knows how to grow and shrink the shape
+// immutably, and how to encode it for the wire.
+// Single source of truth for the enum — utils.ts's sessionStorage parse
+// validates membership against this (not just `typeof === 'string'`) before
+// trusting a stored value, so a hostile/corrupted entry can't smuggle an
+// arbitrary string into the wire payload.
+const PAGE_TYPES = [
+    'home',
+    'plp',
+    'pdp',
+    'cart',
+    'search',
+    'other',
+];
+const isPageType = (value) => typeof value === 'string' && PAGE_TYPES.includes(value);
+const MAX_VIEWED = 20;
+// A product id longer than this is not an id any catalog issues; it is a
+// runaway string that would eat the whole byte budget on one entry. Mirrors
+// the decoder's own per-id cap, which DROPS (never truncates) an oversized
+// id — a truncated id silently becomes a different, wrong product.
+const MAX_PRODUCT_ID_CHARS = 64;
+// The platform's global-id form for a product. Hosts hand us whichever form
+// their storefront layer has to hand; the catalog is keyed on the bare id, so
+// normalize here rather than making every caller remember which one to pass.
+const GLOBAL_ID_PREFIX = 'gid://shopify/Product/';
+/**
+ * Coerces a caller-supplied product id into the id space the catalog uses, or
+ * null when it cannot be one. Accepts a number (storefront globals expose the
+ * id numerically) or a string, tolerates the platform's global-id form, and
+ * rejects empty/oversized values rather than putting an id on the wire that
+ * can never resolve.
+ */
+const normalizeProductId = (value) => {
+    const raw = typeof value === 'number' && Number.isFinite(value)
+        ? String(value)
+        : typeof value === 'string'
+            ? value.trim()
+            : '';
+    const id = raw.startsWith(GLOBAL_ID_PREFIX)
+        ? raw.slice(GLOBAL_ID_PREFIX.length)
+        : raw;
+    if (!id || id.length > MAX_PRODUCT_ID_CHARS) {
+        return null;
+    }
+    return id;
+};
+// Hard cap enforced by serializeContext, measured in ENCODED UTF-8 BYTES —
+// `.length` counts UTF-16 code units, which undercounts CJK/emoji text by up
+// to 3x. Kept in sync with the `ctx` query param budget documented in the
+// PR2 brief (base64url grows this ~4/3, so ~2.7KB encoded — comfortably
+// inside URL limits).
+const MAX_SERIALIZED_BYTES = 2048;
+const pushViewed = (ctx, id) => ({
+    ...ctx,
+    viewed: [id, ...ctx.viewed.filter((viewedId) => viewedId !== id)].slice(0, MAX_VIEWED),
+});
+// Drops entries from the tail (pushViewed/pushQuery keep newest-first) until
+// the ENCODED byte length fits the hard cap, in order of how much each byte
+// is worth: the browse list first (its tail is the least recent thing the
+// shopper looked at, and it is the longest list), then the cart, then the
+// queries — fewest entries and the most intent per byte, so they yield last
+// but are not exempt: five 200-char CJK queries alone encode to ~3KB, so a
+// character-bounded list can still blow a byte budget.
+const serializeContext = (ctx) => {
+    let working = {
+        ...ctx,
+        viewed: [...ctx.viewed],
+        cart: [...ctx.cart],
+        queries: [...ctx.queries],
+    };
+    let serialized = JSON.stringify(working);
+    while (textEncoder.encode(serialized).length > MAX_SERIALIZED_BYTES &&
+        (working.viewed.length > 0 ||
+            working.cart.length > 0 ||
+            working.queries.length > 0)) {
+        working =
+            working.viewed.length > 0
+                ? { ...working, viewed: working.viewed.slice(0, -1) }
+                : working.cart.length > 0
+                    ? { ...working, cart: working.cart.slice(0, -1) }
+                    : { ...working, queries: working.queries.slice(0, -1) };
+        serialized = JSON.stringify(working);
+    }
+    return serialized;
+};
+// Detected once per session from the entry URL — home/plp/pdp/cart by path
+// shape, everything else is 'other'. Pure so it's testable alongside the
+// rest of this module; utils.ts calls it exactly once, on first read.
+const detectEntryPage = (pathname) => {
+    if (pathname === '/') {
+        return 'home';
+    }
+    if (pathname.startsWith('/products/')) {
+        return 'pdp';
+    }
+    if (pathname.startsWith('/collections/')) {
+        return 'plp';
+    }
+    if (pathname.startsWith('/cart')) {
+        return 'cart';
+    }
+    return 'other';
+};
+// Native TextEncoder + btoa, same as the CDN sibling's utils/user-auth.ts —
+// jsdom's missing TextEncoder is a test-environment gap, polyfilled in
+// jest.setup.ts rather than worked around in shipped code.
+const textEncoder = new TextEncoder();
+const toBase64Url = (bytes) => {
+    let bin = '';
+    for (let i = 0; i < bytes.length; i++) {
+        bin += String.fromCharCode(bytes[i]);
+    }
+    return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+};
+// Wire form for the `ctx` search query param: base64url(serializeContext(ctx)),
+// no padding. Returns null when there's nothing worth the extra URL bytes —
+// a context with no viewed products, cart lines or past queries yet (e.g. the very
+// first search of a fresh tab) — so a brand-new session doesn't pay for a
+// param carrying only the entryPage enum.
+const encodeContextParam = (ctx) => {
+    if (ctx.viewed.length === 0 &&
+        ctx.cart.length === 0 &&
+        ctx.queries.length === 0) {
+        return null;
+    }
+    return toBase64Url(textEncoder.encode(serializeContext(ctx)));
+};
+
+// `crypto.randomUUID` is secure-context-only: on an `http://` storefront it is
+// undefined and calling it throws a TypeError. Called bare, that threw from
+// inside the autocomplete and image-search render paths — after results were
+// already assigned — so the catch cleared them and the shopper saw an error
+// state for a working search. `crypto.getRandomValues` has no such
+// restriction, so it carries the fallback; Math.random is the last resort for
+// an environment with no crypto at all. The output stays RFC4122-v4 shaped
+// either way, because the worker's beacon validators reject anything else.
+const randomBytes16 = () => {
+    const bytes = new Uint8Array(16);
+    if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+        crypto.getRandomValues(bytes);
+        return bytes;
+    }
+    for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = Math.floor(Math.random() * 256);
+    }
+    return bytes;
+};
+const mintId = () => {
+    var _a, _b;
+    if (typeof crypto !== 'undefined' &&
+        typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    const bytes = randomBytes16();
+    // Version 4, variant 10xx — the two bits the shape check would otherwise
+    // read as a malformed id.
+    bytes[6] = (((_a = bytes[6]) !== null && _a !== void 0 ? _a : 0) & 0x0f) | 0x40;
+    bytes[8] = (((_b = bytes[8]) !== null && _b !== void 0 ? _b : 0) & 0x3f) | 0x80;
+    const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+};
 // Intentionally duplicated from @blotoutio/providers/evo-search/config to keep the hooks bundle lean — importing from the config barrel pulls the shared/universal geo data into dist/hooks.mjs (~4KB gzipped). Drift between the two values is caught by utils.test.ts.
 const previewKeyName = 'previewEvoSearch';
 const hasPreviewKey = () => {
@@ -878,6 +1054,101 @@ const hasDisableKey = () => {
         return false;
     }
 };
+// Cross-widget, cross-search shopper context (recently viewed products,
+// finalized queries, entry page) that rides along on every search
+// request as a `ctx` query param and every finalized-query beacon, so
+// ranking/telemetry can see the visit's shape without the worker
+// maintaining its own session. A query param, not a header, so /search
+// stays a CORS-simple request (no preflight on the per-keystroke hot path).
+// sessionStorage-scoped like the rest of this file's keys: it dies with the
+// tab and never needs a retention policy. No PII — see session-context.ts.
+const sessionContextKeyName = 'evoSearchSessionContext';
+const emptySessionContext = () => ({
+    viewed: [],
+    cart: [],
+    queries: [],
+    entryPage: detectEntryPage(typeof window !== 'undefined' ? window.location.pathname : ''),
+});
+const getSessionContext = () => {
+    try {
+        const raw = sessionStorage.getItem(sessionContextKeyName);
+        if (raw) {
+            const parsed = JSON.parse(raw);
+            // Element types are checked, not just array-ness: a corrupted stored
+            // value (e.g. viewed: [123]) must not flow onto the wire as non-string
+            // data. Fall through to a fresh context instead, same as the
+            // entryPage enum check below.
+            const isStringArray = (value) => Array.isArray(value) && value.every((v) => typeof v === 'string');
+            // Absent, not invalid: a tab that started on an older SDK has a stored
+            // context with no `cart` key at all. Reading that as a shape failure
+            // would throw away its viewed/queries history on every upgrade, so a
+            // missing list reads as an empty one; a wrong-typed one still falls
+            // through to a fresh context like any other corrupted array.
+            const storedCart = parsed.cart === undefined ? [] : parsed.cart;
+            if (isStringArray(parsed.viewed) &&
+                isStringArray(parsed.queries) &&
+                isStringArray(storedCart)) {
+                return {
+                    viewed: parsed.viewed,
+                    cart: storedCart,
+                    queries: parsed.queries,
+                    // A hostile/corrupted stored value (or a future enum member from a
+                    // newer SDK version) falls back to 'other' rather than discarding
+                    // otherwise-good viewed/queries data, and rather than passing
+                    // an unvalidated string through to the wire.
+                    entryPage: isPageType(parsed.entryPage) ? parsed.entryPage : 'other',
+                };
+            }
+        }
+    }
+    catch {
+        // Storage unavailable or corrupt; fall through to a fresh context.
+    }
+    // First read this session: detect entryPage once and persist immediately
+    // so a later navigation within the same tab doesn't re-detect it from a
+    // different path.
+    const fresh = emptySessionContext();
+    setSessionContext(fresh);
+    return fresh;
+};
+/** @internal */
+const setSessionContext = (ctx) => {
+    try {
+        sessionStorage.setItem(sessionContextKeyName, serializeContext(ctx));
+    }
+    catch {
+        // Storage unavailable; the context is best-effort telemetry, not
+        // functionality — swallow rather than fail whatever caller triggered it.
+    }
+};
+// base64url-encoded form for the `ctx` search query param — null when
+// there's nothing worth adding to the URL yet (see encodeContextParam).
+// api.ts stays decoupled from session-context's internals. Memoized because
+// search() calls this on every debounced keystroke: the cache is keyed on
+// the raw stored string, so a hit costs one getItem + compare instead of the
+// parse/serialize/encode chain, and any writer (not just setSessionContext)
+// invalidates it naturally.
+let cachedContextRaw = null;
+let cachedContextParam = null;
+const getSessionContextParam = () => {
+    let raw = null;
+    try {
+        raw = sessionStorage.getItem(sessionContextKeyName);
+    }
+    catch {
+        // Storage unavailable — nothing stable to memoize against.
+        return encodeContextParam(getSessionContext());
+    }
+    if (raw !== null && raw === cachedContextRaw) {
+        return cachedContextParam;
+    }
+    const ctx = getSessionContext();
+    cachedContextParam = encodeContextParam(ctx);
+    // A null raw means getSessionContext just persisted a fresh context — key
+    // the cache on what it wrote so the next call hits.
+    cachedContextRaw = raw !== null && raw !== void 0 ? raw : serializeContext(ctx);
+    return cachedContextParam;
+};
 
 var _a;
 const registryKey = Symbol.for('evo-search');
@@ -914,6 +1185,260 @@ const notifyReady = () => {
     notifySubscribers(registry.subscribers, 'notifyReady');
 };
 
+/**
+ * Storefront-local helpers, deliberately separate from the worker-scoped API
+ * client: `api.ts` injects identity params and headers that must never reach
+ * the merchant's own origin, and its `credentials: omit` policy is the
+ * opposite of what storefront requests (which ride the cart cookie) need.
+ */
+/**
+ * The storefront's root path. Shopify publishes it (locale prefix included,
+ * e.g. `/en-ca/`) on `window.Shopify.routes.root`; default to `/`.
+ */
+const storefrontRoot = () => {
+    var _a, _b;
+    if (typeof window === 'undefined') {
+        return '/';
+    }
+    const root = (_b = (_a = window.Shopify) === null || _a === void 0 ? void 0 : _a.routes) === null || _b === void 0 ? void 0 : _b.root;
+    return typeof root === 'string' && root.startsWith('/') && root.endsWith('/')
+        ? root
+        : '/';
+};
+
+// Storefront-side producers for the shopper session context. `session-context.ts`
+// knows how to grow the shape and `utils.ts` how to persist it; this module is
+// the only place that decides, from the page itself, WHAT to put in it.
+//
+// Why it exists: the widget's product-click handler is the only other producer,
+// so a shopper who browses the storefront normally — landing on product pages
+// from a collection, an ad, or a link — contributes nothing to ranking until
+// they happen to click a result inside search. Capturing the product page the
+// shopper is standing on closes that gap.
+//
+// Constraints this module works under, all deliberate:
+//   - No network calls. This runs on the merchant's storefront; every id comes
+//     from something already in the page (a global the platform published, or
+//     the page's own structured data) or from a host that hands it to us.
+//   - No PII, no page text. Ids only — never titles, prices or descriptions.
+//   - Never throws. Every source is optional and best-effort: a page that
+//     exposes none of them simply contributes nothing.
+//   - No consent gate of its own. The context is anonymous, client-held and
+//     dies with the tab; the provider is loaded under the pixel's own consent
+//     decision, so a suppressed init means no capture at all, and the
+//     transport (the `ctx` search param) stays gated on the merchant opt-in
+//     that api.ts checks.
+const shopifyMeta = () => {
+    var _a, _b;
+    const w = window;
+    // Two spellings of the same platform-published object: themes render the
+    // analytics one, and some render a bare `meta` as well. Neither is catalog
+    // data — they are the platform's page-scoped conventions.
+    return (_b = (_a = w.ShopifyAnalytics) === null || _a === void 0 ? void 0 : _a.meta) !== null && _b !== void 0 ? _b : w.meta;
+};
+/**
+ * True when the page the shopper is on is a product page, by the two signals
+ * a storefront publishes without us asking: the platform's own page-type
+ * marker, and the product path shape under the storefront root (which carries
+ * the locale prefix on localized stores, so `/fr/products/…` is recognized).
+ */
+const onProductPage = () => {
+    var _a, _b;
+    if (((_b = (_a = shopifyMeta()) === null || _a === void 0 ? void 0 : _a.page) === null || _b === void 0 ? void 0 : _b.pageType) === 'product') {
+        return true;
+    }
+    return window.location.pathname.startsWith(`${storefrontRoot()}products/`);
+};
+// Structured data is the last resort and the only source read out of the DOM,
+// so it is bounded on every axis: how many blocks are parsed, how big a block
+// may be, and how deep the search for a Product node goes.
+const MAX_LD_BLOCKS = 5;
+// A structured-data block far larger than this is a page-wide graph, not one
+// product's node; parsing it would cost more than the signal is worth.
+const MAX_LD_CHARS = 100000;
+const productIdFromLdNode = (node) => {
+    if (!node || typeof node !== 'object') {
+        return null;
+    }
+    if (Array.isArray(node)) {
+        for (const entry of node) {
+            const found = productIdFromLdNode(entry);
+            if (found) {
+                return found;
+            }
+        }
+        return null;
+    }
+    const record = node;
+    const graph = record['@graph'];
+    if (Array.isArray(graph)) {
+        return productIdFromLdNode(graph);
+    }
+    const type = record['@type'];
+    const isProduct = Array.isArray(type)
+        ? type.includes('Product')
+        : type === 'Product';
+    if (!isProduct) {
+        return null;
+    }
+    const id = normalizeProductId(record['productID']);
+    // Only an all-digits id is accepted here, and `sku` is never read: the
+    // catalog is keyed on the platform's own numeric product id, whereas a
+    // merchant SKU (or a handle) is a different id space entirely. An id from
+    // the wrong space can never resolve server-side — it would silently occupy
+    // one of the few recently-viewed slots and contribute nothing. A host whose
+    // structured data carries something else should call `trackProductView`.
+    return id && /^\d+$/.test(id) ? id : null;
+};
+const productIdFromStructuredData = () => {
+    const blocks = document.querySelectorAll('script[type="application/ld+json"]');
+    const limit = Math.min(blocks.length, MAX_LD_BLOCKS);
+    for (let i = 0; i < limit; i++) {
+        const text = blocks[i].textContent;
+        if (!text || text.length > MAX_LD_CHARS) {
+            continue;
+        }
+        try {
+            const found = productIdFromLdNode(JSON.parse(text));
+            if (found) {
+                return found;
+            }
+        }
+        catch {
+            // A malformed block is one merchant app's problem, not ours; try the
+            // next one.
+        }
+    }
+    return null;
+};
+/**
+ * The id of the product this page is about, or null when the page isn't a
+ * product page (or doesn't say which product it is). Sources are tried
+ * cheapest first and each one is optional.
+ */
+const currentProductId = () => {
+    var _a, _b;
+    try {
+        // The platform global is authoritative and free: it is only populated on
+        // a product page, and it carries the id in the catalog's own id space.
+        const fromGlobal = normalizeProductId((_b = (_a = shopifyMeta()) === null || _a === void 0 ? void 0 : _a.product) === null || _b === void 0 ? void 0 : _b.id);
+        if (fromGlobal) {
+            return fromGlobal;
+        }
+        if (!onProductPage()) {
+            return null;
+        }
+        return productIdFromStructuredData();
+    }
+    catch {
+        return null;
+    }
+};
+const rememberView = (id) => {
+    const ctx = getSessionContext();
+    // Once per page load: a re-entrant call (a second capture attempt, a
+    // re-init) must not churn storage for a product that is already the most
+    // recent view. A LATER load of the same product is a different matter — by
+    // then something else is at the head, so it pushes again and moves back to
+    // the front, which is how recency is expressed. There is no repeat counter:
+    // `viewed` is a deduplicated, newest-first list and the server tallies each
+    // id once.
+    if (ctx.viewed[0] === id) {
+        return;
+    }
+    setSessionContext(pushViewed(ctx, id));
+};
+/**
+ * Records the product page the shopper is currently on, if this is one.
+ * Returns whether anything was recorded (the retry below is its only caller
+ * that cares).
+ */
+const captureProductView = () => {
+    try {
+        const id = currentProductId();
+        if (!id) {
+            return false;
+        }
+        rememberView(id);
+        return true;
+    }
+    catch {
+        // Storage or DOM unavailable — the context is best-effort ranking input,
+        // never functionality.
+        return false;
+    }
+};
+/**
+ * Called once from the SDK bootstrap. The platform's page globals are written
+ * by the theme's own head markup, so a loader that runs ahead of them would
+ * see nothing at init; when the document is still parsing and nothing was
+ * found, try again once the DOM is complete.
+ */
+const startProductViewCapture = () => {
+    try {
+        if (captureProductView()) {
+            return;
+        }
+        if (document.readyState === 'loading') {
+            document.addEventListener('DOMContentLoaded', () => {
+                captureProductView();
+            }, { once: true });
+        }
+    }
+    catch {
+        // See captureProductView.
+    }
+};
+
+const createSessionContextGate = (uiPreferences, fetchConfig, 
+// Whether this shopper has accumulated anything worth sending yet. Spending
+// a request to ask permission to send nothing is the one case where the
+// probe is pure waste, and it is also the common one — a session that has
+// just started has an empty context.
+hasContext) => {
+    let serverEnabled = false;
+    // One probe per API instance, latched BEFORE the request is issued so a
+    // slow or failing config fetch can never turn the per-keystroke search path
+    // into a retry storm. A probe that fails leaves the gate off, which is the
+    // safe answer: the context is best-effort ranking input, never correctness.
+    let probed = false;
+    const prime = () => {
+        // An explicit merchant preference already decides the question in both
+        // directions, so there is nothing to ask the server about.
+        if (probed || (uiPreferences === null || uiPreferences === void 0 ? void 0 : uiPreferences.sessionContext) !== undefined) {
+            return;
+        }
+        // Deliberately does NOT latch `probed`: a session with nothing to say yet
+        // will have something to say later, and that later call is the one worth
+        // spending the probe on.
+        if (!hasContext()) {
+            return;
+        }
+        probed = true;
+        // Deferred to a microtask so the request that triggered the prime is
+        // already on the wire: the probe must never compete with, delay, or
+        // reorder the search it rides behind.
+        void Promise.resolve().then(() => fetchConfig().catch(() => {
+            // Swallowed deliberately — the gate simply stays off. The caller that
+            // triggered this never learns of it, and never retries.
+        }));
+    };
+    return {
+        shouldSend: () => {
+            var _a;
+            prime();
+            // The merchant preference is an explicit override in both directions;
+            // absent — the normal state — defers to the server's last answer.
+            return (_a = uiPreferences === null || uiPreferences === void 0 ? void 0 : uiPreferences.sessionContext) !== null && _a !== void 0 ? _a : serverEnabled;
+        },
+        prime,
+        resolveFrom: (sessionContextEnabled) => {
+            probed = true;
+            serverEnabled = sessionContextEnabled === true;
+        },
+    };
+};
+
 // Resilience wrapper for /search requests. A transient network failure or a
 // hung request must not wedge the UI: add a per-attempt timeout (a hang becomes
 // a rejection), retry transient failures with backoff, and never retry a
@@ -1150,6 +1675,13 @@ const downscaleImage = async (source) => {
 // Ask can't reuse withSearchResilience: a half-consumed stream isn't retryable.
 // Idle timeout resets per chunk; both reject with TimeoutError so submitAsk
 // routes them to the search fallback rather than treating them as cancellation.
+// Ceiling for an assembled GET URL, past which the optional session-context
+// param is dropped (see getJSON). Chosen above the encoder's own worst case —
+// session-context.ts caps its payload at 2KB, which base64url-grows to ~2.7KB
+// — so a legitimately full context is never dropped on its own, and several
+// times under the request-line ceiling of the edge that terminates these
+// requests. It is a safety bound, not a tuning knob.
+const MAX_REQUEST_URL_CHARS = 4096;
 const QUICK_ADD_VALIDATE_TIMEOUT_MS = 7000;
 const ASK_REQUEST_TIMEOUT_MS = 7000;
 const ASK_SSE_IDLE_TIMEOUT_MS = 10000;
@@ -1163,6 +1695,16 @@ const KEEP_WARM_INTERVAL_MS = 60000;
 // Stand-in caller signal for `search()` calls that don't pass one. Module-level
 // and never aborted, so it carries no state between calls.
 const NEVER_ABORTED = new AbortController().signal;
+// Tells /search this client resolves the response's product and collection
+// lanes against the top-level arrays itself, so the lanes need only carry ids.
+// Without it the server repeats every lane entry in full, which roughly doubles
+// the body for entries the client already has. Sent on both search legs so
+// neither pays for the duplication.
+//
+// Opt-in from the client, not a server-side switch: the client is published
+// separately from the worker, so a storefront can be running any earlier
+// version of it. One that never sends this keeps receiving whole entries.
+const LANE_REFERENCES = { lanes: 'ids' };
 // Always defer to what the storefront itself is rendering — same source
 // shop-gpt reads from. Two widgets on the same page would otherwise drift:
 // shop-gpt picks Shopify, evo-search would pick its own override and show
@@ -1293,6 +1835,16 @@ const createEvoSearchAPI = ({ fetch: fetchImpl = window.fetch, baseURL, userId,
         if (!credentialed) {
             setIdentityParams(url);
         }
+        // Measured only here, where the URL is finally assembled: the results-page
+        // leg carries facets, filter selections, a continuation cursor and identity
+        // on top of the query, so its length is not knowable at the call site. A
+        // session context is a ranking hint, so an over-long URL drops the hint
+        // rather than the request — a slightly less personalized answer beats a
+        // refused one.
+        if (url.href.length > MAX_REQUEST_URL_CHARS &&
+            url.searchParams.has('ctx')) {
+            url.searchParams.delete('ctx');
+        }
         const response = await fetchImpl(url, {
             method: 'GET',
             ...(credentialed ? { headers: getHeaders() } : {}),
@@ -1312,9 +1864,21 @@ const createEvoSearchAPI = ({ fetch: fetchImpl = window.fetch, baseURL, userId,
         logger.info('EvoSearch API: Fetching trending searches');
         return getJSON('/trending', 'Trending', undefined, signal);
     };
-    const config = (signal) => {
+    // Held in the gate rather than read off `uiPreferences` at each send site:
+    // that object is captured by value when this API instance is built, and the
+    // widget replaces its own copy after fetching config, so an overlay there
+    // would never reach this closure. The gate starts closed, so a search that
+    // races ahead of the first answer sends nothing — session context is
+    // best-effort ranking input, never a correctness input. `config` is
+    // referenced lazily (only once the probe fires, long after this line runs).
+    const sessionContextGate = createSessionContextGate(uiPreferences, () => config(), () => getSessionContextParam() !== null);
+    const config = async (signal) => {
         logger.info('EvoSearch API: Fetching ask config');
-        return getJSON('/config', 'Config', undefined, signal);
+        const data = await getJSON('/config', 'Config', undefined, signal);
+        // A worker deployed before this gate omits the field; an absent answer
+        // must read as off rather than as an opt-in.
+        sessionContextGate.resolveFrom(data.sessionContextEnabled);
+        return data;
     };
     const searchPageDesign = (signal, previewToken) => {
         logger.info(`EvoSearch API: Fetching ${previewToken ? 'preview' : 'published'} search page design`);
@@ -1384,11 +1948,38 @@ const createEvoSearchAPI = ({ fetch: fetchImpl = window.fetch, baseURL, userId,
     };
     const deleteRecent = (value) => sendMutation('/user/recents', 'DeleteRecent', 'DELETE', { value });
     const clearRecents = () => sendMutation('/user/recents', 'ClearRecents', 'DELETE');
+    // The single decision point for whether a request carries the shopper's
+    // session context, shared by both search legs so the autocomplete and
+    // results-page requests cannot drift apart on when it is sent — the results
+    // page is where a shopper spends the most time, so a leg without it is a
+    // silently unpersonalized surface.
+    //
+    // Best-effort shopper context (recently viewed, past queries, entry page)
+    // for server-side ranking, capped well under 2KB by session-context.ts.
+    // Carried as a query param rather than a header so /search stays a
+    // CORS-simple request — no OPTIONS preflight on the per-keystroke hot path.
+    // Omitted while there's nothing to say yet. Gated on the server, which is
+    // the only side that knows whether a `ctx` consumer is live: sending browsing
+    // history nobody reads is pure cost and pure exposure. The merchant
+    // preference is an explicit override in both directions — set, it wins;
+    // absent (the normal state), the server decides.
+    const withSessionContext = (params) => {
+        if (!sessionContextGate.shouldSend()) {
+            return params;
+        }
+        const ctxParam = getSessionContextParam();
+        return ctxParam ? { ...params, ctx: ctxParam } : params;
+    };
     // Resilience lives here, not at each call site, so no consumer can opt out —
     // the headless channel previously had no deadline and no retry.
     const search = async (query, limit = 24, signal) => {
         logger.info(`EvoSearch API: Search request - query length: ${query.length}, limit: ${limit}`);
-        const data = await withSearchResilience((attemptSignal) => getJSON('/search', 'Search', { q: query, limit: String(limit) }, attemptSignal), 
+        const searchParams = withSessionContext({
+            q: query,
+            limit: String(limit),
+            ...LANE_REFERENCES,
+        });
+        const data = await withSearchResilience((attemptSignal) => getJSON('/search', 'Search', searchParams, attemptSignal), 
         // Shared stand-in is safe: the wrapper removes its abort listener per attempt.
         signal !== null && signal !== void 0 ? signal : NEVER_ABORTED);
         logger.info(`EvoSearch API: Search success - ${data.llmSuggestions.length} suggestions, ${data.products.length} products`);
@@ -1402,6 +1993,7 @@ const createEvoSearchAPI = ({ fetch: fetchImpl = window.fetch, baseURL, userId,
         const params = {
             q: query,
             facets: '1',
+            ...LANE_REFERENCES,
         };
         if (options.limit != null) {
             params['limit'] = String(options.limit);
@@ -1435,7 +2027,12 @@ const createEvoSearchAPI = ({ fetch: fetchImpl = window.fetch, baseURL, userId,
         if ((filters === null || filters === void 0 ? void 0 : filters.priceMax) != null) {
             params['priceMax'] = String(filters.priceMax);
         }
-        return withSearchResilience((attemptSignal) => getJSON('/search', 'SearchResults', params, attemptSignal), (_f = options.signal) !== null && _f !== void 0 ? _f : NEVER_ABORTED);
+        return withSearchResilience((attemptSignal) => getJSON('/search', 'SearchResults', 
+        // Applied per attempt, and to every page: a continuation (cursor) or
+        // a numbered page (offset) is the same result set the shopper is
+        // still reading, so dropping the context there would re-rank the
+        // next page against a different profile than the first.
+        withSessionContext(params), attemptSignal), (_f = options.signal) !== null && _f !== void 0 ? _f : NEVER_ABORTED);
     };
     // Same deadline as `validateQuickAdd`, and for the same reason: the only
     // caller passes no signal, so without one a stalled request never settles —
@@ -1692,7 +2289,7 @@ const createEvoSearchAPI = ({ fetch: fetchImpl = window.fetch, baseURL, userId,
             .catch(logger.error);
         // Also send to analytics via sendTag
         sendTag({
-            eventId: crypto.randomUUID(),
+            eventId: mintId(),
             eventName: action,
             data: {
                 ...actionData,
@@ -1760,6 +2357,17 @@ const parseSseFrame = (frame) => {
     }
 };
 
+const FORCED_KEY = 'evsUiVersion';
+// ?evs=reset must also drop the QA force so a shopper returns to the configured version.
+const clearForcedUiVersion = () => {
+    try {
+        sessionStorage.removeItem(FORCED_KEY);
+    }
+    catch {
+        /* no-op: storage unavailable */
+    }
+};
+
 const error = (message) => console.error(message);
 // Headless hosts render their own UI, so nothing else pings /warm for them.
 let disposeKeepWarm;
@@ -1832,6 +2440,7 @@ const init = (params) => {
             try {
                 sessionStorage.removeItem(previewKeyName);
                 sessionStorage.removeItem(disableKeyName);
+                clearForcedUiVersion();
                 logger.info('EvoSearch SDK: Reset to configured state via ?evs=reset URL param');
             }
             catch {
@@ -1851,6 +2460,13 @@ const init = (params) => {
         if (hasPreview) {
             logger.info('EvoSearch SDK: Preview mode enabled via sessionStorage');
         }
+        // Before the UI/headless fork: a headless host returns early below, and
+        // its shoppers browse product pages exactly like everyone else's. Not
+        // gated on the session-context opt-in — that flag gates the TRANSPORT
+        // (api.ts decides whether the context leaves the browser), and gating
+        // capture too would leave a merchant who turns it on with an empty
+        // history until the shopper navigates again.
+        startProductViewCapture();
         const evoSearchAPI = createEvoSearchAPI({
             baseURL: params.baseUrl,
             userId: params.userId,
@@ -1862,7 +2478,7 @@ const init = (params) => {
         const uiImplementation = window[registryKey].ui;
         const headless = !uiImplementation;
         params.sendTag({
-            eventId: crypto.randomUUID(),
+            eventId: mintId(),
             eventName: 'evoSearchInitialized',
             data: { mode, hasPreview, headless },
             providers: { evoSearch: true },
@@ -1894,7 +2510,7 @@ const init = (params) => {
             visualSearchEnabled,
         });
         params.sendTag({
-            eventId: crypto.randomUUID(),
+            eventId: mintId(),
             eventName: 'evoSearchLoaded',
             data: {},
             providers: { evoSearch: true },
@@ -1914,7 +2530,7 @@ const init = (params) => {
 const tag = ({ data }) => {
     try {
         return {
-            sdkVersion: "1.70.2" || '',
+            sdkVersion: "1.71.1" || '',
             searchQuery: data['searchQuery'],
             searchResults: data['searchResults'],
             timestamp: Date.now(),
@@ -1923,7 +2539,7 @@ const tag = ({ data }) => {
     catch (err) {
         console.error(`EvoSearch SDK: Tagging failed - ${err}`);
         return {
-            sdkVersion: "1.70.2" ,
+            sdkVersion: "1.71.1" ,
             timestamp: Date.now(),
         };
     }