@drip-apex/sdk 0.1.0 → 0.3.0

package/src/consent-evaluation-borlabs.test.ts

@@ -0,0 +1,41 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { readBorlabsConsent } from "./consent-evaluation";
+
+describe("readBorlabsConsent", () => {
+  afterEach(() => {
+    delete (globalThis as Record<string, unknown>).BorlabsCookie;
+    if (typeof window !== "undefined") delete (window as unknown as Record<string, unknown>).BorlabsCookie;
+  });
+
+  it.each([true, false])("returns v3 service consent when hasConsent returns %s", (granted) => {
+    const hasConsent = vi.fn(() => granted);
+    const hasConsentForServiceGroup = vi.fn(() => false);
+    (globalThis as any).BorlabsCookie = { Consents: { hasConsent, hasConsentForServiceGroup } };
+
+    expect(readBorlabsConsent("apex-analytics")).toBe(granted);
+    expect(hasConsent).toHaveBeenCalledWith("apex-analytics");
+    expect(hasConsentForServiceGroup).toHaveBeenCalledTimes(granted ? 0 : 1);
+  });
+
+  it("falls back to the v3 service group API and defaults to statistics", () => {
+    const hasConsent = vi.fn(() => false);
+    const hasConsentForServiceGroup = vi.fn(() => true);
+    (globalThis as any).BorlabsCookie = { Consents: { hasConsent, hasConsentForServiceGroup } };
+
+    expect(readBorlabsConsent("  ")).toBe(true);
+    expect(hasConsent).toHaveBeenCalledWith("statistics");
+    expect(hasConsentForServiceGroup).toHaveBeenCalledWith("statistics");
+  });
+
+  it("falls back to the v2 API when v3 methods are unavailable", () => {
+    const checkCookieConsent = vi.fn(() => true);
+    (globalThis as any).BorlabsCookie = { checkCookieConsent };
+
+    expect(readBorlabsConsent("statistics")).toBe(true);
+    expect(checkCookieConsent).toHaveBeenCalledWith("statistics");
+  });
+
+  it("returns unknown when Borlabs is absent", () => {
+    expect(readBorlabsConsent()).toBeNull();
+  });
+});

package/src/consent-evaluation-cookiescript.test.ts

@@ -0,0 +1,50 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { readCookieScriptConsent } from "./consent-evaluation";
+
+function installCookie(value: string): void {
+  Object.defineProperty(globalThis, "document", {
+    configurable: true,
+    value: { cookie: `other=1; CookieScriptConsent=${value}; trailing=1` },
+  });
+}
+
+describe("CookieScript consent cookie fallback", () => {
+  afterEach(() => {
+    delete (globalThis as Record<string, unknown>).CookieScript;
+    delete (globalThis as Record<string, unknown>).document;
+  });
+
+  it.each([
+    ["JSON-encoded categories", JSON.stringify(["functionality", "performance"])],
+    ["array categories", ["functionality", "performance"]],
+  ])("maps analytics to performance for %s", (_label, categories) => {
+    installCookie(encodeURIComponent(JSON.stringify({ action: "accept", categories })));
+    expect(readCookieScriptConsent("analytics")).toBe(true);
+  });
+
+  it("returns false for rejection", () => {
+    installCookie(encodeURIComponent(JSON.stringify({ action: "reject" })));
+    expect(readCookieScriptConsent("analytics")).toBe(false);
+  });
+
+  it("returns null before CookieScript records an action", () => {
+    installCookie(encodeURIComponent(JSON.stringify({ bannershown: 1 })));
+    expect(readCookieScriptConsent("analytics")).toBeNull();
+  });
+
+  it.each(["%E0%A4%A", encodeURIComponent("not json")])(
+    "returns null for malformed cookie %s",
+    (value) => {
+      installCookie(value);
+      expect(readCookieScriptConsent("analytics")).toBeNull();
+    },
+  );
+
+  it("keeps the CookieScript instance primary when it disagrees with the cookie", () => {
+    installCookie(encodeURIComponent(JSON.stringify({ action: "accept", categories: ["performance"] })));
+    (globalThis as Record<string, any>).CookieScript = {
+      instance: { currentState: () => ({ action: "reject" }) },
+    };
+    expect(readCookieScriptConsent("analytics")).toBe(false);
+  });
+});

