@qoretechnologies/reqraft 0.10.56 → 0.10.57-pr.127.g0a792ea

package/src/tracking/browser/attach.ts

@@ -0,0 +1,186 @@
+import { effectiveRatio } from '../core/sections';
+import type { Tracker } from '../core/tracker';
+
+/**
+ * Connects a `Tracker` to the page: tab visibility, page leave, interactions,
+ * scroll depth, the heartbeat, section visibility (IntersectionObserver on every
+ * `[data-track-section]`) and clicks (one delegated listener for
+ * `[data-track-click]`). Returns a function that removes all of it.
+ *
+ * Markup contract (see design/TRACKING.md):
+ *   data-track-section="<id>"        a section: visible time, seen, exit section
+ *   data-track-click="<target>"      a tracked click (`get-started`, `contact`, …)
+ *   data-track-placement="<where>"   optional; defaults to the enclosing section id
+ *   data-track-label="<text>"        optional; defaults to the element's text
+ */
+
+const SECTION_SELECTOR = '[data-track-section]';
+const THRESHOLDS = Array.from({ length: 21 }, (_, i) => i / 20);
+const TICK_MS = 250;
+const ACTIVITY_EVENTS = ['pointerdown', 'keydown', 'wheel', 'touchstart', 'mousemove', 'scroll'] as const;
+
+export interface IAttached {
+  detach: () => void;
+  /** Observes an element under a synthetic id (an experiment's wrapped element); not in the page summary. */
+  observeElement: (el: Element, id: string) => () => void;
+}
+
+const clean = (s: string | null | undefined, max = 80) => {
+  const t = (s ?? '').replace(/\s+/g, ' ').trim();
+  return t ? t.slice(0, max) : null;
+};
+
+export const attachToPage = (tracker: Tracker, heartbeatMs: number): IAttached => {
+  const cleanup: (() => void)[] = [];
+  const on = (target: EventTarget, type: string, fn: EventListener, opts?: AddEventListenerOptions) => {
+    target.addEventListener(type, fn, opts);
+    cleanup.push(() => target.removeEventListener(type, fn, opts));
+  };
+  const safe = (fn: () => void) => () => {
+    try {
+      fn();
+    } catch {
+      /* never into the page */
+    }
+  };
+
+  // ── tab visibility and page leave
+  on(document, 'visibilitychange', safe(() => tracker.setTabVisible(document.visibilityState === 'visible')));
+  on(window, 'pagehide', safe(() => tracker.leave()));
+  if (document.visibilityState !== 'visible') tracker.setTabVisible(false);
+
+  // ── engagement (throttled to one signal per second)
+  let lastActivity = 0;
+  const activity = safe(() => {
+    const now = Date.now();
+    if (now - lastActivity < 1000) return;
+    lastActivity = now;
+    tracker.activity();
+  });
+  ACTIVITY_EVENTS.forEach((t) => on(window, t, activity, { passive: true, capture: true }));
+
+  // ── scroll depth (once per frame)
+  let scrollQueued = false;
+  const measureScroll = safe(() => {
+    scrollQueued = false;
+    const doc = document.documentElement;
+    const scrollable = Math.max(doc.scrollHeight, document.body?.scrollHeight ?? 0);
+    const seen = window.scrollY + window.innerHeight;
+    tracker.scrolled(scrollable > 0 ? (seen / scrollable) * 100 : 100);
+  });
+  on(window, 'scroll', () => {
+    if (scrollQueued) return;
+    scrollQueued = true;
+    requestAnimationFrame(measureScroll);
+  }, { passive: true });
+
+  // ── heartbeat while visible, and the section clock
+  const heartbeat = setInterval(safe(() => document.visibilityState === 'visible' && tracker.heartbeat()), heartbeatMs);
+  const tick = setInterval(safe(() => tracker.sections.tick(tracker.now())), TICK_MS);
+  cleanup.push(() => clearInterval(heartbeat), () => clearInterval(tick));
+
+  // ── sections
+  const ratios = new Map<Element, number>();
+  const ids = new Map<Element, string>();
+  const report = new Map<string, boolean>();
+  const apply = (id: string) => {
+    let best = 0;
+    ids.forEach((other, el) => other === id && (best = Math.max(best, ratios.get(el) ?? 0)));
+    tracker.sections.update(id, best, tracker.now());
+  };
+  const io =
+    typeof IntersectionObserver !== 'undefined'
+      ? new IntersectionObserver(
+          (entries) =>
+            safe(() => {
+              const vh = window.innerHeight || document.documentElement.clientHeight;
+              entries.forEach((e) => {
+                const id = ids.get(e.target);
+                if (!id) return;
+                ratios.set(e.target, effectiveRatio(e.intersectionRatio, e.intersectionRect.height, e.rootBounds?.height ?? vh));
+                apply(id);
+              });
+            })(),
+          { threshold: THRESHOLDS },
+        )
+      : null;
+
+  const track = (el: Element, id: string, inSummary: boolean) => {
+    if (ids.get(el) === id) return;
+    ids.set(el, id);
+    report.set(id, (report.get(id) ?? false) || inSummary);
+    tracker.sections.register(id, inSummary);
+    io?.observe(el);
+  };
+  const untrack = (el: Element) => {
+    const id = ids.get(el);
+    if (!id) return;
+    io?.unobserve(el);
+    ids.delete(el);
+    ratios.delete(el);
+    apply(id);
+  };
+
+  const scan = safe(() => {
+    const present = new Set<Element>(Array.from(document.querySelectorAll(SECTION_SELECTOR)));
+    ids.forEach((id, el) => report.get(id) && !present.has(el) && !el.isConnected && untrack(el));
+    present.forEach((el) => {
+      const id = (el as HTMLElement).dataset.trackSection;
+      if (id) track(el, id, true);
+    });
+  });
+
+  // Re-measure everything at a new page view: the section clock starts from zero,
+  // and re-observing makes the observer report every element's current state.
+  const remeasure = safe(() => {
+    scan();
+    ids.forEach((_id, el) => {
+      io?.unobserve(el);
+      io?.observe(el);
+    });
+  });
+  cleanup.push(tracker.pageViewId.subscribe(remeasure));
+
+  let scanTimer: ReturnType<typeof setTimeout> | null = null;
+  const mo =
+    typeof MutationObserver !== 'undefined'
+      ? new MutationObserver(() => {
+          if (scanTimer) return;
+          scanTimer = setTimeout(() => {
+            scanTimer = null;
+            scan();
+          }, 150);
+        })
+      : null;
+  mo?.observe(document.body, { childList: true, subtree: true });
+  scan();
+  cleanup.push(() => {
+    mo?.disconnect();
+    io?.disconnect();
+    if (scanTimer) clearTimeout(scanTimer);
+  });
+
+  // ── clicks: one delegated listener
+  const onClick = (e: Event) =>
+    safe(() => {
+      const el = (e.target as Element | null)?.closest?.('[data-track-click]') as HTMLElement | null;
+      if (!el) return;
+      const d = el.dataset;
+      const link = el.closest('a');
+      tracker.click({
+        target: d.trackClick || 'unknown',
+        placement: d.trackPlacement || (el.closest(SECTION_SELECTOR) as HTMLElement | null)?.dataset.trackSection || null,
+        label: clean(d.trackLabel) ?? clean(el.innerText) ?? clean(el.getAttribute('aria-label')),
+        href: d.trackHref || link?.href || null,
+      });
+    })();
+  on(document, 'click', onClick, { capture: true });
+
+  return {
+    detach: () => cleanup.forEach((fn) => fn()),
+    observeElement: (el, id) => {
+      track(el, id, false);
+      return () => untrack(el);
+    },
+  };
+};

