@kharon-labs/browser 0.1.0 → 0.2.0

package/README.md

@@ -8,7 +8,9 @@ then measures it against a holdout.
 npm install @kharon-labs/browser
 ```
 
-On a site without a bundler, use the script-tag build at `https://kharonlabs.com/sdk/v1.js`.
+On a site without a bundler, use the script-tag build at `https://kharonlabs.com/sdk/v1.js`. On a
+React site (including Next.js and React Native Web), use
+[`@kharon-labs/react`](https://www.npmjs.com/package/@kharon-labs/react), which is built on this package.
 
 ## Plain HTML
 
@@ -44,6 +46,7 @@ conversion("demo_booked");
 | `init({ key, apiBase?, consent?, timeoutMs?, pageId?, cookieDomain? })` | Resolves the page's slots once the DOM is ready and starts measuring if allowed. |
 | `setConsent("granted" \| "denied" \| "unknown")` | Forward your consent tool's answer. Safe to call before `init`. |
 | `conversion(goal, value?)` | Records a goal. Forms with `data-ge-goal="…"` record theirs on submit. |
+| `signup()` | Records a `signup` conversion. Prefer `recordSignup` in `@kharon-labs/server`, which counts only signups that succeeded. |
 | `refresh()` | Re-scans and re-resolves, e.g. after a client-side route change. |
 
 ## Slots
@@ -56,6 +59,13 @@ conversion("demo_booked");
 - The markup's own text is the default. A field the variant doesn't set keeps it, and a slot the
   console doesn't know yet keeps all of it.
 
+## Single-page apps
+
+The package scans the page once, when the DOM is ready. After a client-side route change that mounts
+new slots, call `refresh()`. On React Native Web, a `dataSet={{ geSlot: "hero" }}` prop renders
+`data-ge-slot="hero"`; React Native's types don't declare `dataSet`, so add it with a module
+augmentation (or use `@kharon-labs/react`, which needs no DOM attributes).
+
 ## Guarantees
 
 - **Defaults always render.** If we answer late (after `timeoutMs`, 500 ms), fail or are down, the
@@ -64,6 +74,9 @@ conversion("demo_booked");
   and Switzerland, GPC honored). Until it allows storing the visitor, the package writes no cookie
   or storage and sends no analytics.
 - **Holdouts.** Held-out visitors see the defaults; their impressions record the variant withheld.
+- **Acquisition.** A session's first page view records how it arrived: `utm_*` tags, which ad
+  network's click id was present (never the id), a Kharon campaign link, and the referring site's
+  host. Never the URL's path or other parameters.
 
 The visitor id is a first-party `ge_vid` cookie on your domain (one year; Safari caps script-set
 cookies at seven days, `@kharon-labs/server` avoids that). A denial deletes it.
@@ -72,3 +85,15 @@ cookies at seven days, `@kharon-labs/server` avoids that). A denial deletes it.
 
 About 4 KB gzip, no dependencies. ES2020 browsers; without `fetch` the page keeps its defaults, and
 without `IntersectionObserver` impressions aren't recorded.
+
+## Your privacy policy
+
+Adding Kharon Labs sets a first-party cookie and sends visit data to us, so your
+privacy policy should say so. A paragraph to adapt (not legal advice):
+
+> We use Kharon Labs to tailor parts of this website to the organization a visit comes from and to
+> measure whether that helps. Kharon Labs processes your IP address, browser details, the page you
+> visit and how you arrived, and infers your organization (not you personally). With your consent
+> where required, it stores a random visitor ID in a first-party cookie (`ge_vid`) and records page
+> views and interactions. See https://kharonlabs.com/privacy for what Kharon Labs collects and how
+> long it keeps it.

package/dist/index.cjs

