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

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);
+  };
+}

package/src/tracking/core/queue.ts

@@ -0,0 +1,131 @@
+import type { IBatch, ITrackedEvent } from './types';
+
+/**
+ * How a batch leaves the page. `beacon` is used when the page is going away
+ * (`pagehide`, tab hidden): the browser delivers it after the page is gone.
+ * Resolves to `true` when the batch was handed over, `false` to keep it for later
+ * (network error), and never rejects.
+ */
+export interface ITransport {
+  send(body: string, mode: 'fetch' | 'beacon'): Promise<boolean>;
+}
+
+/** Collector limits (§4): at most 100 events and 64 KB per batch. We stay under both. */
+export const MAX_EVENTS_PER_BATCH = 100;
+export const MAX_BATCH_BYTES = 60 * 1024;
+/** Events kept while the collector is unreachable; the oldest are dropped past this. */
+export const MAX_BACKLOG = 500;
+
+export interface IQueueOptions {
+  flushIntervalMs: number;
+  maxQueued: number;
+  transport: ITransport;
+  /** The envelope for a batch; null → nothing may be sent (no consent) and the queue is dropped. */
+  envelope: () => Omit<IBatch, 'events' | 'sent_at'> | null;
+  now: () => number;
+  /** Timers are injected so tests can drive them. */
+  setTimer: (fn: () => void, ms: number) => unknown;
+  clearTimer: (handle: unknown) => void;
+  debug?: (batch: IBatch) => void;
+}
+
+const size = (s: string) => (typeof TextEncoder !== 'undefined' ? new TextEncoder().encode(s).length : s.length * 2);
+
+/**
+ * Batches events: sends every `flushIntervalMs`, as soon as `maxQueued` are waiting,
+ * and immediately (as a beacon) when the page is going away.
+ */
+export class EventQueue {
+  private events: ITrackedEvent[] = [];
+  private timer: unknown = null;
+  private sending = false;
+
+  constructor(private readonly o: IQueueOptions) {}
+
+  get length() {
+    return this.events.length;
+  }
+
+  push(event: ITrackedEvent) {
+    this.events.push(event);
+    if (this.events.length > MAX_BACKLOG) this.events.splice(0, this.events.length - MAX_BACKLOG);
+    if (this.events.length >= this.o.maxQueued) void this.flush('fetch');
+    else this.schedule();
+  }
+
+  /** Forget everything unsent (consent withdrawn). */
+  clear() {
+    this.events = [];
+    if (this.timer != null) this.o.clearTimer(this.timer);
+    this.timer = null;
+  }
+
+  private schedule() {
+    if (this.timer != null) return;
+    this.timer = this.o.setTimer(() => {
+      this.timer = null;
+      void this.flush('fetch');
+    }, this.o.flushIntervalMs);
+  }
+
+  /** Splits `events` into batches that fit the collector's limits. */
+  static chunk(events: ITrackedEvent[], envelope: Omit<IBatch, 'events' | 'sent_at'>, sentAt: string): IBatch[] {
+    const batches: IBatch[] = [];
+    let current: ITrackedEvent[] = [];
+    const bodyOf = (evts: ITrackedEvent[]) => JSON.stringify({ ...envelope, sent_at: sentAt, events: evts });
+    for (const e of events) {
+      const next = [...current, e];
+      if (current.length && (next.length > MAX_EVENTS_PER_BATCH || size(bodyOf(next)) > MAX_BATCH_BYTES)) {
+        batches.push({ ...envelope, sent_at: sentAt, events: current });
+        current = [e];
+      } else {
+        current = next;
+      }
+    }
+    if (current.length) batches.push({ ...envelope, sent_at: sentAt, events: current });
+    // A single event larger than the limit is dropped rather than rejected forever.
+    return batches.filter((b) => b.events.length > 1 || size(JSON.stringify(b)) <= MAX_BATCH_BYTES);
+  }
+
+  async flush(mode: 'fetch' | 'beacon' = 'fetch'): Promise<void> {
+    if (this.timer != null) {
+      this.o.clearTimer(this.timer);
+      this.timer = null;
+    }
+    if (!this.events.length) return;
+    // A fetch in flight owns the queue; a beacon (page going away) sends what is left now.
+    if (this.sending && mode === 'fetch') {
+      this.schedule();
+      return;
+    }
+    const envelope = this.o.envelope();
+    if (!envelope) {
+      this.events = [];
+      return;
+    }
+    const pending = this.events;
+    this.events = [];
+    const batches = EventQueue.chunk(pending, envelope, new Date(this.o.now()).toISOString());
+    this.sending = true;
+    const failed: ITrackedEvent[] = [];
+    try {
+      for (const batch of batches) {
+        this.o.debug?.(batch);
+        let ok = false;
+        try {
+          ok = await this.o.transport.send(JSON.stringify(batch), mode);
+        } catch {
+          ok = false;
+        }
+        if (!ok) failed.push(...batch.events);
+      }
+    } finally {
+      this.sending = false;
+    }
+    if (failed.length) {
+      // Kept for the next flush, which the next event schedules (no retry loop against a
+      // collector that is down); event ids make a double delivery harmless.
+      this.events = [...failed, ...this.events].slice(-MAX_BACKLOG);
+    }
+  }
+}