package/src/tracking/browser/env.ts

@@ -0,0 +1,78 @@
+import type { ITransport } from '../core/queue';
+import { safeStorage } from '../core/storage';
+import type { IPageInfo, ITrackerEnv } from '../core/tracker';
+
+/**
+ * Sends a batch. `beacon` (page going away): `navigator.sendBeacon`, falling back
+ * to `fetch(…, { keepalive: true })` when the beacon is refused (too big, or the
+ * browser has none). Any HTTP answer counts as delivered — the collector always
+ * answers 204, and a 404 (collector not installed) must not turn into a retry loop;
+ * only a network error keeps the batch for the next flush.
+ */
+export const browserTransport = (endpoint: string): ITransport => ({
+  async send(body, mode) {
+    if (mode === 'beacon' && typeof navigator !== 'undefined' && typeof navigator.sendBeacon === 'function') {
+      try {
+        if (navigator.sendBeacon(endpoint, new Blob([body], { type: 'application/json' }))) return true;
+      } catch {
+        /* fall through to fetch */
+      }
+    }
+    try {
+      await fetch(endpoint, {
+        method: 'POST',
+        body,
+        headers: { 'Content-Type': 'application/json' },
+        // Batches stay under 60 KB (queue.ts), inside keepalive's 64 KB budget.
+        keepalive: true,
+        credentials: 'same-origin',
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  },
+});
+
+const fetchJson = async (url: string, timeoutMs: number): Promise<unknown> => {
+  const ctrl = typeof AbortController !== 'undefined' ? new AbortController() : undefined;
+  const timer = setTimeout(() => ctrl?.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { headers: { Accept: 'application/json' }, signal: ctrl?.signal, credentials: 'same-origin' });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    return await res.json();
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+/** desktop / tablet / mobile from the user agent (targeting only; the server classifies for reports). */
+export const deviceOf = (ua: string): IPageInfo['device'] => {
+  if (/iPad|Tablet|PlayBook|Silk|Android(?!.*Mobile)/i.test(ua)) return 'tablet';
+  if (/Mobi|iPhone|iPod|Android.*Mobile|Opera Mini|IEMobile/i.test(ua)) return 'mobile';
+  return 'desktop';
+};
+
+const readPage = (): IPageInfo => ({
+  origin: window.location.origin,
+  path: window.location.pathname,
+  search: window.location.search,
+  title: document.title,
+  referrer: document.referrer,
+  lang: navigator.language || 'en',
+  viewport: [window.innerWidth, window.innerHeight],
+  device: deviceOf(navigator.userAgent || ''),
+});
+
+export const browserEnv = (endpoint: string): ITrackerEnv => ({
+  local: safeStorage(() => window.localStorage),
+  session: safeStorage(() => window.sessionStorage),
+  transport: browserTransport(endpoint),
+  now: () => Date.now(),
+  setTimer: (fn, ms) => setTimeout(fn, ms),
+  clearTimer: (h) => clearTimeout(h as ReturnType<typeof setTimeout>),
+  page: readPage,
+  fetchJson,
+  // eslint-disable-next-line no-console
+  log: (...args) => console.info(...args),
+});

package/src/tracking/core/consent.ts

@@ -0,0 +1,37 @@
+import type { IStorage } from './storage';
+import { Observable } from './observable';
+import { KEYS, type TConsentState, type TStorageKeys } from './types';
+
+/**
+ * The visitor's answer (§3 of the contract): `localStorage["<prefix>consent"]` is
+ * `granted` | `denied`, `<prefix>consent.v` the version of the text they answered
+ * (prefix `qa.` by default). An answer to an older version counts as no answer, so
+ * the consent prompt asks again.
+ */
+export class ConsentStore {
+  readonly state: Observable<TConsentState>;
+
+  constructor(
+    private readonly storage: IStorage,
+    private readonly version: number,
+    private readonly keys: TStorageKeys = KEYS,
+  ) {
+    this.state = new Observable<TConsentState>(this.read());
+  }
+
+  private read(): TConsentState {
+    const answer = this.storage.get(this.keys.consent);
+    const version = Number(this.storage.get(this.keys.consentVersion) ?? 0);
+    if ((answer === 'granted' || answer === 'denied') && version >= this.version) return answer;
+    return 'unknown';
+  }
+
+  get = (): TConsentState => this.state.get();
+  granted = (): boolean => this.state.get() === 'granted';
+
+  answer(state: 'granted' | 'denied') {
+    this.storage.set(this.keys.consent, state);
+    this.storage.set(this.keys.consentVersion, String(this.version));
+    this.state.set(state);
+  }
+}

package/src/tracking/core/engagement.ts

@@ -0,0 +1,47 @@
+/**
+ * Engaged time: the tab is visible AND the visitor did something (scroll, pointer,
+ * key, touch) within the last `windowMs`. Each interaction extends the engaged
+ * stretch to `interaction + windowMs`; hiding the tab ends it at once.
+ */
+export class EngagementClock {
+  private engagedMs = 0;
+  /** Start and end of the current engaged stretch (end is in the future while active). */
+  private from: number | null = null;
+  private until = 0;
+  private tabVisible = true;
+
+  constructor(private readonly windowMs: number) {}
+
+  reset() {
+    this.engagedMs = 0;
+    this.from = null;
+    this.until = 0;
+  }
+
+  activity(now: number) {
+    if (!this.tabVisible) return;
+    if (this.from != null && now <= this.until) {
+      this.until = now + this.windowMs;
+      return;
+    }
+    this.close(now);
+    this.from = now;
+    this.until = now + this.windowMs;
+  }
+
+  setTabVisible(visible: boolean, now: number) {
+    if (!visible) this.close(now);
+    this.tabVisible = visible;
+  }
+
+  private close(now: number) {
+    if (this.from == null) return;
+    this.engagedMs += Math.max(0, Math.min(now, this.until) - this.from);
+    this.from = null;
+  }
+
+  total(now: number): number {
+    const open = this.from != null ? Math.max(0, Math.min(now, this.until) - this.from) : 0;
+    return Math.round(this.engagedMs + open);
+  }
+}

package/src/tracking/core/experiments.ts

@@ -0,0 +1,258 @@
+import { hashV2 } from './hash';
+import { Observable } from './observable';
+import { readJson, writeJson, type IStorage } from './storage';
+import { KEYS, type IExperimentDefinition, type IExperimentVariant, type TStorageKeys } from './types';
+
+/**
+ * Client-side assignment (§5 of the contract). No round trip: the running
+ * experiments are fetched once (public fields only) and every visitor is bucketed
+ * locally from their `vid`, the same way every time, on any page.
+ */
+
+export type TAssignmentReason =
+  /** Bucketed into a variant: an exposure is logged when the trigger is seen. */
+  | 'assigned'
+  /** Outside the experiment's traffic share: control, no exposure. */
+  | 'not-enrolled'
+  /** Targeting (path, device, language) does not match: control, no exposure. */
+  | 'not-targeted'
+  /** No consent (no vid) or tracking disabled: control, no exposure. */
+  | 'no-consent'
+  /** Definitions not loaded (yet, or the endpoint is missing) or experiment not running: control. */
+  | 'not-running'
+  /** A preview link (`?qa_variant=`) or the in-app version switch: that variant, never logged. */
+  | 'preview'
+  /** The experiment ended: everybody sees the winner, nothing is logged. */
+  | 'concluded';
+
+export interface IAssignment {
+  key: string;
+  variant: string;
+  /** Whether this visitor counts for the experiment (exposure is logged). */
+  enrolled: boolean;
+  reason: TAssignmentReason;
+  /** The section whose being seen logs the exposure; null → on render. */
+  trigger: string | null;
+}
+
+export interface IAssignContext {
+  path: string;
+  device?: 'desktop' | 'tablet' | 'mobile';
+  lang?: string;
+}
+
+export const controlOf = (variants: IExperimentVariant[], fallback = 'a'): string =>
+  (variants.find((v) => v.control) ?? variants[0])?.key ?? fallback;
+
+/**
+ * GrowthBook's bucket ranges: variant i owns `[c_i, c_i + traffic * w_i)` where
+ * `c_i` is the sum of the weights before it. The enrolled share equals `traffic`,
+ * and raising `traffic` later never moves an enrolled visitor to another variant.
+ * Weights that do not add up to 1 are normalised.
+ */
+export const bucketRanges = (weights: number[], traffic: number): [number, number][] => {
+  const cover = Math.min(1, Math.max(0, Number.isFinite(traffic) ? traffic : 0));
+  const clean = weights.map((w) => (Number.isFinite(w) && w > 0 ? w : 0));
+  const sum = clean.reduce((a, b) => a + b, 0);
+  const norm = sum > 0 ? clean.map((w) => w / sum) : clean.map(() => 1 / clean.length);
+  let cumulative = 0;
+  return norm.map((w) => {
+    const start = cumulative;
+    cumulative += w;
+    return [start, start + cover * w];
+  });
+};
+
+/** `/` matches `/` only; `/blog/*` matches `/blog/` and everything under it. */
+export const pathMatches = (patterns: string[] | null | undefined, path: string): boolean => {
+  if (!patterns || !patterns.length) return true;
+  const clean = path.split(/[?#]/)[0] || '/';
+  return patterns.some((p) => (p.endsWith('*') ? clean.startsWith(p.slice(0, -1)) : clean === p || clean === `${p}/`));
+};
+
+const targeted = (def: IExperimentDefinition, ctx: IAssignContext): boolean => {
+  const t = def.targeting;
+  if (!t) return true;
+  if (!pathMatches(t.paths, ctx.path)) return false;
+  if (t.device && ctx.device && t.device !== ctx.device) return false;
+  if (t.lang && ctx.lang && !ctx.lang.toLowerCase().startsWith(t.lang.toLowerCase())) return false;
+  return true;
+};
+
+/** Pure assignment of one visitor to one experiment. */
+export const assign = (def: IExperimentDefinition, vid: string | null, ctx: IAssignContext): IAssignment => {
+  const control = controlOf(def.variants);
+  const trigger = def.trigger?.section ?? null;
+  const base = { key: def.key, variant: control, enrolled: false, trigger };
+  if (def.status === 'concluded') return { ...base, variant: def.winner || control, reason: 'concluded' };
+  if (!vid) return { ...base, reason: 'no-consent' };
+  if (!def.variants.length) return { ...base, reason: 'not-running' };
+  if (!targeted(def, ctx)) return { ...base, reason: 'not-targeted' };
+  const n = hashV2(def.key, vid);
+  const ranges = bucketRanges(
+    def.variants.map((v) => v.weight),
+    def.traffic,
+  );
+  const i = ranges.findIndex(([from, to]) => n >= from && n < to);
+  if (i < 0) return { ...base, reason: 'not-enrolled' };
+  return { ...base, variant: def.variants[i].key, enrolled: true, reason: 'assigned' };
+};
+
+/** The default preview query parameter. */
+export const DEFAULT_PREVIEW_PARAM = 'qa_variant';
+
+/**
+ * `?qa_variant=signup-cta:b,other:a` → `{ 'signup-cta': 'b', other: 'a' }`.
+ * `?qa_variant=clear` (or `off`) → `{}` and clears the saved preview.
+ * Returns null when the parameter is absent. `param` names the query parameter.
+ */
+export const parsePreview = (search: string, param: string = DEFAULT_PREVIEW_PARAM): Record<string, string> | null => {
+  let raw: string | null = null;
+  try {
+    raw = new URLSearchParams(search).get(param);
+  } catch {
+    return null;
+  }
+  if (raw == null) return null;
+  const out: Record<string, string> = {};
+  if (raw === 'clear' || raw === 'off') return out;
+  raw.split(',').forEach((pair) => {
+    const [k, v] = pair.split(':').map((s) => s?.trim());
+    if (k && v && /^[\w.-]{1,80}$/.test(k) && /^[\w.-]{1,40}$/.test(v)) out[k] = v;
+  });
+  return out;
+};
+
+export type TExperimentsStatus = 'idle' | 'loading' | 'ready' | 'failed';
+
+interface ICache {
+  at: number;
+  property: string;
+  experiments: IExperimentDefinition[];
+}
+
+/** Cached definitions are used for a flicker-free first render for up to a day, then refreshed. */
+const CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 4000;
+
+/** A usable entry, normalised (a concluded entry gets `variants: []`); null for junk. */
+export const normaliseDefinition = (x: unknown): IExperimentDefinition | null => {
+  const d = x as IExperimentDefinition;
+  if (!d || typeof d.key !== 'string') return null;
+  if (d.status === 'concluded') return typeof d.winner === 'string' && d.winner ? { ...d, variants: d.variants ?? [] } : null;
+  if (d.status && d.status !== 'running') return null;
+  const ok = Array.isArray(d.variants) && d.variants.every((v) => v && typeof v.key === 'string' && typeof v.weight === 'number');
+  return ok ? d : null;
+};
+
+export interface IExperimentsDeps {
+  property: string;
+  endpoint: string;
+  local: IStorage;
+  session: IStorage;
+  now: () => number;
+  fetchJson: (url: string, timeoutMs: number) => Promise<unknown>;
+  /** Storage keys (default prefix `qa.`). */
+  keys?: TStorageKeys;
+  /** The preview query parameter (default `qa_variant`). */
+  previewParam?: string;
+}
+
+/** Holds the running experiments and the preview overrides. */
+export class ExperimentStore {
+  readonly status = new Observable<TExperimentsStatus>('idle');
+  /**
+   * An in-app version switch, per experiment (`{ key: variant }`), in this browser's
+   * localStorage (an editor lets its user see each version). A preview: never logged.
+   * Rendered variants follow it live.
+   */
+  readonly editorOverrides: Observable<Record<string, string>>;
+  /**
+   * Bumped by `refresh()` (an editor, after it accepted a winner or removed a version): mounted
+   * experiments decide again, so an accepted test shows its winner at once. Visitors never
+   * trigger it, so their variant stays fixed for the page view.
+   */
+  readonly revision = new Observable<number>(0);
+  private definitions = new Map<string, IExperimentDefinition>();
+  private preview: Record<string, string>;
+  private readonly keys: TStorageKeys;
+
+  constructor(private readonly d: IExperimentsDeps) {
+    this.keys = d.keys ?? KEYS;
+    this.preview = readJson<Record<string, string>>(d.session, this.keys.preview) ?? {};
+    this.editorOverrides = new Observable<Record<string, string>>(readJson<Record<string, string>>(d.local, this.keys.editorVariants) ?? {});
+    const cache = readJson<ICache>(d.local, this.keys.experimentsCache);
+    if (cache && cache.property === d.property && d.now() - cache.at < CACHE_MAX_AGE_MS && Array.isArray(cache.experiments)) {
+      this.setDefinitions(cache.experiments);
+      this.status.set('ready');
+    }
+  }
+
+  /** Reads the preview parameter (`?qa_variant=`) from the URL; the preview sticks for the browser session. */
+  applyPreviewFrom(search: string) {
+    const parsed = parsePreview(search, this.d.previewParam ?? DEFAULT_PREVIEW_PARAM);
+    if (!parsed) return;
+    this.preview = Object.keys(parsed).length ? { ...this.preview, ...parsed } : {};
+    if (Object.keys(this.preview).length) writeJson(this.d.session, this.keys.preview, this.preview);
+    else this.d.session.remove(this.keys.preview);
+  }
+
+  /** The in-app switch first, then a preview link. */
+  previewOf = (key: string): string | undefined => this.editorOverrides.get()[key] ?? this.preview[key];
+
+  editorOverrideOf = (key: string): string | undefined => this.editorOverrides.get()[key];
+
+  /** The in-app version switch for one experiment; `null` goes back to the visitor's own variant. */
+  setEditorOverride(key: string, variant: string | null) {
+    const next = { ...this.editorOverrides.get() };
+    if (variant) next[key] = variant;
+    else delete next[key];
+    if (Object.keys(next).length) writeJson(this.d.local, this.keys.editorVariants, next);
+    else this.d.local.remove(this.keys.editorVariants);
+    this.editorOverrides.set(next);
+  }
+
+  /** Re-reads the switches (another window of the same app changed them). */
+  reloadEditorOverrides() {
+    const stored = readJson<Record<string, string>>(this.d.local, this.keys.editorVariants) ?? {};
+    if (JSON.stringify(stored) !== JSON.stringify(this.editorOverrides.get())) this.editorOverrides.set(stored);
+  }
+
+  /** Loads the definitions again and makes mounted experiments decide again (for an editor, never for visitors). */
+  async refresh(): Promise<void> {
+    await this.load(true);
+    this.revision.set(this.revision.get() + 1);
+  }
+
+  private setDefinitions(list: unknown[]) {
+    this.definitions = new Map(
+      list.map(normaliseDefinition).filter((d): d is IExperimentDefinition => !!d).map((d) => [d.key, d]),
+    );
+  }
+
+  get(key: string) {
+    return this.definitions.get(key);
+  }
+
+  /** Fetches the running experiments; a missing endpoint leaves everyone on the control. */
+  async load(force = false): Promise<void> {
+    if (this.status.get() === 'loading' && !force) return;
+    const hadCache = this.status.get() === 'ready';
+    if (!hadCache) this.status.set('loading');
+    try {
+      const sep = this.d.endpoint.includes('?') ? '&' : '?';
+      const body = await this.d.fetchJson(`${this.d.endpoint}${sep}property=${encodeURIComponent(this.d.property)}`, FETCH_TIMEOUT_MS);
+      const list = Array.isArray(body) ? body : ((body as { experiments?: unknown[] } | null)?.experiments ?? null);
+      if (!Array.isArray(list)) throw new Error('unexpected experiments payload');
+      this.setDefinitions(list);
+      writeJson(this.d.local, this.keys.experimentsCache, {
+        at: this.d.now(),
+        property: this.d.property,
+        experiments: Array.from(this.definitions.values()),
+      } satisfies ICache);
+      this.status.set('ready');
+    } catch {
+      if (!hadCache) this.status.set('failed');
+    }
+  }
+}

package/src/tracking/core/hash.ts

@@ -0,0 +1,26 @@
+/**
+ * Deterministic bucketing: GrowthBook's hash v2 (MIT), so assignments match what
+ * GrowthBook-compatible tooling (and the server, if it ever recomputes) gets.
+ *
+ *   n = (fnv1a32(String(fnv1a32(seed + value))) % 10000) / 10000
+ *
+ * The inner hash is turned into its *decimal string* before it is hashed again —
+ * that is GrowthBook's definition (`hashFnv32a(hashFnv32a(seed + value) + "")`).
+ * Characters are hashed as UTF-16 code units (`charCodeAt`), like GrowthBook; for
+ * the ASCII ids and keys we use that equals FNV-1a over the bytes.
+ */
+
+/** FNV-1a, 32 bit. `fnv1a32('a') === 0xe40c292c` (the reference test vector). */
+export const fnv1a32 = (input: string): number => {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    // h *= 16777619 (the FNV prime) in 32-bit arithmetic, as shifts and adds.
+    h += (h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24);
+  }
+  return h >>> 0;
+};
+
+/** A number in [0, 1) with 4 decimals; the same inputs always give the same number. */
+export const hashV2 = (seed: string, value: string): number =>
+  (fnv1a32(String(fnv1a32(seed + value))) % 10000) / 10000;

package/src/tracking/core/ids.ts

@@ -0,0 +1,25 @@
+/** Random ids from the platform CSPRNG (never Math.random: ids must not collide or be guessable). */
+
+const toBase64Url = (bytes: Uint8Array): string => {
+  let bin = '';
+  bytes.forEach((b) => (bin += String.fromCharCode(b)));
+  return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+};
+
+/** `bytes` random bytes as base64url: 16 bytes = 128 bits = 22 characters. */
+export const randomId = (bytes = 16): string => {
+  const buf = new Uint8Array(bytes);
+  globalThis.crypto.getRandomValues(buf);
+  return toBase64Url(buf);
+};
+
+/** Event id (a UUID v4). */
+export const eventId = (): string => {
+  if (typeof globalThis.crypto?.randomUUID === 'function') return globalThis.crypto.randomUUID();
+  const b = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(b);
+  b[6] = (b[6] & 0x0f) | 0x40;
+  b[8] = (b[8] & 0x3f) | 0x80;
+  const h = Array.from(b).map((x) => x.toString(16).padStart(2, '0')).join('');
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+};

package/src/tracking/core/observable.ts

@@ -0,0 +1,23 @@
+type TListener = () => void;
+
+/** A tiny observable value (what React's `useSyncExternalStore` wants). */
+export class Observable<T> {
+  private listeners = new Set<TListener>();
+  constructor(private value: T) {}
+  get = (): T => this.value;
+  set(next: T) {
+    if (Object.is(next, this.value)) return;
+    this.value = next;
+    this.listeners.forEach((l) => {
+      try {
+        l();
+      } catch {
+        /* a listener never breaks the tracker */
+      }
+    });
+  }
+  subscribe = (listener: TListener) => {
+    this.listeners.add(listener);
+    return () => void this.listeners.delete(listener);
+  };
+}