package/src/consent-evaluation.ts

@@ -0,0 +1,151 @@
+export type SynchronousConsentInput = {
+  requireConsent?: boolean;
+  hasConsent?: boolean;
+  consentModeEnabled?: boolean;
+  configuredConsentGranted?: boolean | null;
+  consentCookieGranted: boolean;
+  respectDoNotTrack?: boolean;
+  doNotTrackValue?: string;
+};
+
+export type ConsentProvider = "custom" | "onetrust" | "usercentrics" | "cookiebot" | "ccm19" | "pandectes" | "cookiescript" | "borlabs";
+
+export function readPath(root: unknown, path?: string): unknown {
+  let current = root as Record<string, unknown> | undefined;
+  for (const part of (path ?? "").split(".").map((item) => item.trim()).filter(Boolean)) {
+    if (!current || typeof current !== "object") return undefined;
+    current = current[part] as Record<string, unknown> | undefined;
+  }
+  return current;
+}
+
+function tokenMatches(value: unknown, required: string): boolean {
+  return value != null && String(value).trim().toLowerCase() === required.trim().toLowerCase();
+}
+
+export function readConsentCookie(name: string): string {
+  try {
+    const match = document.cookie.match(new RegExp("(?:^|;)\\s*" + name + "=([^;]*)"));
+    return match ? decodeURIComponent(match[1]) : "";
+  } catch { return ""; }
+}
+
+/** The SDK's synchronous native-CMP readers, shared with the pre-SDK capture fragment. */
+export function readConfiguredConsent(provider?: ConsentProvider, requiredGroup?: string, getter?: string): boolean | null {
+  const root = globalThis as Record<string, any>;
+  if (provider === "cookiescript") return readCookieScriptConsent(requiredGroup);
+  if (provider === "borlabs") return readBorlabsConsent(requiredGroup);
+  if (provider === "usercentrics") {
+    const uc = root.UC_UI ?? root.window?.UC_UI;
+    if (typeof uc?.getServicesBaseInfo !== "function") return null;
+    let services: unknown;
+    try { services = uc.getServicesBaseInfo(); } catch { return null; }
+    if (!Array.isArray(services)) return null;
+    const required = requiredGroup?.trim() || "Apex";
+    const service = services.find((item) => item && typeof item === "object" &&
+      ["name", "id", "serviceId", "templateId", "dataProcessor", "dataProcessorName"]
+        .some((key) => tokenMatches((item as Record<string, unknown>)[key], required))) as Record<string, any> | undefined;
+    return service ? service.consent?.status === true || service.consentStatus === true || service.status === true : false;
+  }
+  if (provider === "cookiebot") {
+    const consent = (root.Cookiebot ?? root.window?.Cookiebot)?.consent;
+    if (!consent || typeof consent !== "object") return null;
+    const aliases: Record<string, string> = { analytics: "statistics", stats: "statistics", statistic: "statistics", preference: "preferences" };
+    const key = aliases[(requiredGroup?.trim() || "statistics").toLowerCase()] || (requiredGroup?.trim() || "statistics").toLowerCase();
+    return typeof consent[key] === "boolean" ? consent[key] : false;
+  }
+  if (provider === "ccm19") {
+    const embeddings = (root.CCM ?? root.window?.CCM)?.acceptedEmbeddings;
+    if (!Array.isArray(embeddings)) return null;
+    const required = requiredGroup?.trim() || "Apex";
+    return embeddings.some((item) => item && typeof item === "object" &&
+      (tokenMatches((item as any).name, required) || (item as any).id === required));
+  }
+  if (provider === "pandectes") {
+    const purpose = (requiredGroup?.trim() || "analytics").toLowerCase();
+    const method = ({ analytics: "analyticsProcessingAllowed", statistics: "analyticsProcessingAllowed", statistic: "analyticsProcessingAllowed", stats: "analyticsProcessingAllowed", marketing: "marketingAllowed", preferences: "preferencesProcessingAllowed", preference: "preferencesProcessingAllowed", sale_of_data: "saleOfDataAllowed", saleofdata: "saleOfDataAllowed", "sale-of-data": "saleOfDataAllowed", sale: "saleOfDataAllowed" } as Record<string, string>)[purpose];
+    if (!method) return false;
+    for (const source of [root.Pandectes ?? root.window?.Pandectes, root.Shopify?.customerPrivacy ?? root.window?.Shopify?.customerPrivacy]) {
+      try { const value = source?.[method]?.(); if (typeof value === "boolean") return value; } catch {}
+    }
+    return null;
+  }
+  if (provider === "onetrust" || provider === "custom" || getter) {
+    const raw = readPath(root, getter ?? "OnetrustActiveGroups");
+    if (typeof raw === "boolean") return raw;
+    if (raw == null) return null;
+    const required = requiredGroup;
+    if (!required) return raw != null && String(raw).trim() !== "";
+    if (Array.isArray(raw)) return raw.map(String).includes(required);
+    if (typeof raw === "string") return raw.split(",").map((item) => item.trim()).filter(Boolean).includes(required);
+    return raw == null ? null : false;
+  }
+  return null;
+}
+
+export function readBorlabsConsent(requiredGroup?: string): boolean | null {
+  const root = globalThis as Record<string, any>;
+  const borlabs = root.BorlabsCookie ?? root.window?.BorlabsCookie;
+  if (!borlabs) return null;
+  const required = requiredGroup?.trim() || "statistics";
+  const consents = borlabs.Consents;
+  try { if (typeof consents?.hasConsent === "function" && consents.hasConsent(required)) return true; } catch {}
+  try { if (typeof consents?.hasConsentForServiceGroup === "function") return Boolean(consents.hasConsentForServiceGroup(required)); } catch {}
+  try { if (typeof borlabs.checkCookieConsent === "function") return Boolean(borlabs.checkCookieConsent(required)); } catch {}
+  return null;
+}
+
+export function readCookieScriptConsent(requiredGroup?: string): boolean | null {
+  const root = globalThis as Record<string, any>;
+  const requested = (requiredGroup?.trim() || "analytics").toLowerCase();
+  const aliases: Record<string, string> = {
+    analytics: "performance", statistics: "performance", statistic: "performance", stats: "performance",
+    marketing: "targeting", advertising: "targeting", ads: "targeting", functional: "functionality",
+    preferences: "functionality", preference: "functionality", necessary: "strict", essential: "strict",
+  };
+  const required = aliases[requested] || requested;
+  const instance = root.CookieScript?.instance
+    ?? (root.window as Record<string, any> | undefined)?.CookieScript?.instance;
+  let currentState: unknown;
+  if (instance && typeof instance === "object" && typeof instance.currentState === "function") {
+    try { currentState = instance.currentState(); } catch {}
+  }
+  if (!currentState || typeof currentState !== "object" || Array.isArray(currentState)) {
+    try {
+      currentState = JSON.parse(readConsentCookie("CookieScriptConsent"));
+      const categories = (currentState as Record<string, unknown>).categories;
+      if (typeof categories === "string") (currentState as Record<string, unknown>).categories = JSON.parse(categories);
+    } catch { return null; }
+  }
+  if (!currentState || typeof currentState !== "object" || Array.isArray(currentState)) return null;
+  const consent = currentState as Record<string, unknown>;
+  if (consent.action === "reject") return false;
+  if (consent.action !== "accept") return null;
+  const categories = consent.categories;
+  if (!Array.isArray(categories)) return false;
+  return categories.some((item) => String(item).toLowerCase() === required);
+}
+
+export const CONSENT_REQUIRED = 1;
+export const CONSENT_GRANTED = 2;
+export const DNT_BLOCKED = 4;
+export const STORAGE_ALLOWED = 8;
+
+export function resolveSynchronousConsentGranted(input: SynchronousConsentInput & { provider?: ConsentProvider }): boolean {
+  return Boolean(evaluateSynchronousConsentForProvider(input) & CONSENT_GRANTED);
+}
+
+export function evaluateSynchronousConsentForProvider(input: SynchronousConsentInput & { provider?: ConsentProvider }): number {
+  const configured = input.configuredConsentGranted
+    ?? (input.provider === "cookiescript" ? false : null);
+  return evaluateSynchronousConsent({ ...input, configuredConsentGranted: configured });
+}
+
+/** Pure synchronous consent/DNT bitmask shared by SDK init and the inline bootstrap. */
+export function evaluateSynchronousConsent(input: SynchronousConsentInput): number {
+  const required = input.requireConsent === true || typeof input.hasConsent === "boolean" || input.consentModeEnabled === true;
+  const granted = !required || (typeof input.hasConsent === "boolean" ? input.hasConsent : input.configuredConsentGranted ?? input.consentCookieGranted);
+  const value = (input.doNotTrackValue ?? "").toLowerCase();
+  const dnt = input.respectDoNotTrack === true && (value === "1" || value === "yes");
+  return (required ? CONSENT_REQUIRED : 0) | (granted ? CONSENT_GRANTED : 0) | (dnt ? DNT_BLOCKED : 0) | (granted && !dnt ? STORAGE_ALLOWED : 0);
+}