package/src/tracking/core/sections.ts

@@ -0,0 +1,166 @@
+/**
+ * Attention per section, as plain arithmetic over time (no DOM): the browser layer
+ * feeds it visibility changes from an IntersectionObserver and tab visibility, and
+ * asks it for the page summary.
+ *
+ * - `visible_ms`: time any part of the section was on screen while the tab was visible.
+ * - `seen`: the section was at least 50% visible for at least 1 s in one stretch — the
+ *   attention definition the contract uses everywhere (§4). "50% visible" is 50% of
+ *   the section *or* 50% of the viewport covered by it: a section taller than two
+ *   screens can never show half of itself, and it would otherwise never count.
+ * - `first_seen_ms`: when that stretch began, measured from the start of the page view.
+ */
+
+export const SEEN_RATIO = 0.5;
+export const SEEN_MS = 1000;
+
+export interface ISectionSummary {
+  id: string;
+  visible_ms: number;
+  seen: boolean;
+  first_seen_ms: number | null;
+}
+
+interface ISectionState {
+  id: string;
+  /** Effective visibility 0..1 (see above). */
+  ratio: number;
+  visibleMs: number;
+  visibleSince: number | null;
+  halfSince: number | null;
+  seenAt: number | null;
+  firstSeenMs: number | null;
+  /** Reported in the page summary (false for synthetic experiment triggers). */
+  report: boolean;
+}
+
+export class SectionClock {
+  private sections = new Map<string, ISectionState>();
+  private tabVisible = true;
+  private seenListeners = new Set<(id: string) => void>();
+
+  constructor(private start: number) {}
+
+  /** A new page view: everything starts from zero at `now`. */
+  reset(now: number) {
+    this.start = now;
+    const ids = Array.from(this.sections.values()).map((s) => [s.id, s.report] as const);
+    this.sections.clear();
+    ids.forEach(([id, report]) => this.ensure(id, report));
+  }
+
+  onSeen(listener: (id: string) => void) {
+    this.seenListeners.add(listener);
+    return () => void this.seenListeners.delete(listener);
+  }
+
+  isSeen = (id: string) => this.sections.get(id)?.seenAt != null;
+
+  private ensure(id: string, report = true): ISectionState {
+    let s = this.sections.get(id);
+    if (!s) {
+      s = { id, ratio: 0, visibleMs: 0, visibleSince: null, halfSince: null, seenAt: null, firstSeenMs: null, report };
+      this.sections.set(id, s);
+    }
+    return s;
+  }
+
+  /** Registers a section so it shows up in the summary even if it is never on screen. */
+  register(id: string, report = true) {
+    this.ensure(id, report).report ||= report;
+  }
+
+  /** The section's effective visibility changed. */
+  update(id: string, ratio: number, now: number) {
+    const s = this.ensure(id);
+    if (this.tabVisible) {
+      const wasVisible = s.ratio > 0;
+      const isVisible = ratio > 0;
+      if (wasVisible && !isVisible && s.visibleSince != null) {
+        s.visibleMs += Math.max(0, now - s.visibleSince);
+        s.visibleSince = null;
+      }
+      if (!wasVisible && isVisible) s.visibleSince = now;
+      // A stretch at >= 50% continues through ratio changes above the line.
+      const wasHalf = s.ratio >= SEEN_RATIO;
+      const isHalf = ratio >= SEEN_RATIO;
+      if (wasHalf && !isHalf) {
+        this.tickOne(s, now);
+        s.halfSince = null;
+      }
+      if (!wasHalf && isHalf) s.halfSince = now;
+    }
+    s.ratio = ratio;
+  }
+
+  /** The tab became visible or hidden: time stops counting while hidden. */
+  setTabVisible(visible: boolean, now: number) {
+    if (visible === this.tabVisible) return;
+    this.sections.forEach((s) => this.settle(s, now));
+    this.tabVisible = visible;
+    this.sections.forEach((s) => this.arm(s, now));
+  }
+
+  /** Promotes stretches that have lasted long enough to `seen`. Call ~every second. */
+  tick(now: number) {
+    this.sections.forEach((s) => this.tickOne(s, now));
+  }
+
+  /** Closes the open stretches up to `now` (visible time, seen). */
+  private settle(s: ISectionState, now: number) {
+    if (s.visibleSince != null) s.visibleMs += Math.max(0, now - s.visibleSince);
+    s.visibleSince = null;
+    this.tickOne(s, now);
+    s.halfSince = null;
+  }
+
+  private tickOne(s: ISectionState, now: number) {
+    if (s.seenAt == null && s.halfSince != null && now - s.halfSince >= SEEN_MS) {
+      s.seenAt = now;
+      s.firstSeenMs = Math.max(0, s.halfSince - this.start);
+      this.seenListeners.forEach((l) => l(s.id));
+    }
+  }
+
+  /** Opens stretches for the current state. */
+  private arm(s: ISectionState, now: number) {
+    if (!this.tabVisible) return;
+    if (s.ratio > 0) s.visibleSince = now;
+    if (s.ratio >= SEEN_RATIO) s.halfSince = now;
+  }
+
+  /** The section most on screen now (ties: the lower one on the page, i.e. the later registered). */
+  current(): string | null {
+    let best: ISectionState | null = null;
+    for (const s of Array.from(this.sections.values())) {
+      if (s.report && s.ratio > 0 && (!best || s.ratio >= best.ratio)) best = s;
+    }
+    return best?.id ?? null;
+  }
+
+  summary(now: number): ISectionSummary[] {
+    this.tick(now);
+    return Array.from(this.sections.values())
+      .filter((s) => s.report)
+      .map((s) => ({
+        id: s.id,
+        visible_ms: Math.round(s.visibleMs + (s.visibleSince != null ? Math.max(0, now - s.visibleSince) : 0)),
+        seen: s.seenAt != null,
+        first_seen_ms: s.firstSeenMs,
+      }));
+  }
+}
+
+/**
+ * Effective visibility from an IntersectionObserver entry: the larger of the share
+ * of the section on screen and the share of the viewport the section fills.
+ */
+export const effectiveRatio = (
+  intersectionRatio: number,
+  intersectionHeight: number,
+  viewportHeight: number,
+): number => {
+  if (intersectionRatio <= 0) return 0;
+  const cover = viewportHeight > 0 ? intersectionHeight / viewportHeight : 0;
+  return Math.min(1, Math.max(intersectionRatio, cover));
+};