@@ -36,10 +36,69 @@ __export(index_exports, {
   refresh: () => refresh,
   reveal: () => reveal,
   scanSlots: () => scanSlots,
-  setConsent: () => setConsent
+  setConsent: () => setConsent,
+  signup: () => signup
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/engine/analytics/types.ts
+var SIGNUP_GOAL = "signup";
+
+// src/engine/analytics/touch.ts
+var MAX_TOUCH_VALUE = 100;
+var CLICK_ID_PARAMS = {
+  gclid: "google",
+  gbraid: "google",
+  wbraid: "google",
+  msclkid: "microsoft",
+  fbclid: "meta",
+  li_fat_id: "linkedin",
+  ttclid: "tiktok",
+  twclid: "x"
+};
+var CLICK_ID_KINDS = new Set(Object.values(CLICK_ID_PARAMS));
+var UTM_FIELDS = ["source", "medium", "campaign", "term", "content"];
+var KHARON_LINK_PARAM = "ge_co";
+function touchFromUrl(url, referrer) {
+  const touch = {};
+  let page;
+  try {
+    page = new URL(url);
+  } catch {
+    return touch;
+  }
+  for (const field of UTM_FIELDS) {
+    const value = clean(page.searchParams.get(`utm_${field}`));
+    if (value) touch[field] = value;
+  }
+  for (const [param, kind] of Object.entries(CLICK_ID_PARAMS)) {
+    if (page.searchParams.get(param)) {
+      touch.clickId = kind;
+      break;
+    }
+  }
+  if (page.searchParams.get(KHARON_LINK_PARAM)) touch.kharonLink = true;
+  const from = referrerHost(referrer);
+  if (from && from !== bareHost(page.hostname)) touch.referrer = from;
+  return touch;
+}
+function clean(value) {
+  const trimmed = value?.replace(/[\u0000-\u001f\u007f]/g, "").trim();
+  return trimmed ? trimmed.slice(0, MAX_TOUCH_VALUE) : null;
+}
+function referrerHost(referrer) {
+  if (!referrer) return null;
+  try {
+    const { protocol, hostname } = new URL(referrer);
+    return protocol === "http:" || protocol === "https:" ? bareHost(hostname) : null;
+  } catch {
+    return null;
+  }
+}
+function bareHost(hostname) {
+  return hostname.toLowerCase().replace(/^www\./, "");
+}
+
 // src/engine/analytics/beacon.ts
 var BEACON_VERSION = 1;
 var MAX_BEACON_EVENTS = 50;
@@ -48,7 +107,9 @@ var SLOT_ATTRIBUTES = {
   variant: "data-ge-variant",
   counterfactual: "data-ge-counterfactual",
   /** Why the slot shows what it shows (matched, default, holdout). For debugging; not sent. */
-  reason: "data-ge-reason"
+  reason: "data-ge-reason",
+  /** Which step of the fallback ladder chose the content (exact, near, segment, default). Sent on impressions. */
+  rung: "data-ge-rung"
 };
 
 // packages/browser/src/tracker.ts
@@ -67,7 +128,7 @@ function startTracker({
   crossOrigin = false
 }) {
   const win = root.defaultView ?? window;
-  const sessionId = sessionIdFor(win);
+  const { id: sessionId, started } = sessionFor(win);
   const queue = [];
   const seenSlots = /* @__PURE__ */ new Set();
   const push = (type, body) => {
@@ -77,7 +138,7 @@ function startTracker({
   const flush = () => {
     while (queue.length) send(win, endpoint, envelope(queue.splice(0, MAX_BEACON_EVENTS)), crossOrigin);
   };
-  push("page_view", { pageId, configVersion });
+  push("page_view", started ? { pageId, configVersion, touch: touchFromUrl(win.location.href, root.referrer) } : { pageId, configVersion });
   const slots = Array.from(root.querySelectorAll(`[${SLOT_ATTRIBUTES.slot}]`));
   const observer = "IntersectionObserver" in win ? new win.IntersectionObserver(
     (entries) => {
@@ -143,22 +204,23 @@ function readSlot(el) {
   return {
     slotId,
     variantId: el.getAttribute(SLOT_ATTRIBUTES.variant) || null,
-    counterfactualVariantId: el.getAttribute(SLOT_ATTRIBUTES.counterfactual) || null
+    counterfactualVariantId: el.getAttribute(SLOT_ATTRIBUTES.counterfactual) || null,
+    ...el.getAttribute(SLOT_ATTRIBUTES.rung) ? { rung: el.getAttribute(SLOT_ATTRIBUTES.rung) } : {}
   };
 }
 function closestSlot(target) {
   const el = target instanceof Element ? target.closest(`[${SLOT_ATTRIBUTES.slot}]`) : null;
   return el ? readSlot(el) : null;
 }
-function sessionIdFor(win) {
+function sessionFor(win) {
   try {
     const existing = win.sessionStorage.getItem(SESSION_KEY);
-    if (existing) return existing;
+    if (existing) return { id: existing, started: false };
     const id = uuid(win);
     win.sessionStorage.setItem(SESSION_KEY, id);
-    return id;
+    return { id, started: true };
   } catch {
-    return uuid(win);
+    return { id: uuid(win), started: true };
   }
 }
 function uuid(win) {
@@ -204,6 +266,7 @@ function hashSlotDefaults(content) {
 var RESOLVE_PATH = "/api/v1/resolve";
 var COLLECT_V2_PATH = "/api/v1/collect";
 var REASONS = ["matched", "default", "holdout"];
+var RUNGS = ["exact", "near", "segment", "default"];
 function parseResolveResponse(body) {
   if (!isRecord(body) || body.v !== RESOLVE_API_VERSION || !isRecord(body.decisions)) return null;
   if (!Number.isSafeInteger(body.configVersion) || typeof body.persist !== "boolean") return null;
@@ -216,7 +279,10 @@ function parseResolveResponse(body) {
     if (decision) decisions[id] = decision;
   }
   const m = persist && typeof body.m === "string" && body.m.length <= 1024 ? body.m : void 0;
-  if (body.preview === true) return { v: RESOLVE_API_VERSION, configVersion: body.configVersion, persist: false, preview: true, decisions };
+  if (body.preview === true) {
+    const explain = isRecord(body.explain) ? body.explain : void 0;
+    return { v: RESOLVE_API_VERSION, configVersion: body.configVersion, persist: false, preview: true, decisions, ...explain ? { explain } : {} };
+  }
   return { v: RESOLVE_API_VERSION, configVersion: body.configVersion, persist, vid, ...pin ? { pin } : {}, decisions, ...m ? { m } : {} };
 }
 function parseDecision(raw) {
@@ -225,10 +291,12 @@ function parseDecision(raw) {
   if (!REASONS.includes(raw.reason)) return null;
   const content = {};
   for (const [field, value] of Object.entries(raw.content)) if (typeof value === "string") content[field] = value;
+  const rung = RUNGS.includes(raw.rung) ? raw.rung : void 0;
   return {
     variantId: raw.variantId,
     counterfactualVariantId: raw.counterfactualVariantId,
     reason: raw.reason,
+    ...rung && { rung },
     content
   };
 }
@@ -274,6 +342,7 @@ function createClient(options) {
     if (response.preview) {
       previewing = true;
       stopTracking(true);
+      if (response.explain) win.console?.info("[kharon] debug link: why this page shows what it does", response.explain);
       return;
     }
     if (response.persist && response.vid && consent !== "denied") {
@@ -479,6 +548,8 @@ function applyDecision(el, decision, baseURI) {
   el.setAttribute(SLOT_ATTRIBUTES.variant, decision.variantId ?? "");
   el.setAttribute(SLOT_ATTRIBUTES.counterfactual, decision.counterfactualVariantId ?? "");
   el.setAttribute(SLOT_ATTRIBUTES.reason, decision.reason);
+  if (decision.rung) el.setAttribute(SLOT_ATTRIBUTES.rung, decision.rung);
+  else el.removeAttribute(SLOT_ATTRIBUTES.rung);
 }
 function reveal(root) {
   root.getElementById(ANTI_FLICKER_ID)?.remove();
@@ -574,6 +645,9 @@ function setConsent(consent) {
 function conversion(goal, value) {
   current?.conversion(goal, value);
 }
+function signup() {
+  current?.conversion(SIGNUP_GOAL);
+}
 function refresh() {
   return current?.refresh() ?? Promise.resolve();
 }

package/dist/index.d.ts

@@ -1,9 +1,52 @@
-type ConsentChoice = "granted" | "denied" | "unknown";
+type SignalSource = "campaign_link" | "form_email" | "known_visitor" | "reverse_ip" | "referrer";
+type AttributeKey = "company.domain" | "company.name" | "company.legalName" | "company.industry"
+/** NAICS sector id ("finance", "health-care"), rolled up from `company.naics` by `naicsSector`. */
+ | "company.sector" | "company.naics" | "company.sic" | "company.employeeCount" | "company.employeeBand" | "company.revenueBand" | "company.country" | "company.region" | "company.city" | "company.founded" | "company.ownership" | "company.ticker" | "crm.lists" | "crm.stage" | "crm.owner" | "crm.isCustomer" | "visitor.role" | "visitor.networkType" | "visitor.identified" | "visitor.country" | "intent.campaign" | "intent.utmSource" | "intent.utmMedium" | "intent.utmTerm" | "intent.referrerHost";
+type AttributeValue = string | number | boolean;
+type ListAttributeKey = "crm.lists";
+type ScalarAttributeKey = Exclude<AttributeKey, ListAttributeKey>;
+type IdentityContext = Partial<Record<ScalarAttributeKey, AttributeValue>> & Partial<Record<ListAttributeKey, string[]>>;
+type Condition = ({
+	attr: ScalarAttributeKey;
+	op: "eq";
+	value: AttributeValue;
+} | {
+	attr: ScalarAttributeKey;
+	op: "in";
+	value: AttributeValue[];
+}
+/** `startsWith` is a prefix match, for hierarchical codes: NAICS "51" covers "5112". */
+ | {
+	attr: ScalarAttributeKey;
+	op: "contains" | "startsWith";
+	value: string;
+} | {
+	attr: ScalarAttributeKey;
+	op: "gte" | "lte";
+	value: number;
+}
+/** The list attribute holds this id, e.g. the account is on CRM list "hs-123". */
+ | {
+	attr: ListAttributeKey;
+	op: "has";
+	value: string;
+} | {
+	attr: AttributeKey;
+	op: "exists";
+}) & {
+	/**
+	 * For near matching: a visitor who fails this condition never gets a near match. Exact matching
+	 * ignores it. Conditions under `not` are always required.
+	 */
+	required?: boolean;
+};
 type SlotContent = Record<string, string>;
+type VariantStatus = "draft" | "live" | "paused" | "retired";
 type DecisionReason = "matched" | "default" | "holdout";
+type DecisionRung = "exact" | "near" | "segment" | "default";
 interface Decision {
 	slotId: string;
-	/** The variant shown, or null when default content was shown. */
+	/** The variant or segment row (`seg:…`) shown, or null when default content was shown. */
 	variantId: string | null;
 	/**
 	 * For holdout visitors: the variant they *would* have seen. This is the control group for that
@@ -11,9 +54,65 @@ interface Decision {
 	 */
 	counterfactualVariantId: string | null;
 	reason: DecisionReason;
+	rung: DecisionRung;
 	/** Content with all tokens rendered. */
 	content: SlotContent;
 }
+type ConsentChoice = "granted" | "denied" | "unknown";
+type CandidateOutcome = "wins" | "outranked" | "skipped" | "held-out";
+type ExplainOutcome = Exclude<CandidateOutcome, "held-out"> | "no-match" | "not-live";
+interface ConditionExplanation {
+	attr: AttributeKey;
+	op: Condition["op"];
+	/** The rule's value; absent for `exists`. */
+	value?: Extract<Condition, {
+		value: unknown;
+	}>["value"];
+	/** The visitor's value for `attr`, or null when they have none. */
+	actual: AttributeValue | string[] | null;
+	/** Whether this condition alone holds. Null when the attribute can't be known here (see `unavailable`). */
+	matched: boolean | null;
+}
+interface AudienceExplanation {
+	id: string;
+	name: string;
+	matched: boolean;
+	/** Some condition reads an attribute this explanation can't see, so `matched` may be wrong for real visitors. */
+	unknown: boolean;
+	/** Every leaf condition of the rule, in order. `not`, `any` and `all` are folded into `matched`. */
+	conditions: ConditionExplanation[];
+}
+interface VariantExplanation {
+	variantId: string;
+	audienceId: string;
+	status: VariantStatus;
+	/** Whether the variant's audience matches this visitor, whatever its status. */
+	audienceMatched: boolean;
+	outcome: ExplainOutcome;
+	/** For `skipped`: the attributes with no value and no fallback that stopped it rendering. */
+	missing?: string[];
+}
+interface SlotExplanation {
+	/** The variant or segment row (`seg:…`) shown, or null for default content. */
+	variantId: string | null;
+	reason: DecisionReason;
+	/** The step of the fallback ladder that chose the content. */
+	rung: DecisionRung;
+	/** The text each field shows. */
+	content: Record<string, string>;
+	variants: VariantExplanation[];
+}
+interface SiteExplanation {
+	company: {
+		domain: string;
+		source: SignalSource;
+		confidence: number;
+	} | null;
+	/** The flat attributes audiences and templates see. */
+	context: IdentityContext;
+	audiences: AudienceExplanation[];
+	slots: Record<string, SlotExplanation>;
+}
 declare const RESOLVE_API_VERSION = 1;
 interface DeclaredSlot {
 	id: string;
@@ -40,8 +139,11 @@ export interface ResolveRequest {
 	/** The session's config pin from an earlier response (`"<version>.<epoch>"`), to keep its copy stable. */
 	pin?: string;
 }
-/** What one slot shows. The same fields `<Slot>` writes as `data-ge-*` attributes. */
-export type ResolvedSlot = Pick<Decision, "variantId" | "counterfactualVariantId" | "reason" | "content">;
+/**
+ * What one slot shows. The same fields `<Slot>` writes as `data-ge-*` attributes. `rung` is absent in
+ * answers from servers that predate the fallback ladder.
+ */
+export type ResolvedSlot = Pick<Decision, "variantId" | "counterfactualVariantId" | "reason" | "content"> & Partial<Pick<Decision, "rung">>;
 export interface ResolveResponse {
 	v: typeof RESOLVE_API_VERSION;
 	/** Published config version the decisions came from; 0 when the site has never published. */
@@ -64,6 +166,11 @@ export interface ResolveResponse {
 	 * for a synthetic visitor. The package stores nothing, forgets nothing and doesn't measure.
 	 */
 	preview?: true;
+	/**
+	 * A debug link (docs/design/resolve-debug): why each requested slot shows what it does to this
+	 * request, resolved from what our CDN saw. Only with `preview`; the browser SDK logs it to the console.
+	 */
+	explain?: SiteExplanation;
 }
 /**
  * A short, stable fingerprint of a slot's defaults, so resolve can tell when the code and the
@@ -154,6 +261,11 @@ export declare function init(options: KharonOptions): Kharon;
 /** Same as `instance.setConsent`. Safe to call before `init`; the choice is used by the first resolve. */
 export declare function setConsent(consent: Consent): void;
 export declare function conversion(goal: string, value?: number): void;
+/**
+ * Records a signup from the page. Prefer `recordSignup` in `@kharon-labs/server` from your signup
+ * handler: it counts only signups that succeeded, and ones whose browser blocks scripts.
+ */
+export declare function signup(): void;
 export declare function refresh(): Promise<void>;
 
 export {};

package/dist/index.js

@@ -1,3 +1,61 @@
+// src/engine/analytics/types.ts
+var SIGNUP_GOAL = "signup";
+
+// src/engine/analytics/touch.ts
+var MAX_TOUCH_VALUE = 100;
+var CLICK_ID_PARAMS = {
+  gclid: "google",
+  gbraid: "google",
+  wbraid: "google",
+  msclkid: "microsoft",
+  fbclid: "meta",
+  li_fat_id: "linkedin",
+  ttclid: "tiktok",
+  twclid: "x"
+};
+var CLICK_ID_KINDS = new Set(Object.values(CLICK_ID_PARAMS));
+var UTM_FIELDS = ["source", "medium", "campaign", "term", "content"];
+var KHARON_LINK_PARAM = "ge_co";
+function touchFromUrl(url, referrer) {
+  const touch = {};
+  let page;
+  try {
+    page = new URL(url);
+  } catch {
+    return touch;
+  }
+  for (const field of UTM_FIELDS) {
+    const value = clean(page.searchParams.get(`utm_${field}`));
+    if (value) touch[field] = value;
+  }
+  for (const [param, kind] of Object.entries(CLICK_ID_PARAMS)) {
+    if (page.searchParams.get(param)) {
+      touch.clickId = kind;
+      break;
+    }
+  }
+  if (page.searchParams.get(KHARON_LINK_PARAM)) touch.kharonLink = true;
+  const from = referrerHost(referrer);
+  if (from && from !== bareHost(page.hostname)) touch.referrer = from;
+  return touch;
+}
+function clean(value) {
+  const trimmed = value?.replace(/[\u0000-\u001f\u007f]/g, "").trim();
+  return trimmed ? trimmed.slice(0, MAX_TOUCH_VALUE) : null;
+}
+function referrerHost(referrer) {
+  if (!referrer) return null;
+  try {
+    const { protocol, hostname } = new URL(referrer);
+    return protocol === "http:" || protocol === "https:" ? bareHost(hostname) : null;
+  } catch {
+    return null;
+  }
+}
+function bareHost(hostname) {
+  return hostname.toLowerCase().replace(/^www\./, "");
+}
+
 // src/engine/analytics/beacon.ts
 var BEACON_VERSION = 1;
 var MAX_BEACON_EVENTS = 50;
@@ -6,7 +64,9 @@ var SLOT_ATTRIBUTES = {
   variant: "data-ge-variant",
   counterfactual: "data-ge-counterfactual",
   /** Why the slot shows what it shows (matched, default, holdout). For debugging; not sent. */
-  reason: "data-ge-reason"
+  reason: "data-ge-reason",
+  /** Which step of the fallback ladder chose the content (exact, near, segment, default). Sent on impressions. */
+  rung: "data-ge-rung"
 };
 
 // packages/browser/src/tracker.ts
@@ -25,7 +85,7 @@ function startTracker({
   crossOrigin = false
 }) {
   const win = root.defaultView ?? window;
-  const sessionId = sessionIdFor(win);
+  const { id: sessionId, started } = sessionFor(win);
   const queue = [];
   const seenSlots = /* @__PURE__ */ new Set();
   const push = (type, body) => {
@@ -35,7 +95,7 @@ function startTracker({
   const flush = () => {
     while (queue.length) send(win, endpoint, envelope(queue.splice(0, MAX_BEACON_EVENTS)), crossOrigin);
   };
-  push("page_view", { pageId, configVersion });
+  push("page_view", started ? { pageId, configVersion, touch: touchFromUrl(win.location.href, root.referrer) } : { pageId, configVersion });
   const slots = Array.from(root.querySelectorAll(`[${SLOT_ATTRIBUTES.slot}]`));
   const observer = "IntersectionObserver" in win ? new win.IntersectionObserver(
     (entries) => {
@@ -101,22 +161,23 @@ function readSlot(el) {
   return {
     slotId,
     variantId: el.getAttribute(SLOT_ATTRIBUTES.variant) || null,
-    counterfactualVariantId: el.getAttribute(SLOT_ATTRIBUTES.counterfactual) || null
+    counterfactualVariantId: el.getAttribute(SLOT_ATTRIBUTES.counterfactual) || null,
+    ...el.getAttribute(SLOT_ATTRIBUTES.rung) ? { rung: el.getAttribute(SLOT_ATTRIBUTES.rung) } : {}
   };
 }
 function closestSlot(target) {
   const el = target instanceof Element ? target.closest(`[${SLOT_ATTRIBUTES.slot}]`) : null;
   return el ? readSlot(el) : null;
 }
-function sessionIdFor(win) {
+function sessionFor(win) {
   try {
     const existing = win.sessionStorage.getItem(SESSION_KEY);
-    if (existing) return existing;
+    if (existing) return { id: existing, started: false };
     const id = uuid(win);
     win.sessionStorage.setItem(SESSION_KEY, id);
-    return id;
+    return { id, started: true };
   } catch {
-    return uuid(win);
+    return { id: uuid(win), started: true };
   }
 }
 function uuid(win) {
@@ -162,6 +223,7 @@ function hashSlotDefaults(content) {
 var RESOLVE_PATH = "/api/v1/resolve";
 var COLLECT_V2_PATH = "/api/v1/collect";
 var REASONS = ["matched", "default", "holdout"];
+var RUNGS = ["exact", "near", "segment", "default"];
 function parseResolveResponse(body) {
   if (!isRecord(body) || body.v !== RESOLVE_API_VERSION || !isRecord(body.decisions)) return null;
   if (!Number.isSafeInteger(body.configVersion) || typeof body.persist !== "boolean") return null;
@@ -174,7 +236,10 @@ function parseResolveResponse(body) {
     if (decision) decisions[id] = decision;
   }
   const m = persist && typeof body.m === "string" && body.m.length <= 1024 ? body.m : void 0;
-  if (body.preview === true) return { v: RESOLVE_API_VERSION, configVersion: body.configVersion, persist: false, preview: true, decisions };
+  if (body.preview === true) {
+    const explain = isRecord(body.explain) ? body.explain : void 0;
+    return { v: RESOLVE_API_VERSION, configVersion: body.configVersion, persist: false, preview: true, decisions, ...explain ? { explain } : {} };
+  }
   return { v: RESOLVE_API_VERSION, configVersion: body.configVersion, persist, vid, ...pin ? { pin } : {}, decisions, ...m ? { m } : {} };
 }
 function parseDecision(raw) {
@@ -183,10 +248,12 @@ function parseDecision(raw) {
   if (!REASONS.includes(raw.reason)) return null;
   const content = {};
   for (const [field, value] of Object.entries(raw.content)) if (typeof value === "string") content[field] = value;
+  const rung = RUNGS.includes(raw.rung) ? raw.rung : void 0;
   return {
     variantId: raw.variantId,
     counterfactualVariantId: raw.counterfactualVariantId,
     reason: raw.reason,
+    ...rung && { rung },
     content
   };
 }
@@ -232,6 +299,7 @@ function createClient(options) {
     if (response.preview) {
       previewing = true;
       stopTracking(true);
+      if (response.explain) win.console?.info("[kharon] debug link: why this page shows what it does", response.explain);
       return;
     }
     if (response.persist && response.vid && consent !== "denied") {
@@ -437,6 +505,8 @@ function applyDecision(el, decision, baseURI) {
   el.setAttribute(SLOT_ATTRIBUTES.variant, decision.variantId ?? "");
   el.setAttribute(SLOT_ATTRIBUTES.counterfactual, decision.counterfactualVariantId ?? "");
   el.setAttribute(SLOT_ATTRIBUTES.reason, decision.reason);
+  if (decision.rung) el.setAttribute(SLOT_ATTRIBUTES.rung, decision.rung);
+  else el.removeAttribute(SLOT_ATTRIBUTES.rung);
 }
 function reveal(root) {
   root.getElementById(ANTI_FLICKER_ID)?.remove();
@@ -532,6 +602,9 @@ function setConsent(consent) {
 function conversion(goal, value) {
   current?.conversion(goal, value);
 }
+function signup() {
+  current?.conversion(SIGNUP_GOAL);
+}
 function refresh() {
   return current?.refresh() ?? Promise.resolve();
 }
@@ -552,5 +625,6 @@ export {
   refresh,
   reveal,
   scanSlots,
-  setConsent
+  setConsent,
+  signup
 };

package/dist/tracker.cjs

@@ -27,6 +27,61 @@ __export(tracker_exports, {
 });
 module.exports = __toCommonJS(tracker_exports);
 
+// src/engine/analytics/touch.ts
+var MAX_TOUCH_VALUE = 100;
+var CLICK_ID_PARAMS = {
+  gclid: "google",
+  gbraid: "google",
+  wbraid: "google",
+  msclkid: "microsoft",
+  fbclid: "meta",
+  li_fat_id: "linkedin",
+  ttclid: "tiktok",
+  twclid: "x"
+};
+var CLICK_ID_KINDS = new Set(Object.values(CLICK_ID_PARAMS));
+var UTM_FIELDS = ["source", "medium", "campaign", "term", "content"];
+var KHARON_LINK_PARAM = "ge_co";
+function touchFromUrl(url, referrer) {
+  const touch = {};
+  let page;
+  try {
+    page = new URL(url);
+  } catch {
+    return touch;
+  }
+  for (const field of UTM_FIELDS) {
+    const value = clean(page.searchParams.get(`utm_${field}`));
+    if (value) touch[field] = value;
+  }
+  for (const [param, kind] of Object.entries(CLICK_ID_PARAMS)) {
+    if (page.searchParams.get(param)) {
+      touch.clickId = kind;
+      break;
+    }
+  }
+  if (page.searchParams.get(KHARON_LINK_PARAM)) touch.kharonLink = true;
+  const from = referrerHost(referrer);
+  if (from && from !== bareHost(page.hostname)) touch.referrer = from;
+  return touch;
+}
+function clean(value) {
+  const trimmed = value?.replace(/[\u0000-\u001f\u007f]/g, "").trim();
+  return trimmed ? trimmed.slice(0, MAX_TOUCH_VALUE) : null;
+}
+function referrerHost(referrer) {
+  if (!referrer) return null;
+  try {
+    const { protocol, hostname } = new URL(referrer);
+    return protocol === "http:" || protocol === "https:" ? bareHost(hostname) : null;
+  } catch {
+    return null;
+  }
+}
+function bareHost(hostname) {
+  return hostname.toLowerCase().replace(/^www\./, "");
+}
+
 // src/engine/analytics/beacon.ts
 var BEACON_VERSION = 1;
 var MAX_BEACON_EVENTS = 50;
@@ -35,7 +90,9 @@ var SLOT_ATTRIBUTES = {
   variant: "data-ge-variant",
   counterfactual: "data-ge-counterfactual",
   /** Why the slot shows what it shows (matched, default, holdout). For debugging; not sent. */
-  reason: "data-ge-reason"
+  reason: "data-ge-reason",
+  /** Which step of the fallback ladder chose the content (exact, near, segment, default). Sent on impressions. */
+  rung: "data-ge-rung"
 };
 
 // packages/browser/src/tracker.ts
@@ -54,7 +111,7 @@ function startTracker({
   crossOrigin = false
 }) {
   const win = root.defaultView ?? window;
-  const sessionId = sessionIdFor(win);
+  const { id: sessionId, started } = sessionFor(win);
   const queue = [];
   const seenSlots = /* @__PURE__ */ new Set();
   const push = (type, body) => {
@@ -64,7 +121,7 @@ function startTracker({
   const flush = () => {
     while (queue.length) send(win, endpoint, envelope(queue.splice(0, MAX_BEACON_EVENTS)), crossOrigin);
   };
-  push("page_view", { pageId, configVersion });
+  push("page_view", started ? { pageId, configVersion, touch: touchFromUrl(win.location.href, root.referrer) } : { pageId, configVersion });
   const slots = Array.from(root.querySelectorAll(`[${SLOT_ATTRIBUTES.slot}]`));
   const observer = "IntersectionObserver" in win ? new win.IntersectionObserver(
     (entries) => {
@@ -130,22 +187,23 @@ function readSlot(el) {
   return {
     slotId,
     variantId: el.getAttribute(SLOT_ATTRIBUTES.variant) || null,
-    counterfactualVariantId: el.getAttribute(SLOT_ATTRIBUTES.counterfactual) || null
+    counterfactualVariantId: el.getAttribute(SLOT_ATTRIBUTES.counterfactual) || null,
+    ...el.getAttribute(SLOT_ATTRIBUTES.rung) ? { rung: el.getAttribute(SLOT_ATTRIBUTES.rung) } : {}
   };
 }
 function closestSlot(target) {
   const el = target instanceof Element ? target.closest(`[${SLOT_ATTRIBUTES.slot}]`) : null;
   return el ? readSlot(el) : null;
 }
-function sessionIdFor(win) {
+function sessionFor(win) {
   try {
     const existing = win.sessionStorage.getItem(SESSION_KEY);
-    if (existing) return existing;
+    if (existing) return { id: existing, started: false };
     const id = uuid(win);
     win.sessionStorage.setItem(SESSION_KEY, id);
-    return id;
+    return { id, started: true };
   } catch {
-    return uuid(win);
+    return { id: uuid(win), started: true };
   }
 }
 function uuid(win) {

package/dist/tracker.d.ts

@@ -1,4 +1,30 @@
 type SignalSource = "campaign_link" | "form_email" | "known_visitor" | "reverse_ip" | "referrer";
+type DecisionRung = "exact" | "near" | "segment" | "default";
+interface Touch$1 {
+	/** `utm_source`, `utm_medium`, … as tagged, trimmed to `MAX_TOUCH_VALUE` characters. */
+	source?: string;
+	medium?: string;
+	campaign?: string;
+	term?: string;
+	content?: string;
+	/** Which ad network's click id the URL carried (`gclid` → `google`). The id itself is dropped. */
+	clickId?: ClickIdKind;
+	/** The landing URL was one of our campaign links (`?ge_co=`). */
+	kharonLink?: true;
+	/** Host of an external referring page, lowercased and without `www.`. */
+	referrer?: string;
+}
+declare const CLICK_ID_PARAMS: {
+	readonly gclid: "google";
+	readonly gbraid: "google";
+	readonly wbraid: "google";
+	readonly msclkid: "microsoft";
+	readonly fbclid: "meta";
+	readonly li_fat_id: "linkedin";
+	readonly ttclid: "tiktok";
+	readonly twclid: "x";
+};
+type ClickIdKind = (typeof CLICK_ID_PARAMS)[keyof typeof CLICK_ID_PARAMS];
 interface BaseEvent {
 	siteId: string;
 	visitorId: string;
@@ -20,6 +46,11 @@ interface PageViewEvent extends BaseEvent {
 	pageId: string;
 	/** Site config version that was resolved, so results are attributable to what was live. */
 	configVersion: number;
+	/**
+	 * How the session arrived, on its first page view only (`{}` for a direct visit). Absent on later
+	 * page views and from trackers older than signup attribution.
+	 */
+	touch?: Touch$1;
 }
 interface SlotImpressionEvent extends BaseEvent {
 	type: "slot_impression";
@@ -27,6 +58,8 @@ interface SlotImpressionEvent extends BaseEvent {
 	variantId: string | null;
 	/** Set for holdout visitors: the variant withheld from them. See Decision.counterfactualVariantId. */
 	counterfactualVariantId: string | null;
+	/** The fallback-ladder step behind the decision (Decision.rung). Absent from older scripts and events. */
+	rung?: DecisionRung;
 }
 interface InteractionEvent extends BaseEvent {
 	type: "interaction";
@@ -38,9 +71,11 @@ interface ConversionEvent extends BaseEvent {
 	type: "conversion";
 	goal: string;
 	value?: number;
+	/** `server`: confirmed by the site's backend (`POST /api/v1/signups`), not reported by the page. */
+	source?: "server";
 }
 type AnalyticsEvent = PageViewEvent | SlotImpressionEvent | InteractionEvent | ConversionEvent;
-type ServerStamped = "siteId" | "visitorId" | "ts" | "companyDomain" | "companySource";
+type ServerStamped = "siteId" | "visitorId" | "ts" | "companyDomain" | "companySource" | "source";
 type BeaconEvent = {
 	[K in AnalyticsEvent["type"]]: Omit<Extract<AnalyticsEvent, {
 		type: K;

package/dist/tracker.js

@@ -1,3 +1,58 @@
+// src/engine/analytics/touch.ts
+var MAX_TOUCH_VALUE = 100;
+var CLICK_ID_PARAMS = {
+  gclid: "google",
+  gbraid: "google",
+  wbraid: "google",
+  msclkid: "microsoft",
+  fbclid: "meta",
+  li_fat_id: "linkedin",
+  ttclid: "tiktok",
+  twclid: "x"
+};
+var CLICK_ID_KINDS = new Set(Object.values(CLICK_ID_PARAMS));
+var UTM_FIELDS = ["source", "medium", "campaign", "term", "content"];
+var KHARON_LINK_PARAM = "ge_co";
+function touchFromUrl(url, referrer) {
+  const touch = {};
+  let page;
+  try {
+    page = new URL(url);
+  } catch {
+    return touch;
+  }
+  for (const field of UTM_FIELDS) {
+    const value = clean(page.searchParams.get(`utm_${field}`));
+    if (value) touch[field] = value;
+  }
+  for (const [param, kind] of Object.entries(CLICK_ID_PARAMS)) {
+    if (page.searchParams.get(param)) {
+      touch.clickId = kind;
+      break;
+    }
+  }
+  if (page.searchParams.get(KHARON_LINK_PARAM)) touch.kharonLink = true;
+  const from = referrerHost(referrer);
+  if (from && from !== bareHost(page.hostname)) touch.referrer = from;
+  return touch;
+}
+function clean(value) {
+  const trimmed = value?.replace(/[\u0000-\u001f\u007f]/g, "").trim();
+  return trimmed ? trimmed.slice(0, MAX_TOUCH_VALUE) : null;
+}
+function referrerHost(referrer) {
+  if (!referrer) return null;
+  try {
+    const { protocol, hostname } = new URL(referrer);
+    return protocol === "http:" || protocol === "https:" ? bareHost(hostname) : null;
+  } catch {
+    return null;
+  }
+}
+function bareHost(hostname) {
+  return hostname.toLowerCase().replace(/^www\./, "");
+}
+
 // src/engine/analytics/beacon.ts
 var BEACON_VERSION = 1;
 var MAX_BEACON_EVENTS = 50;
@@ -6,7 +61,9 @@ var SLOT_ATTRIBUTES = {
   variant: "data-ge-variant",
   counterfactual: "data-ge-counterfactual",
   /** Why the slot shows what it shows (matched, default, holdout). For debugging; not sent. */
-  reason: "data-ge-reason"
+  reason: "data-ge-reason",
+  /** Which step of the fallback ladder chose the content (exact, near, segment, default). Sent on impressions. */
+  rung: "data-ge-rung"
 };
 
 // packages/browser/src/tracker.ts
@@ -25,7 +82,7 @@ function startTracker({
   crossOrigin = false
 }) {
   const win = root.defaultView ?? window;
-  const sessionId = sessionIdFor(win);
+  const { id: sessionId, started } = sessionFor(win);
   const queue = [];
   const seenSlots = /* @__PURE__ */ new Set();
   const push = (type, body) => {
@@ -35,7 +92,7 @@ function startTracker({
   const flush = () => {
     while (queue.length) send(win, endpoint, envelope(queue.splice(0, MAX_BEACON_EVENTS)), crossOrigin);
   };
-  push("page_view", { pageId, configVersion });
+  push("page_view", started ? { pageId, configVersion, touch: touchFromUrl(win.location.href, root.referrer) } : { pageId, configVersion });
   const slots = Array.from(root.querySelectorAll(`[${SLOT_ATTRIBUTES.slot}]`));
   const observer = "IntersectionObserver" in win ? new win.IntersectionObserver(
     (entries) => {
@@ -101,22 +158,23 @@ function readSlot(el) {
   return {
     slotId,
     variantId: el.getAttribute(SLOT_ATTRIBUTES.variant) || null,
-    counterfactualVariantId: el.getAttribute(SLOT_ATTRIBUTES.counterfactual) || null
+    counterfactualVariantId: el.getAttribute(SLOT_ATTRIBUTES.counterfactual) || null,
+    ...el.getAttribute(SLOT_ATTRIBUTES.rung) ? { rung: el.getAttribute(SLOT_ATTRIBUTES.rung) } : {}
   };
 }
 function closestSlot(target) {
   const el = target instanceof Element ? target.closest(`[${SLOT_ATTRIBUTES.slot}]`) : null;
   return el ? readSlot(el) : null;
 }
-function sessionIdFor(win) {
+function sessionFor(win) {
   try {
     const existing = win.sessionStorage.getItem(SESSION_KEY);
-    if (existing) return existing;
+    if (existing) return { id: existing, started: false };
     const id = uuid(win);
     win.sessionStorage.setItem(SESSION_KEY, id);
-    return id;
+    return { id, started: true };
   } catch {
-    return uuid(win);
+    return { id: uuid(win), started: true };
   }
 }
 function uuid(win) {

package/dist/v1.js

@@ -1 +1 @@
-"use strict";(()=>{var Te=Object.defineProperty;var Ve=(e,t)=>{for(var n in t)Te(e,n,{get:t[n],enumerable:!0})};var ee={};Ve(ee,{ANTI_FLICKER_SNIPPET:()=>me,DEFAULT_API_BASE:()=>X,DEFAULT_TIMEOUT_MS:()=>U,VISITOR_COOKIE:()=>R,antiFlickerStart:()=>q,applyDecision:()=>J,conversion:()=>We,createClient:()=>F,hashSlotDefaults:()=>O,init:()=>Q,isWritable:()=>Z,pageIdFor:()=>Y,parseResolveResponse:()=>$,refresh:()=>qe,reveal:()=>B,scanSlots:()=>W,setConsent:()=>He});var d={slot:"data-ge-slot",variant:"data-ge-variant",counterfactual:"data-ge-counterfactual",reason:"data-ge-reason"};var Oe="/api/collect",D="ge_sid",w="ge_pin",ne=.5,Ce=2e3;function re({pageId:e,configVersion:t,endpoint:n=Oe,root:o=document,match:r,envelope:s=c=>({v:1,events:c,...r?{m:r}:{}}),crossOrigin:a=!1}){let c=o.defaultView??window,u=be(c),f=[],h=new Set,A=(l,p)=>{f.push({type:l,sessionId:u,...p}),f.length>=50&&m()},m=()=>{for(;f.length;)Pe(c,n,s(f.splice(0,50)),a)};A("page_view",{pageId:e,configVersion:t});let i=Array.from(o.querySelectorAll(`[${d.slot}]`)),v="IntersectionObserver"in c?new c.IntersectionObserver(l=>{for(let p of l){if(!p.isIntersecting||p.intersectionRatio<ne)continue;let g=se(p.target);v?.unobserve(p.target),!(!g||h.has(g.slotId))&&(h.add(g.slotId),A("slot_impression",g))}},{threshold:ne}):null;for(let l of i)v?.observe(l);let I=l=>p=>{let g=ke(p.target);g&&A("interaction",{slotId:g.slotId,variantId:g.variantId,action:l})},C=I("click"),_=I("copy"),N=l=>{l.target.open&&I("expand")(l)},k=l=>{let p=l.target.closest?.("form")?.getAttribute("data-ge-goal");p&&b(p)},x=()=>{o.visibilityState==="hidden"&&m()},b=(l,p)=>{A("conversion",p===void 0?{goal:l}:{goal:l,value:p}),m()};o.addEventListener("click",C,!0),o.addEventListener("copy",_,!0),o.addEventListener("toggle",N,!0),o.addEventListener("submit",k,!0),o.addEventListener("visibilitychange",x),c.addEventListener("pagehide",m);let y=c.setInterval(m,Ce);return{conversion:b,flush:m,stop({discard:l=!1}={}){l&&(f.length=0),m(),v?.disconnect(),c.clearInterval(y),o.removeEventListener("click",C,!0),o.removeEventListener("copy",_,!0),o.removeEventListener("toggle",N,!0),o.removeEventListener("submit",k,!0),o.removeEventListener("visibilitychange",x),c.removeEventListener("pagehide",m)}}}function se(e){let t=e.getAttribute(d.slot);return t?{slotId:t,variantId:e.getAttribute(d.variant)||null,counterfactualVariantId:e.getAttribute(d.counterfactual)||null}:null}function ke(e){let t=e instanceof Element?e.closest(`[${d.slot}]`):null;return t?se(t):null}function be(e){try{let t=e.sessionStorage.getItem(D);if(t)return t;let n=oe(e);return e.sessionStorage.setItem(D,n),n}catch{return oe(e)}}function oe(e){if(typeof e.crypto.randomUUID=="function")return e.crypto.randomUUID();let t=e.crypto.getRandomValues(new Uint8Array(16));t[6]=t[6]&15|64,t[8]=t[8]&63|128;let n=Array.from(t,o=>o.toString(16).padStart(2,"0")).join("");return`${n.slice(0,8)}-${n.slice(8,12)}-${n.slice(12,16)}-${n.slice(16,20)}-${n.slice(20)}`}function Pe(e,t,n,o){let r=JSON.stringify(n),s=o?"text/plain":"application/json";e.navigator.sendBeacon?.(t,new Blob([r],{type:s}))||e.fetch(t,{method:"POST",body:r,keepalive:!0,credentials:o?"omit":"same-origin",headers:{"content-type":s}}).catch(a=>console.warn("[ge] analytics beacon failed",a))}var S="ge_preview";var ie=/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;function T(e){return typeof e=="string"&&ie.test(e)}function O(e){let t=JSON.stringify(Object.keys(e).sort().map(o=>[o,e[o]])),n=2166136261;for(let o=0;o<t.length;o++)n^=t.charCodeAt(o),n=Math.imul(n,16777619);return(n>>>0).toString(16).padStart(8,"0")}var ce="/api/v1/resolve",le="/api/v1/collect",Be=["matched","default","holdout"];function $(e){if(!M(e)||e.v!==1||!M(e.decisions)||!Number.isSafeInteger(e.configVersion)||typeof e.persist!="boolean")return null;let t=T(e.vid)?e.vid:void 0,n=e.persist&&t!==void 0,o=n&&typeof e.pin=="string"&&/^\d{1,9}\.\d{1,9}$/.test(e.pin)?e.pin:void 0,r={};for(let[a,c]of Object.entries(e.decisions)){let u=Le(c);u&&(r[a]=u)}let s=n&&typeof e.m=="string"&&e.m.length<=1024?e.m:void 0;return e.preview===!0?{v:1,configVersion:e.configVersion,persist:!1,preview:!0,decisions:r}:{v:1,configVersion:e.configVersion,persist:n,vid:t,...o?{pin:o}:{},decisions:r,...s?{m:s}:{}}}function Le(e){if(!M(e)||!M(e.content)||!ae(e.variantId)||!ae(e.counterfactualVariantId)||!Be.includes(e.reason))return null;let t={};for(let[n,o]of Object.entries(e.content))typeof o=="string"&&(t[n]=o);return{variantId:e.variantId,counterfactualVariantId:e.counterfactualVariantId,reason:e.reason,content:t}}function M(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}function ae(e){return e===null||typeof e=="string"}var X="https://kharonlabs.com",U=500,Ne=5e3,R="ge_vid",De=365*24*60*60;function F(e){let t=e.root??document,n=t.defaultView??window,o=(e.apiBase??X).replace(/\/+$/,""),r=new Set,s=e.consent??"unknown",a=!1,c,u=null,f=!1,h=(i=!1)=>{u?.stop({discard:i}),u=null},A=()=>{a=!1,c=void 0,h(!0),Ke(t,R,e.cookieDomain);try{n.sessionStorage.removeItem(D),n.sessionStorage.removeItem(w)}catch{}},m=i=>{if(i.preview){f=!0,h(!0);return}i.persist&&i.vid&&s!=="denied"?(a=!0,c=i.m,K(t,R)!==i.vid&&$e(t,R,i.vid,e.cookieDomain),i.pin&&ue(n,w,i.pin)):(a||K(t,R))&&A()};return{get consent(){return s},async resolve(i,v=Date.now()+Ne){let I=K(t,R),C=pe(n,w),_=we(n),N={v:1,key:e.key,...T(I)?{vid:I}:{},...C?{pin:C}:{},url:_.url,referrer:t.referrer,slots:i.map(y=>({id:y.id,h:O(y.defaults)})),consent:s,gpc:n.navigator.globalPrivacyControl===!0},k=v-Date.now();if(k<=0||typeof n.fetch!="function")return null;let x=typeof AbortController=="function"?new AbortController:null,b;try{let y=n.fetch(o+ce,{method:"POST",body:JSON.stringify(N),credentials:"omit",signal:x?.signal}),l=new Promise(_e=>{b=setTimeout(()=>{x?.abort(),_e(null)},k)}),p=await Promise.race([y,l]);if(!p)return null;if(!p.ok)return console.warn(`[kharon] resolve answered ${p.status}; keeping defaults`),null;let g=$(await Promise.race([p.json(),l]));return!g||Date.now()>v?null:(g.preview&&_.token?ue(n,S,_.token):!g.preview&&_.token&&Me(n,S),m(g),g)}catch(y){return x?.signal.aborted||console.warn("[kharon] resolve failed; keeping defaults",y),null}finally{clearTimeout(b)}},adopt:m,track(i){h();let v=K(t,R);f||!a||!T(v)||(u=re({pageId:e.pageId??Y(n.location.pathname),configVersion:i,endpoint:o+le,root:t,crossOrigin:!0,envelope:I=>({v:2,key:e.key,vid:v,consent:s,events:I,...c?{m:c}:{}})}))},setConsent(i){if(i!==s){s=i,i==="denied"&&A();for(let v of r)v(i)}},onConsentChange(i){return r.add(i),()=>r.delete(i)},conversion(i,v){u?.conversion(i,v)},stop:()=>h()}}function Y(e){return e.split("/").map(n=>n.replace(/[^A-Za-z0-9_:-]/g,"")).filter(Boolean).join(".").slice(0,128)||"home"}function K(e,t){for(let n of e.cookie.split(";")){let[o,...r]=n.trim().split("=");if(o===t)try{return decodeURIComponent(r.join("="))}catch{return}}}function pe(e,t){try{return e.sessionStorage.getItem(t)}catch{return null}}function we(e){let t=e.location.href,n;try{n=new URL(t)}catch{return{url:t,token:null}}let o=n.searchParams.get(S);if(o)return{url:t,token:o};let r=pe(e,S);return r?(n.searchParams.set(S,r),{url:n.toString(),token:r}):{url:t,token:null}}function Me(e,t){try{e.sessionStorage.removeItem(t)}catch{}}function ue(e,t,n){try{e.sessionStorage.setItem(t,n)}catch{}}function de(e,t){let n=e.location?.protocol==="https:"?"; Secure":"";return`; Path=/; SameSite=Lax${t?`; Domain=${t}`:""}${n}`}function $e(e,t,n,o){e.cookie=`${t}=${encodeURIComponent(n)}; Max-Age=${De}${de(e,o)}`}function Ke(e,t,n){e.cookie=`${t}=; Max-Age=0${de(e,n)}`}var fe="data-ge-field",ge="data-ge-attr",G="kharon-af",me=`<style id="${G}">[${d.slot}]{visibility:hidden!important}</style><script>window.__kharonAf=Date.now();setTimeout(function(){var s=document.getElementById("${G}");s&&s.parentNode.removeChild(s)},500)<\/script>`,Ue=new Set(["href","src","action","formaction","poster","cite","xlink:href"]),Fe=/^(on|style$|srcdoc$|srcset$)/,H=new WeakMap,P="#text";function Ee(e,t){return t===null?(e.textContent??"").trim():e.getAttribute(t)}function Ie(e,t){let n=H.get(e);return n?.has(t??P)?n.get(t??P):Ee(e,t)}function ve(e,t,n){let o=H.get(e);o||H.set(e,o=new Map),o.has(t??P)||o.set(t??P,Ee(e,t)),t===null?e.textContent=n??"":n===null?e.removeAttribute(t):e.setAttribute(t,n)}function W(e){let t=new Map;for(let n of Se(e)){let o=n.getAttribute(d.slot);if(t.has(o))continue;let r={};for(let s of Re(n))s.field in r||(r[s.field]=Ie(s.el,s.attr)??"");t.set(o,{id:o,defaults:r})}return[...t.values()]}function ye(e,t){for(let n of Se(e)){let o=t.decisions[n.getAttribute(d.slot)];o&&J(n,o,e.baseURI)}}function J(e,t,n){for(let{el:o,field:r,attr:s}of Re(e)){let a=t.content[r];typeof a=="string"&&(s===null||Z(s,a,n))?ve(o,s,a):H.get(o)?.has(s??P)&&ve(o,s,Ie(o,s))}e.setAttribute(d.variant,t.variantId??""),e.setAttribute(d.counterfactual,t.counterfactualVariantId??""),e.setAttribute(d.reason,t.reason)}function B(e){e.getElementById(G)?.remove()}function q(e){let t=e.defaultView?.__kharonAf;return typeof t=="number"?t:void 0}function Z(e,t,n){let o=e.toLowerCase();if(Fe.test(o))return!1;if(!Ue.has(o))return!0;try{let{protocol:r}=new URL(t,n);return r==="http:"||r==="https:"}catch{return!1}}function Se(e){return Array.from(e.querySelectorAll(`[${d.slot}]`))}function Re(e){let t=[],n=[e,...Array.from(e.querySelectorAll(`[${fe}],[${ge}]`))];for(let o of n){if(o!==e&&o.closest(`[${d.slot}]`)!==e)continue;let r=o.getAttribute(fe);r&&t.push({el:o,field:r,attr:null});for(let s of(o.getAttribute(ge)??"").split(",")){let a=s.lastIndexOf(":"),c=s.slice(0,a).trim(),u=s.slice(a+1).trim();a>0&&c&&u&&t.push({el:o,field:u,attr:c})}}return t}var E=null,he;function Q(e){if(E)return console.warn("[kharon] init called twice; keeping the first instance"),E;let t=e.root??document,n=e.timeoutMs??U,o=F({...e,consent:he??e.consent}),r=async u=>{try{let f=await o.resolve(W(t),u);f&&ye(t,f),B(t),f&&o.track(f.configVersion)}catch(f){B(t),console.warn("[kharon] personalization failed; keeping defaults",f)}},a=new Promise(u=>{t.readyState!=="loading"?u():t.addEventListener("DOMContentLoaded",()=>u(),{once:!0})}).then(()=>r((q(t)??Date.now())+n));o.onConsentChange(u=>{u==="granted"&&(a=a.then(()=>r()))});let c={client:o,get ready(){return a},setConsent:o.setConsent,conversion:o.conversion,refresh(){return a=a.then(()=>r(Date.now()+n)),a},stop(){o.stop(),E===c&&(E=null)}};return E=c,c}function He(e){E?E.setConsent(e):he=e}function We(e,t){E?.conversion(e,t)}function qe(){return E?.refresh()??Promise.resolve()}var je=["granted","denied","unknown"],L=document.currentScript;window.kharon=ee;var Ae=L?.getAttribute("data-key");L&&Ae&&Q({key:Ae,apiBase:L.getAttribute("data-api")??new URL(L.src).origin,consent:je.find(e=>e===L.getAttribute("data-consent"))});})();
+"use strict";(()=>{var be=Object.defineProperty;var Oe=(e,t)=>{for(var n in t)be(e,n,{get:t[n],enumerable:!0})};var ie={};Oe(ie,{ANTI_FLICKER_SNIPPET:()=>Ee,DEFAULT_API_BASE:()=>Q,DEFAULT_TIMEOUT_MS:()=>F,VISITOR_COOKIE:()=>E,antiFlickerStart:()=>j,applyDecision:()=>ne,conversion:()=>et,createClient:()=>q,hashSlotDefaults:()=>T,init:()=>re,isWritable:()=>oe,pageIdFor:()=>ee,parseResolveResponse:()=>$,refresh:()=>nt,reveal:()=>D,scanSlots:()=>W,setConsent:()=>Qe,signup:()=>tt});var G="signup";var X={gclid:"google",gbraid:"google",wbraid:"google",msclkid:"microsoft",fbclid:"meta",li_fat_id:"linkedin",ttclid:"tiktok",twclid:"x"},st=new Set(Object.values(X)),Ve=["source","medium","campaign","term","content"],Le="ge_co";function Y(e,t){let n={},o;try{o=new URL(e)}catch{return n}for(let i of Ve){let a=we(o.searchParams.get(`utm_${i}`));a&&(n[i]=a)}for(let[i,a]of Object.entries(X))if(o.searchParams.get(i)){n.clickId=a;break}o.searchParams.get(Le)&&(n.kharonLink=!0);let r=De(t);return r&&r!==se(o.hostname)&&(n.referrer=r),n}function we(e){let t=e?.replace(/[\u0000-\u001f\u007f]/g,"").trim();return t?t.slice(0,100):null}function De(e){if(!e)return null;try{let{protocol:t,hostname:n}=new URL(e);return t==="http:"||t==="https:"?se(n):null}catch{return null}}function se(e){return e.toLowerCase().replace(/^www\./,"")}var Z=1,B=50;var p={slot:"data-ge-slot",variant:"data-ge-variant",counterfactual:"data-ge-counterfactual",reason:"data-ge-reason",rung:"data-ge-rung"};var Me="/api/collect",U="ge_sid",K="ge_pin",ae=.5,Be=2e3;function le({pageId:e,configVersion:t,endpoint:n=Me,root:o=document,match:r,envelope:i=c=>({v:Z,events:c,...r?{m:r}:{}}),crossOrigin:a=!1}){let c=o.defaultView??window,{id:f,started:d}=Ke(c),m=[],b=new Set,R=(l,u)=>{m.push({type:l,sessionId:f,...u}),m.length>=B&&s()},s=()=>{for(;m.length;)$e(c,n,i(m.splice(0,B)),a)};R("page_view",d?{pageId:e,configVersion:t,touch:Y(c.location.href,o.referrer)}:{pageId:e,configVersion:t});let g=Array.from(o.querySelectorAll(`[${p.slot}]`)),h="IntersectionObserver"in c?new c.IntersectionObserver(l=>{for(let u of l){if(!u.isIntersecting||u.intersectionRatio<ae)continue;let v=ue(u.target);h?.unobserve(u.target),!(!v||b.has(v.slotId))&&(b.add(v.slotId),R("slot_impression",v))}},{threshold:ae}):null;for(let l of g)h?.observe(l);let x=l=>u=>{let v=Ue(u.target);v&&R("interaction",{slotId:v.slotId,variantId:v.variantId,action:l})},_=x("click"),N=x("copy"),O=l=>{l.target.open&&x("expand")(l)},C=l=>{let u=l.target.closest?.("form")?.getAttribute("data-ge-goal");u&&S(u)},V=()=>{o.visibilityState==="hidden"&&s()},S=(l,u)=>{R("conversion",u===void 0?{goal:l}:{goal:l,value:u}),s()};o.addEventListener("click",_,!0),o.addEventListener("copy",N,!0),o.addEventListener("toggle",O,!0),o.addEventListener("submit",C,!0),o.addEventListener("visibilitychange",V),c.addEventListener("pagehide",s);let M=c.setInterval(s,Be);return{conversion:S,flush:s,stop({discard:l=!1}={}){l&&(m.length=0),s(),h?.disconnect(),c.clearInterval(M),o.removeEventListener("click",_,!0),o.removeEventListener("copy",N,!0),o.removeEventListener("toggle",O,!0),o.removeEventListener("submit",C,!0),o.removeEventListener("visibilitychange",V),c.removeEventListener("pagehide",s)}}}function ue(e){let t=e.getAttribute(p.slot);return t?{slotId:t,variantId:e.getAttribute(p.variant)||null,counterfactualVariantId:e.getAttribute(p.counterfactual)||null,...e.getAttribute(p.rung)?{rung:e.getAttribute(p.rung)}:{}}:null}function Ue(e){let t=e instanceof Element?e.closest(`[${p.slot}]`):null;return t?ue(t):null}function Ke(e){try{let t=e.sessionStorage.getItem(U);if(t)return{id:t,started:!1};let n=ce(e);return e.sessionStorage.setItem(U,n),{id:n,started:!0}}catch{return{id:ce(e),started:!0}}}function ce(e){if(typeof e.crypto.randomUUID=="function")return e.crypto.randomUUID();let t=e.crypto.getRandomValues(new Uint8Array(16));t[6]=t[6]&15|64,t[8]=t[8]&63|128;let n=Array.from(t,o=>o.toString(16).padStart(2,"0")).join("");return`${n.slice(0,8)}-${n.slice(8,12)}-${n.slice(12,16)}-${n.slice(16,20)}-${n.slice(20)}`}function $e(e,t,n,o){let r=JSON.stringify(n),i=o?"text/plain":"application/json";e.navigator.sendBeacon?.(t,new Blob([r],{type:i}))||e.fetch(t,{method:"POST",body:r,keepalive:!0,credentials:o?"omit":"same-origin",headers:{"content-type":i}}).catch(a=>console.warn("[ge] analytics beacon failed",a))}var y="ge_preview";var pe=/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;function A(e){return typeof e=="string"&&pe.test(e)}function T(e){let t=JSON.stringify(Object.keys(e).sort().map(o=>[o,e[o]])),n=2166136261;for(let o=0;o<t.length;o++)n^=t.charCodeAt(o),n=Math.imul(n,16777619);return(n>>>0).toString(16).padStart(8,"0")}var de="/api/v1/resolve",ge="/api/v1/collect",He=["matched","default","holdout"],Fe=["exact","near","segment","default"];function $(e){if(!L(e)||e.v!==1||!L(e.decisions)||!Number.isSafeInteger(e.configVersion)||typeof e.persist!="boolean")return null;let t=A(e.vid)?e.vid:void 0,n=e.persist&&t!==void 0,o=n&&typeof e.pin=="string"&&/^\d{1,9}\.\d{1,9}$/.test(e.pin)?e.pin:void 0,r={};for(let[a,c]of Object.entries(e.decisions)){let f=qe(c);f&&(r[a]=f)}let i=n&&typeof e.m=="string"&&e.m.length<=1024?e.m:void 0;if(e.preview===!0){let a=L(e.explain)?e.explain:void 0;return{v:1,configVersion:e.configVersion,persist:!1,preview:!0,decisions:r,...a?{explain:a}:{}}}return{v:1,configVersion:e.configVersion,persist:n,vid:t,...o?{pin:o}:{},decisions:r,...i?{m:i}:{}}}function qe(e){if(!L(e)||!L(e.content)||!fe(e.variantId)||!fe(e.counterfactualVariantId)||!He.includes(e.reason))return null;let t={};for(let[o,r]of Object.entries(e.content))typeof r=="string"&&(t[o]=r);let n=Fe.includes(e.rung)?e.rung:void 0;return{variantId:e.variantId,counterfactualVariantId:e.counterfactualVariantId,reason:e.reason,...n&&{rung:n},content:t}}function L(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}function fe(e){return e===null||typeof e=="string"}var Q="https://kharonlabs.com",F=500,ze=5e3,E="ge_vid",We=365*24*60*60;function q(e){let t=e.root??document,n=t.defaultView??window,o=(e.apiBase??Q).replace(/\/+$/,""),r=new Set,i=e.consent??"unknown",a=!1,c,f=null,d=!1,m=(s=!1)=>{f?.stop({discard:s}),f=null},b=()=>{a=!1,c=void 0,m(!0),Ye(t,E,e.cookieDomain);try{n.sessionStorage.removeItem(U),n.sessionStorage.removeItem(K)}catch{}},R=s=>{if(s.preview){d=!0,m(!0),s.explain&&n.console?.info("[kharon] debug link: why this page shows what it does",s.explain);return}s.persist&&s.vid&&i!=="denied"?(a=!0,c=s.m,H(t,E)!==s.vid&&Xe(t,E,s.vid,e.cookieDomain),s.pin&&me(n,K,s.pin)):(a||H(t,E))&&b()};return{get consent(){return i},async resolve(s,g=Date.now()+ze){let h=H(t,E),x=ve(n,K),_=je(n),N={v:1,key:e.key,...A(h)?{vid:h}:{},...x?{pin:x}:{},url:_.url,referrer:t.referrer,slots:s.map(S=>({id:S.id,h:T(S.defaults)})),consent:i,gpc:n.navigator.globalPrivacyControl===!0},O=g-Date.now();if(O<=0||typeof n.fetch!="function")return null;let C=typeof AbortController=="function"?new AbortController:null,V;try{let S=n.fetch(o+de,{method:"POST",body:JSON.stringify(N),credentials:"omit",signal:C?.signal}),M=new Promise(v=>{V=setTimeout(()=>{C?.abort(),v(null)},O)}),l=await Promise.race([S,M]);if(!l)return null;if(!l.ok)return console.warn(`[kharon] resolve answered ${l.status}; keeping defaults`),null;let u=$(await Promise.race([l.json(),M]));return!u||Date.now()>g?null:(u.preview&&_.token?me(n,y,_.token):!u.preview&&_.token&&Ge(n,y),R(u),u)}catch(S){return C?.signal.aborted||console.warn("[kharon] resolve failed; keeping defaults",S),null}finally{clearTimeout(V)}},adopt:R,track(s){m();let g=H(t,E);d||!a||!A(g)||(f=le({pageId:e.pageId??ee(n.location.pathname),configVersion:s,endpoint:o+ge,root:t,crossOrigin:!0,envelope:h=>({v:2,key:e.key,vid:g,consent:i,events:h,...c?{m:c}:{}})}))},setConsent(s){if(s!==i){i=s,s==="denied"&&b();for(let g of r)g(s)}},onConsentChange(s){return r.add(s),()=>r.delete(s)},conversion(s,g){f?.conversion(s,g)},stop:()=>m()}}function ee(e){return e.split("/").map(n=>n.replace(/[^A-Za-z0-9_:-]/g,"")).filter(Boolean).join(".").slice(0,128)||"home"}function H(e,t){for(let n of e.cookie.split(";")){let[o,...r]=n.trim().split("=");if(o===t)try{return decodeURIComponent(r.join("="))}catch{return}}}function ve(e,t){try{return e.sessionStorage.getItem(t)}catch{return null}}function je(e){let t=e.location.href,n;try{n=new URL(t)}catch{return{url:t,token:null}}let o=n.searchParams.get(y);if(o)return{url:t,token:o};let r=ve(e,y);return r?(n.searchParams.set(y,r),{url:n.toString(),token:r}):{url:t,token:null}}function Ge(e,t){try{e.sessionStorage.removeItem(t)}catch{}}function me(e,t,n){try{e.sessionStorage.setItem(t,n)}catch{}}function Ie(e,t){let n=e.location?.protocol==="https:"?"; Secure":"";return`; Path=/; SameSite=Lax${t?`; Domain=${t}`:""}${n}`}function Xe(e,t,n,o){e.cookie=`${t}=${encodeURIComponent(n)}; Max-Age=${We}${Ie(e,o)}`}function Ye(e,t,n){e.cookie=`${t}=; Max-Age=0${Ie(e,n)}`}var Se="data-ge-field",he="data-ge-attr",te="kharon-af",Ee=`<style id="${te}">[${p.slot}]{visibility:hidden!important}</style><script>window.__kharonAf=Date.now();setTimeout(function(){var s=document.getElementById("${te}");s&&s.parentNode.removeChild(s)},500)<\/script>`,Ze=new Set(["href","src","action","formaction","poster","cite","xlink:href"]),Je=/^(on|style$|srcdoc$|srcset$)/,z=new WeakMap,w="#text";function Re(e,t){return t===null?(e.textContent??"").trim():e.getAttribute(t)}function _e(e,t){let n=z.get(e);return n?.has(t??w)?n.get(t??w):Re(e,t)}function ye(e,t,n){let o=z.get(e);o||z.set(e,o=new Map),o.has(t??w)||o.set(t??w,Re(e,t)),t===null?e.textContent=n??"":n===null?e.removeAttribute(t):e.setAttribute(t,n)}function W(e){let t=new Map;for(let n of ke(e)){let o=n.getAttribute(p.slot);if(t.has(o))continue;let r={};for(let i of xe(n))i.field in r||(r[i.field]=_e(i.el,i.attr)??"");t.set(o,{id:o,defaults:r})}return[...t.values()]}function Ae(e,t){for(let n of ke(e)){let o=t.decisions[n.getAttribute(p.slot)];o&&ne(n,o,e.baseURI)}}function ne(e,t,n){for(let{el:o,field:r,attr:i}of xe(e)){let a=t.content[r];typeof a=="string"&&(i===null||oe(i,a,n))?ye(o,i,a):z.get(o)?.has(i??w)&&ye(o,i,_e(o,i))}e.setAttribute(p.variant,t.variantId??""),e.setAttribute(p.counterfactual,t.counterfactualVariantId??""),e.setAttribute(p.reason,t.reason),t.rung?e.setAttribute(p.rung,t.rung):e.removeAttribute(p.rung)}function D(e){e.getElementById(te)?.remove()}function j(e){let t=e.defaultView?.__kharonAf;return typeof t=="number"?t:void 0}function oe(e,t,n){let o=e.toLowerCase();if(Je.test(o))return!1;if(!Ze.has(o))return!0;try{let{protocol:r}=new URL(t,n);return r==="http:"||r==="https:"}catch{return!1}}function ke(e){return Array.from(e.querySelectorAll(`[${p.slot}]`))}function xe(e){let t=[],n=[e,...Array.from(e.querySelectorAll(`[${Se}],[${he}]`))];for(let o of n){if(o!==e&&o.closest(`[${p.slot}]`)!==e)continue;let r=o.getAttribute(Se);r&&t.push({el:o,field:r,attr:null});for(let i of(o.getAttribute(he)??"").split(",")){let a=i.lastIndexOf(":"),c=i.slice(0,a).trim(),f=i.slice(a+1).trim();a>0&&c&&f&&t.push({el:o,field:f,attr:c})}}return t}var I=null,Ce;function re(e){if(I)return console.warn("[kharon] init called twice; keeping the first instance"),I;let t=e.root??document,n=e.timeoutMs??F,o=q({...e,consent:Ce??e.consent}),r=async f=>{try{let d=await o.resolve(W(t),f);d&&Ae(t,d),D(t),d&&o.track(d.configVersion)}catch(d){D(t),console.warn("[kharon] personalization failed; keeping defaults",d)}},a=new Promise(f=>{t.readyState!=="loading"?f():t.addEventListener("DOMContentLoaded",()=>f(),{once:!0})}).then(()=>r((j(t)??Date.now())+n));o.onConsentChange(f=>{f==="granted"&&(a=a.then(()=>r()))});let c={client:o,get ready(){return a},setConsent:o.setConsent,conversion:o.conversion,refresh(){return a=a.then(()=>r(Date.now()+n)),a},stop(){o.stop(),I===c&&(I=null)}};return I=c,c}function Qe(e){I?I.setConsent(e):Ce=e}function et(e,t){I?.conversion(e,t)}function tt(){I?.conversion(G)}function nt(){return I?.refresh()??Promise.resolve()}var ot=["granted","denied","unknown"],P=document.currentScript;window.kharon=ie;var Te=P?.getAttribute("data-key");P&&Te&&re({key:Te,apiBase:P.getAttribute("data-api")??new URL(P.src).origin,consent:ot.find(e=>e===P.getAttribute("data-consent"))});})();

package/package.json

@@ -1,13 +1,8 @@
 {
   "name": "@kharon-labs/browser",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Personalize slots on any website with Kharon Labs: swaps in the variant for each visitor and measures lift against a holdout.",
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/alexarmenciu/growth-engine.git",
-    "directory": "packages/browser"
-  },
   "homepage": "https://kharonlabs.com",
   "type": "module",
   "sideEffects": false,