package/src/css.test.ts

@@ -0,0 +1,30 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from "vitest";
+import { injectCss, removeAllCss, removeCssForOwner } from "./css";
+
+describe("CSS artifact journal", () => {
+  afterEach(() => {
+    removeAllCss();
+    document.head.innerHTML = "";
+  });
+
+  it("replaces stale content when an existing element id carries different CSS", () => {
+    injectCss(".hero{color:red}", "exp", "var", ["page-a"], "artifact-a");
+    injectCss(".hero{color:blue}", "exp", "var", ["page-a"], "artifact-a");
+
+    expect(document.getElementById("drip-css-exp-var")?.textContent).toBe(
+      ".hero{color:blue}",
+    );
+  });
+
+  it("keeps a shared artifact until its final owner tears down", () => {
+    injectCss(".hero{color:red}", "exp", "var", ["page-a"], "artifact-a");
+    injectCss(".hero{color:red}", "exp", "var", ["page-b"], "artifact-a");
+
+    removeCssForOwner("page-a");
+    expect(document.getElementById("drip-css-exp-var")).not.toBeNull();
+
+    removeCssForOwner("page-b");
+    expect(document.getElementById("drip-css-exp-var")).toBeNull();
+  });
+});

package/src/css.ts

@@ -1,17 +1,82 @@
 const CSS_CLASS = "drip-css";
 const CSS_LINK_CLASS = "drip-css-link";
+type CssJournalEntry = {
+  seq: number;
+  artifactId: string;
+  epoch: number;
+  owners: Set<string>;
+  target: Element;
+  state: "applied" | "invalidated";
+};
+const cssJournal: CssJournalEntry[] = [];
+let cssSequence = 0;
 
-export function injectCss(css: string, experimentId: string, variationId: string): void {
+function recordArtifact(
+  element: Element,
+  artifactId: string,
+  ownerKeys: readonly string[],
+  epoch: number,
+): void {
+  const existing = cssJournal.find(
+    (entry) => entry.target === element && entry.artifactId === artifactId,
+  );
+  if (existing) {
+    ownerKeys.forEach((ownerKey) => existing.owners.add(ownerKey));
+    existing.state = "applied";
+    existing.epoch = epoch;
+    return;
+  }
+  cssJournal.push({
+    seq: ++cssSequence,
+    artifactId,
+    epoch,
+    owners: new Set(ownerKeys),
+    target: element,
+    state: "applied",
+  });
+}
+
+function forgetElement(element: Element): void {
+  for (let index = cssJournal.length - 1; index >= 0; index -= 1) {
+    if (cssJournal[index].target === element) cssJournal.splice(index, 1);
+  }
+}
+
+export function injectCss(
+  css: string,
+  experimentId: string,
+  variationId: string,
+  ownerKeys: readonly string[] = [],
+  artifactId = "css:" + experimentId + ":" + variationId,
+  epoch = 0,
+): void {
   const id = "drip-css-" + experimentId + "-" + variationId;
-  if (document.getElementById(id)) return;
+  const existing = document.getElementById(id);
+  if (existing && existing.textContent === css) {
+    recordArtifact(existing, artifactId, ownerKeys, epoch);
+    return;
+  }
+  if (existing) {
+    forgetElement(existing);
+    existing.textContent = css;
+    recordArtifact(existing, artifactId, ownerKeys, epoch);
+    return;
+  }
   const style = document.createElement("style");
   style.id = id;
   style.className = CSS_CLASS;
   style.textContent = css;
+  recordArtifact(style, artifactId, ownerKeys, epoch);
   (document.head || document.documentElement).appendChild(style);
 }
 
-export function injectExperimentCss(css: string, experimentId: string): void {
+export function injectExperimentCss(
+  css: string,
+  experimentId: string,
+  ownerKeys: readonly string[] = [],
+  artifactId = "css:experiment:" + experimentId,
+  epoch = 0,
+): void {
   const id = "drip-css-exp-" + experimentId;
   let style = document.getElementById(id) as HTMLStyleElement | null;
   if (!style) {
@@ -20,35 +85,84 @@ export function injectExperimentCss(css: string, experimentId: string): void {
     style.className = CSS_CLASS;
     (document.head || document.documentElement).appendChild(style);
   }
+  if (style.textContent !== css) forgetElement(style);
   style.textContent = css;
+  recordArtifact(style, artifactId, ownerKeys, epoch);
 }
 
 export function removeCss(experimentId: string, variationId: string): void {
   const el = document.getElementById("drip-css-" + experimentId + "-" + variationId);
-  if (el) el.remove();
+  if (el) {
+    forgetElement(el);
+    el.remove();
+  }
 }
 
-export function injectExternalCss(url: string, experimentId: string, variationId: string): Promise<void> {
+export function injectExternalCss(
+  url: string,
+  experimentId: string,
+  variationId: string,
+  ownerKeys: readonly string[] = [],
+  artifactId = "css:external:" + experimentId + ":" + variationId,
+  epoch = 0,
+): Promise<void> {
   return new Promise((resolve, reject) => {
     const id = "drip-css-link-" + experimentId + "-" + variationId;
     const previous = document.getElementById(id);
     if (previous && previous.getAttribute("href") === url) {
+      recordArtifact(previous, artifactId, ownerKeys, epoch);
       resolve();
       return;
     }
-    if (previous) previous.remove();
+    if (previous) {
+      forgetElement(previous);
+      previous.remove();
+    }
     const link = document.createElement("link");
     link.id = id;
     link.className = CSS_LINK_CLASS;
     link.rel = "stylesheet";
     link.href = url;
+    recordArtifact(link, artifactId, ownerKeys, epoch);
     link.onload = () => resolve();
     link.onerror = () => reject(new Error("Failed to load CSS artifact: " + url));
     (document.head || document.documentElement).appendChild(link);
   });
 }
 
+export function removeCssForOwner(ownerKey: string, artifactId?: string): void {
+  const removed = new Set<Element>();
+  for (let index = cssJournal.length - 1; index >= 0; index -= 1) {
+    const entry = cssJournal[index];
+    if (artifactId !== undefined && entry.artifactId !== artifactId) continue;
+    if (!entry.owners.delete(ownerKey) || entry.owners.size > 0) continue;
+    removed.add(entry.target);
+    cssJournal.splice(index, 1);
+  }
+  for (const element of removed) {
+    if (!cssJournal.some((entry) => entry.target === element)) element.remove();
+  }
+}
+
+export function addCssOwners(
+  existingOwnerKeys: ReadonlySet<string>,
+  ownerKeys: readonly string[],
+  artifactId?: string,
+): void {
+  if (existingOwnerKeys.size === 0 || ownerKeys.length === 0) return;
+  for (const entry of cssJournal) {
+    if (artifactId !== undefined && entry.artifactId !== artifactId) continue;
+    if (
+      !Array.from(existingOwnerKeys).some((ownerKey) =>
+        entry.owners.has(ownerKey)
+      )
+    ) continue;
+    ownerKeys.forEach((ownerKey) => entry.owners.add(ownerKey));
+  }
+}
+
 export function removeAllCss(): void {
   document.querySelectorAll("." + CSS_CLASS).forEach((el) => el.remove());
   document.querySelectorAll("." + CSS_LINK_CLASS).forEach((el) => el.remove());
+  cssJournal.length = 0;
 }

package/src/cwv.test.ts

@@ -1,95 +1,78 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-describe("CWV self-measurement", () => {
-  afterEach(async () => {
-    const { resetCwvMeasurement } = await import("./cwv");
-    resetCwvMeasurement();
-    vi.useRealTimers();
-    vi.unstubAllGlobals();
-    vi.restoreAllMocks();
+// Coverage for the route-scoped CLS measurement: the total/after-reveal split,
+// the hadRecentInput filter, and route-reset finalization. The full-page
+// vitals (LCP/INP/TTFB + ratings) live in storefront-vitals and its suite.
+describe("CWV route-scoped CLS measurement", () => {
+  let callbacks: PerformanceObserverCallback[];
+
+  beforeEach(() => {
     vi.resetModules();
+    vi.useFakeTimers();
+    callbacks = [];
+    vi.stubGlobal("PerformanceObserver", class {
+      constructor(callback: PerformanceObserverCallback) { callbacks.push(callback); }
+      observe = vi.fn();
+      disconnect = vi.fn();
+      takeRecords = vi.fn(() => []);
+    });
+    vi.stubGlobal("performance", { now: () => 1_000 });
   });
 
-  it("feature-detects unsupported PerformanceObserver without throwing", async () => {
-    vi.stubGlobal("PerformanceObserver", undefined);
-    const { getCwvMetrics, startCwvMeasurement } = await import("./cwv");
-
-    expect(() => startCwvMeasurement()).not.toThrow();
-    expect(getCwvMetrics()).toEqual({ cls_total: 0, cls_after_reveal: 0 });
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
   });
 
-  it("resets without constructing an observer when measurement is disabled", async () => {
-    const observer = vi.fn();
-    vi.stubGlobal("PerformanceObserver", observer);
-    const { getCwvMetrics, startCwvMeasurement, waitForCwvMetrics } = await import("./cwv");
-
-    startCwvMeasurement(true);
+  const emit = (entries: unknown[]) => callbacks.at(-1)?.(
+    { getEntries: () => entries } as PerformanceObserverEntryList,
+    {} as PerformanceObserver,
+  );
 
-    expect(observer).not.toHaveBeenCalled();
-    await expect(waitForCwvMetrics()).resolves.toBeNull();
-    expect(getCwvMetrics()).toEqual({ cls_total: 0, cls_after_reveal: 0 });
-  });
-
-  it("accumulates layout shifts and splits shifts after reveal", async () => {
-    vi.useFakeTimers();
-    let callback: PerformanceObserverCallback | null = null;
-    const disconnect = vi.fn();
-    const observe = vi.fn();
-    vi.stubGlobal("PerformanceObserver", class PerformanceObserver {
-      constructor(cb: PerformanceObserverCallback) { callback = cb; }
-      observe = observe;
-      disconnect = disconnect;
-      takeRecords = vi.fn(() => []);
-    });
-    vi.spyOn(performance, "now").mockReturnValue(100);
-    const { getCwvMetrics, markCwvReveal, startCwvMeasurement, waitForCwvMetrics } = await import("./cwv");
+  it("splits CLS into total and after-reveal and ignores recent-input shifts", async () => {
+    const { markCwvReveal, resetCwvMeasurement, startCwvMeasurement, waitForCwvMetrics } = await import("./cwv");
+    resetCwvMeasurement();
     startCwvMeasurement();
+    emit([
+      { startTime: 500, value: 0.05, hadRecentInput: false },
+      { startTime: 600, value: 1, hadRecentInput: true },
+    ]);
     markCwvReveal();
-    const finalized = waitForCwvMetrics();
-
-    callback?.({
-      getEntries: () => [
-        { startTime: 50, value: 0.1, hadRecentInput: false },
-        { startTime: 150, value: 0.2, hadRecentInput: false },
-        { startTime: 160, value: 0.4, hadRecentInput: true },
-      ],
-    } as unknown as PerformanceObserverEntryList, {} as PerformanceObserver);
-
-    expect(observe).toHaveBeenCalledWith({ type: "layout-shift", buffered: true });
-    expect(getCwvMetrics()).toEqual({ cls_total: 0.3, cls_after_reveal: 0.2 });
+    emit([{ startTime: 1_500, value: 0.02, hadRecentInput: false }]);
+    const completion = waitForCwvMetrics();
     await vi.advanceTimersByTimeAsync(5_000);
-    expect(disconnect).toHaveBeenCalled();
-    await expect(finalized).resolves.toEqual({ cls_total: 0.3, cls_after_reveal: 0.2 });
+    await expect(completion).resolves.toEqual({ cls_total: 0.07, cls_after_reveal: 0.02 });
   });
 
-  it("finalizes the prior route and resets metrics when a new route starts", async () => {
-    vi.useFakeTimers();
-    const callbacks: PerformanceObserverCallback[] = [];
-    const observes: ReturnType<typeof vi.fn>[] = [];
-    vi.stubGlobal("PerformanceObserver", class PerformanceObserver {
-      observe = vi.fn();
-      disconnect = vi.fn();
-      takeRecords = vi.fn(() => []);
-      constructor(callback: PerformanceObserverCallback) {
-        callbacks.push(callback);
-        observes.push(this.observe);
-      }
-    });
-    vi.spyOn(performance, "now").mockReturnValue(100);
-    const { getCwvMetrics, markCwvReveal, startCwvMeasurement, waitForCwvMetrics } = await import("./cwv");
-
+  it("finalizes the prior route when a new measurement starts and never reuses its values", async () => {
+    const { resetCwvMeasurement, startCwvMeasurement, getCwvMetrics, waitForCwvMetrics } = await import("./cwv");
+    resetCwvMeasurement();
     startCwvMeasurement();
-    markCwvReveal();
+    emit([{ startTime: 100, value: 0.2, hadRecentInput: false }]);
     const firstRoute = waitForCwvMetrics();
-    callbacks[0]?.({
-      getEntries: () => [{ startTime: 150, value: 0.25, hadRecentInput: false }],
-    } as unknown as PerformanceObserverEntryList, {} as PerformanceObserver);
-
     startCwvMeasurement();
-
-    await expect(firstRoute).resolves.toEqual({ cls_total: 0.25, cls_after_reveal: 0.25 });
+    await expect(firstRoute).resolves.toEqual({ cls_total: 0.2, cls_after_reveal: 0 });
+    // The fresh route starts from zero — no carry-over of the prior window.
     expect(getCwvMetrics()).toEqual({ cls_total: 0, cls_after_reveal: 0 });
-    expect(observes[0]).toHaveBeenCalledWith({ type: "layout-shift", buffered: true });
-    expect(observes[1]).toHaveBeenCalledWith({ type: "layout-shift", buffered: false });
+    emit([{ startTime: 200, value: 0.1, hadRecentInput: false }]);
+    expect(getCwvMetrics()).toEqual({ cls_total: 0.1, cls_after_reveal: 0 });
+  });
+
+  it("resolves null without constructing observers when measurement is disabled", async () => {
+    const { resetCwvMeasurement, startCwvMeasurement, waitForCwvMetrics } = await import("./cwv");
+    resetCwvMeasurement();
+    startCwvMeasurement(true);
+    expect(callbacks).toHaveLength(0);
+    await expect(waitForCwvMetrics()).resolves.toBeNull();
+  });
+
+  it("bounds an unrevealed route with the fallback timeout", async () => {
+    const { resetCwvMeasurement, startCwvMeasurement, waitForCwvMetrics } = await import("./cwv");
+    resetCwvMeasurement();
+    startCwvMeasurement();
+    emit([{ startTime: 300, value: 0.04, hadRecentInput: false }]);
+    const completion = waitForCwvMetrics();
+    await vi.advanceTimersByTimeAsync(5_000);
+    await expect(completion).resolves.toEqual({ cls_total: 0.04, cls_after_reveal: 0 });
   });
 });