@drip-apex/sdk 0.1.0 → 0.3.0

package/src/early-interaction-capture.ts

@@ -0,0 +1,230 @@
+import { isExperimentServable } from "@drip/event-schema/experiment-servability";
+import { CONSENT_GRANTED, CONSENT_REQUIRED, DNT_BLOCKED, evaluateSynchronousConsentForProvider, readConfiguredConsent } from "./consent-evaluation";
+import { isOptedOut } from "./guards";
+import { getOrCreateSessionId } from "./track";
+import type { Assignment, DataProtectionSettings, Experiment, Goal } from "./types";
+import { safeRegexTest } from "./safe-regex";
+import { buildTargetingAttributes, matchedPageRuleIds } from "./targeting";
+import { weekdayScheduleBlocksDelivery } from "./weekday-schedule";
+
+export const EARLY_INTERACTION_STORAGE_KEY = "drip_early_interactions_v1";
+export const EARLY_INTERACTION_TTL_MS = 15 * 60 * 1000;
+const EARLY_INTERACTION_MAX_ENTRIES = 50;
+const PAIRED_ACTION_WINDOW_MS = 1000;
+type StorageMode = NonNullable<DataProtectionSettings["storageMode"]>;
+type ConsentState = "allowed" | "denied" | "unknown";
+
+export type EarlyInteractionEntry = {
+  goalId: string; experimentId: string; variationId: string; assignmentEpoch: number;
+  kind: "click" | "submit"; data: Record<string, unknown>; timestamp: number;
+  sessionId: string; pageUrl: string; configRevision: number;
+};
+type EarlyCaptureState = { entries: EarlyInteractionEntry[]; stop: () => void; storageMode: StorageMode };
+declare global {
+  var __dripEarlyInteractions: EarlyCaptureState | undefined;
+  var __dripHasConsent: boolean | undefined;
+  var __dripInstallEarlyInteractionCapture: typeof installEarlyInteractionCapture | undefined;
+  var __dripPredecided: { decision?: Array<[string, string]> } | undefined;
+  var __dripEarlyQ: Array<{ kind: "click" | "submit"; target: Element; timestamp: number; id: number; pageUrl: string; consentAllowed: boolean }> | undefined;
+  var __dripEarlyStop: (() => void) | undefined;
+}
+
+export function drainBootstrapEarlyInteractions(input: ConsentConfig & {
+  assignments: Assignment[];
+  experiments: Experiment[];
+  activePageIds?: ReadonlySet<string>;
+  qaMode?: boolean;
+  environment?: string;
+  now?: number;
+  consume: (goalId: string, assignment: Assignment, timestamp: number, kind: "click" | "submit", pageUrl: string) => void;
+}): void {
+  const queued = globalThis.__dripEarlyQ;
+  globalThis.__dripEarlyStop?.();
+  globalThis.__dripEarlyStop = undefined;
+  globalThis.__dripEarlyQ = [];
+  if (!Array.isArray(queued) || queued.length === 0) return;
+  const liveConsentAllowed = !isOptedOut() && consentState(input) === "allowed";
+  const experiments = new Map(input.experiments.map((experiment) => [experiment.id, experiment]));
+  const now = input.now ?? Date.now();
+  const seen = new Set<number>();
+  const lastActions = new Map<string, { kind: "click" | "submit"; timestamp: number; form: Element | null }>();
+  for (const entry of queued) {
+    if (!entry || entry.consentAllowed !== true || !liveConsentAllowed || seen.has(entry.id) || !Number.isFinite(entry.timestamp) || now - entry.timestamp > EARLY_INTERACTION_TTL_MS || entry.timestamp > now || !(entry.target instanceof Element)) continue;
+    seen.add(entry.id);
+    for (const assignment of input.assignments) {
+      const experiment = experiments.get(assignment.experimentId);
+      if (!experiment || !isExperimentServable(experiment, { qaMode: input.qaMode === true, environment: input.environment || "production" })) continue;
+      const clickTimeAttributes = buildTargetingAttributes({}, entry.pageUrl, { persistSignals: false });
+      const clickTimePageIds = matchedPageRuleIds(
+        [...(experiment.targeting?.pageRules ?? []), ...(experiment.goalPageRules ?? [])],
+        { url: entry.pageUrl, attributes: clickTimeAttributes },
+      );
+      for (const goal of experiment.goals ?? []) {
+        if ((goal.type !== "click" && String(goal.type) !== "submit") || !goal.selector) continue;
+        if (!goalIsActiveForBootstrap(goal, clickTimePageIds, entry.pageUrl)) continue;
+        const matched = matchingElement(entry.target, goal, entry.kind);
+        if (matched) {
+          const actionKey = `${assignment.experimentId}:${goal.id}`;
+          const prior = lastActions.get(actionKey);
+          const form = logicalForm(matched);
+          if (prior && prior.kind !== entry.kind && entry.timestamp - prior.timestamp <= PAIRED_ACTION_WINDOW_MS && form && prior.form === form) continue;
+          lastActions.set(actionKey, { kind: entry.kind, timestamp: entry.timestamp, form });
+          input.consume(goal.id, assignment, entry.timestamp, entry.kind, entry.pageUrl);
+        }
+      }
+    }
+  }
+}
+
+function logicalForm(matched: Element): HTMLFormElement | null {
+  return matched.closest("form") ??
+    (matched as HTMLButtonElement | HTMLInputElement).form ?? null;
+}
+
+function goalIsActiveForBootstrap(goal: Goal, activePageIds: ReadonlySet<string>, pageUrl: string): boolean {
+  if (goal.pageId) return activePageIds.has(goal.pageId);
+  return !goal.urlPattern || safeRegexTest(goal.urlPattern, pageUrl);
+}
+
+function readCookie(name: string): string {
+  try { const match = (document.cookie || "").match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`)); return match ? decodeURIComponent(match[1]) : ""; }
+  catch { return ""; }
+}
+function consentState(config: ConsentConfig): ConsentState {
+  const configured = readConfiguredConsent(config.consentProvider, config.consentRequiredGroup, config.consentGetter);
+  const explicit = typeof globalThis.__dripHasConsent === "boolean" ? globalThis.__dripHasConsent : undefined;
+  const cookie = readCookie("drip_consent");
+  const nav = globalThis.navigator as Navigator & { msDoNotTrack?: string } | undefined;
+  const bits = evaluateSynchronousConsentForProvider({
+    requireConsent: config.requireConsent, hasConsent: explicit, consentModeEnabled: config.consentModeEnabled,
+    provider: config.consentProvider, configuredConsentGranted: configured, consentCookieGranted: cookie === "1",
+    respectDoNotTrack: config.respectDoNotTrack,
+    doNotTrackValue: nav?.doNotTrack ?? nav?.msDoNotTrack ?? (globalThis as any).doNotTrack ?? "",
+  });
+  if (bits & DNT_BLOCKED) return "denied";
+  if (!(bits & CONSENT_REQUIRED)) return "allowed";
+  if (bits & CONSENT_GRANTED) return "allowed";
+  if (explicit === false || configured === false || cookie === "0") return "denied";
+  return "unknown";
+}
+function getStorage(mode: StorageMode): Storage | null {
+  try { return mode === "sessionStorage" ? globalThis.sessionStorage ?? null : mode === "localStorage" ? globalThis.localStorage ?? null : null; }
+  catch { return null; }
+}
+function readPersisted(mode: StorageMode): EarlyInteractionEntry[] {
+  try { const raw = mode === "cookie" ? readCookie(EARLY_INTERACTION_STORAGE_KEY) : getStorage(mode)?.getItem(EARLY_INTERACTION_STORAGE_KEY) ?? ""; const parsed = JSON.parse(raw || "[]"); return Array.isArray(parsed) ? parsed : []; }
+  catch { return []; }
+}
+function persist(mode: StorageMode, entries: EarlyInteractionEntry[]): void {
+  const bounded = entries.slice(-EARLY_INTERACTION_MAX_ENTRIES); let value = JSON.stringify(bounded);
+  if (mode === "cookie") while (encodeURIComponent(value).length > 3500 && bounded.length) { bounded.shift(); value = JSON.stringify(bounded); }
+  try { if (mode === "cookie") document.cookie = `${EARLY_INTERACTION_STORAGE_KEY}=${encodeURIComponent(value)}; Path=/; SameSite=Lax; Max-Age=900`; else if (mode !== "memory") getStorage(mode)?.setItem(EARLY_INTERACTION_STORAGE_KEY, value); } catch {}
+}
+export function clearEarlyInteractions(mode?: StorageMode): void {
+  for (const candidate of mode ? [mode] : (["localStorage", "sessionStorage", "cookie", "memory"] as StorageMode[])) {
+    try { if (candidate === "cookie") document.cookie = `${EARLY_INTERACTION_STORAGE_KEY}=; Path=/; SameSite=Lax; Max-Age=0`; else if (candidate !== "memory") getStorage(candidate)?.removeItem(EARLY_INTERACTION_STORAGE_KEY); } catch {}
+  }
+  if (globalThis.__dripEarlyInteractions) globalThis.__dripEarlyInteractions.entries.length = 0;
+}
+function matchingElement(target: Element, goal: Goal, kind: "click" | "submit"): Element | null {
+  if (!goal.selector) return null;
+  try {
+    if (kind === "submit") {
+      const form = target instanceof HTMLFormElement ? target : target.closest("form");
+      if (!form) return null;
+      if (form.matches(goal.selector)) return form;
+      const descendant = form.querySelector(goal.selector);
+      if (descendant) return descendant;
+      // Form-associated controls may live outside the form (`form="id"`).
+      return Array.from(document.querySelectorAll(goal.selector)).find((element) =>
+        (element instanceof HTMLButtonElement || element instanceof HTMLInputElement) && element.form === form
+      ) ?? null;
+    }
+    const match = target.closest(goal.selector); return match && (!goal.textMatch || (match.textContent || "").trim().toLowerCase().includes(goal.textMatch.trim().toLowerCase())) ? match : null;
+  } catch { return null; }
+}
+type ConsentConfig = { requireConsent?: boolean; consentModeEnabled?: boolean; consentProvider?: "custom" | "onetrust" | "usercentrics" | "cookiebot" | "ccm19" | "pandectes" | "cookiescript" | "borlabs"; consentRequiredGroup?: string; consentGetter?: string; respectDoNotTrack?: boolean };
+export type EarlyCaptureConfig = ConsentConfig & { experiments: Experiment[]; assignments: Pick<Assignment, "experimentId" | "variationId" | "assignmentEpoch">[]; attributes?: Record<string, unknown>; configRevision: number; pageUrl: string; storageMode?: StorageMode; forcedExperimentIds?: string[]; now?: number };
+const CONSENT_EVENTS = ["OneTrustGroupsUpdated", "OptanonConsentChanged", "CookiebotOnConsentReady", "CookiebotOnAccept", "CookiebotOnDecline", "CookieConsentDeclaration", "UC_UI_CMP_EVENT", "ccm19EmbeddingAccepted", "ccm19WidgetClosed", "ccm19WidgetLoaded", "PandectesInitialized", "visitorConsentCollected", "CookieScriptLoaded", "CookieScriptAccept", "CookieScriptAcceptAll", "CookieScriptReject", "CookieScriptClose"];
+
+export function installEarlyInteractionCapture(config: EarlyCaptureConfig): void {
+  globalThis.__dripEarlyInteractions?.stop();
+  const mode = config.storageMode ?? "localStorage";
+  if (!Number.isSafeInteger(config.configRevision) || isOptedOut()) { clearEarlyInteractions(); return; }
+  const entries = readPersisted(mode);
+  let armed = false;
+  const sessionId = getOrCreateSessionId();
+  const assignmentMap = new Map(config.assignments.map((a) => [a.experimentId, a]));
+  const forcedExperimentIds = new Set(config.forcedExperimentIds ?? []);
+  const targetingAttributes = buildTargetingAttributes(
+    config.attributes ?? {},
+    config.pageUrl,
+    { persistSignals: false },
+  );
+  const activePageIds = matchedPageRuleIds(
+    config.experiments.flatMap((experiment) => [...(experiment.targeting?.pageRules ?? []), ...(experiment.goalPageRules ?? [])]),
+    { url: config.pageUrl, attributes: targetingAttributes },
+  );
+  const goals = config.experiments.flatMap((experiment) => {
+    if (
+      !forcedExperimentIds.has(experiment.id) &&
+      weekdayScheduleBlocksDelivery(
+        experiment.weekdaySchedule,
+        new Date(config.now ?? Date.now()),
+      )
+    ) return [];
+    const assignment = assignmentMap.get(experiment.id);
+    if (!assignment || !Number.isSafeInteger(assignment.assignmentEpoch) || (assignment.assignmentEpoch ?? 0) < 1) return [];
+    return (experiment.goals ?? []).filter((goal) => {
+      if ((goal.type !== "click" && String(goal.type) !== "submit") || !goal.selector) return false;
+      if (goal.pageId) return activePageIds.has(goal.pageId);
+      return !goal.urlPattern || safeRegexTest(goal.urlPattern, config.pageUrl);
+    }).map((goal) => ({ goal, assignment }));
+  });
+  const lastActions = new Map<string, { at: number; kind: "click" | "submit"; form: Element | null }>();
+  const capture = (event: Event, kind: "click" | "submit") => {
+    if (isOptedOut()) { stop(); clearEarlyInteractions(mode); return; }
+    const consent = consentState(config); if (consent !== "allowed") { if (consent === "denied") clearEarlyInteractions(mode); return; }
+    const target = event.target; if (!(target instanceof Element)) return;
+    for (const { goal, assignment } of goals) {
+      const matched = matchingElement(target, goal, kind); if (!matched) continue;
+      const form = logicalForm(matched); const key = `${goal.id}:${assignment.experimentId}`;
+      const prior = lastActions.get(key);
+      if (prior && prior.kind !== kind && Date.now() - prior.at <= PAIRED_ACTION_WINDOW_MS && form && prior.form === form) continue;
+      lastActions.set(key, { at: Date.now(), kind, form });
+      entries.push({ goalId: goal.id, experimentId: assignment.experimentId, variationId: assignment.variationId, assignmentEpoch: assignment.assignmentEpoch!, kind, data: { early_interaction: true }, timestamp: Date.now(), sessionId, pageUrl: config.pageUrl.slice(0, 2048), configRevision: config.configRevision });
+    }
+    if (entries.length > EARLY_INTERACTION_MAX_ENTRIES) entries.splice(0, entries.length - EARLY_INTERACTION_MAX_ENTRIES); persist(mode, entries);
+  };
+  const click = (event: Event) => capture(event, "click"); const submit = (event: Event) => capture(event, "submit");
+  const arm = () => { if (armed) return; armed = true; document.addEventListener("click", click, true); document.addEventListener("submit", submit, true); };
+  const disarm = () => { if (!armed) return; armed = false; document.removeEventListener("click", click, true); document.removeEventListener("submit", submit, true); };
+  const consentChange = () => { const consent = consentState(config); if (consent === "allowed") arm(); else { disarm(); if (consent === "denied") clearEarlyInteractions(mode); } };
+  const stop = () => { disarm(); CONSENT_EVENTS.forEach((event) => window.removeEventListener(event, consentChange)); };
+  CONSENT_EVENTS.forEach((event) => window.addEventListener(event, consentChange)); consentChange();
+  globalThis.__dripEarlyInteractions = { entries, storageMode: mode, stop };
+}
+
+export function drainEarlyInteractions(input: ConsentConfig & { qaMode?: boolean; environment?: string; configRevision: number | undefined; sessionId: string; storageMode?: StorageMode; experiments: Experiment[]; now?: number; forcedExperimentIds?: string[]; consume: (entry: EarlyInteractionEntry) => void }): void {
+  const mode = input.storageMode ?? globalThis.__dripEarlyInteractions?.storageMode ?? "localStorage";
+  globalThis.__dripEarlyInteractions?.stop();
+  if (isOptedOut() || consentState(input) !== "allowed") { clearEarlyInteractions(mode); return; }
+  const entries = [...readPersisted(mode), ...(globalThis.__dripEarlyInteractions?.entries ?? [])]; clearEarlyInteractions(mode);
+  const now = input.now ?? Date.now(); const seen = new Set<string>();
+  const forcedExperimentIds = new Set(input.forcedExperimentIds ?? []);
+  const experiments = new Map(input.experiments.filter((experiment) =>
+    isExperimentServable(experiment, { qaMode: input.qaMode === true, environment: input.environment || "production" }) &&
+    (
+      forcedExperimentIds.has(experiment.id) ||
+      !weekdayScheduleBlocksDelivery(experiment.weekdaySchedule, new Date(now))
+    )
+  ).map((experiment) => [experiment.id, experiment]));
+  for (const entry of entries) {
+    const identity = JSON.stringify(entry); if (seen.has(identity)) continue; seen.add(identity);
+    if (!entry || typeof entry !== "object" || !Number.isFinite(entry.timestamp) || now - entry.timestamp > EARLY_INTERACTION_TTL_MS || entry.timestamp > now) continue;
+    if (entry.sessionId !== input.sessionId || entry.configRevision !== input.configRevision) continue;
+    const experiment = experiments.get(entry.experimentId);
+    if (!experiment || experiment.assignmentEpoch !== entry.assignmentEpoch || !experiment.variations.some((variation) => variation.id === entry.variationId) || !(experiment.goals ?? []).some((goal) => goal.id === entry.goalId)) continue;
+    try { input.consume(entry); } catch {}
+  }
+}

package/src/early-reassert.test.ts

@@ -0,0 +1,207 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { readFileSync } from "node:fs";
+import {
+  assignmentsHaveCustomJs,
+  assignmentsHaveStructuralMutations,
+  installEarlyReassert,
+  shouldUseEarlyReassert,
+} from "./early-reassert";
+import type { Assignment } from "./types";
+
+const assignment = {
+  experimentId: "exp", variationId: "treatment", mutations: [{ selector: "#hero", type: "text", value: "Treatment" }],
+} as Assignment;
+const runtimeSource = () => readFileSync(
+  process.cwd().endsWith("packages/sdk") ? "src/activation-runtime.ts" : "packages/sdk/src/activation-runtime.ts",
+  "utf8",
+);
+
+describe("early hydration re-assert", () => {
+  const stops: Array<() => void> = [];
+  const install = (input: Parameters<typeof installEarlyReassert>[0]) => {
+    const stop = installEarlyReassert(input);
+    stops.push(stop);
+    return stop;
+  };
+
+  afterEach(async () => {
+    stops.splice(0).forEach((stop) => stop());
+    await Promise.resolve();
+    vi.useRealTimers();
+    document.body.innerHTML = "";
+  });
+
+  it("requires the opt-in, trusted inline predecision, and visual consent", () => {
+    const eligible = { applyTiming: "early_reassert", hasTrustedPredecision: true, consentGranted: true, dntBlocked: false, configSource: "inline" };
+    expect(shouldUseEarlyReassert(eligible)).toBe(true);
+    expect(shouldUseEarlyReassert({ ...eligible, applyTiming: "after_hydration" })).toBe(false);
+    expect(shouldUseEarlyReassert({ ...eligible, hasTrustedPredecision: false })).toBe(false);
+    expect(shouldUseEarlyReassert({ ...eligible, consentGranted: false })).toBe(false);
+    expect(shouldUseEarlyReassert({ ...eligible, configSource: "network" })).toBe(false);
+  });
+
+  it("repairs a hydration revert within one animation frame", async () => {
+    vi.useFakeTimers();
+    document.body.innerHTML = '<h1 id="hero">Treatment</h1>';
+    const diagnostics = {};
+    const reapply = vi.fn(() => { document.querySelector("#hero")!.textContent = "Treatment"; });
+    const stop = install({ resolveAssignments: () => [assignment], diagnostics, reapply });
+    await Promise.resolve();
+    document.querySelector("#hero")!.textContent = "Server";
+    await Promise.resolve();
+    expect(reapply).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(16);
+    expect(reapply).toHaveBeenCalledTimes(1);
+    expect(document.querySelector("#hero")!.textContent).toBe("Treatment");
+    expect(diagnostics).toMatchObject({ reasserts_count: 1 });
+    stop();
+  });
+
+  it("arms from an empty render plane when assignments arrive during hydration", async () => {
+    vi.useFakeTimers();
+    document.body.innerHTML = '<h1 id="hero">Treatment</h1>';
+    let live: Assignment[] = [];
+    const reapply = vi.fn(() => {
+      document.querySelector("#hero")!.textContent = "Treatment";
+    });
+    install({ resolveAssignments: () => live, diagnostics: {}, reapply });
+    await Promise.resolve();
+
+    live = [assignment];
+    document.querySelector("#hero")!.textContent = "Framework";
+    await Promise.resolve();
+    vi.advanceTimersByTime(16);
+
+    expect(reapply).toHaveBeenCalledWith([assignment]);
+    expect(document.querySelector("#hero")!.textContent).toBe("Treatment");
+  });
+
+  it("trips the cap instead of re-applying forever", async () => {
+    vi.useFakeTimers();
+    document.body.innerHTML = '<h1 id="hero">Treatment</h1>';
+    const diagnostics: { reasserts_count?: number; revert_loops_detected?: number } = {};
+    const reapply = vi.fn();
+    install({ resolveAssignments: () => [assignment], diagnostics, reapply, cap: 2 });
+    await Promise.resolve();
+    for (let index = 0; index < 3; index += 1) {
+      document.querySelector("#hero")!.setAttribute("data-render", String(index));
+      await Promise.resolve();
+      vi.advanceTimersByTime(40);
+    }
+    expect(reapply).toHaveBeenCalledTimes(2);
+    expect(diagnostics.revert_loops_detected).toBe(1);
+  });
+
+  it("ignores unrelated DOM churn", async () => {
+    vi.useFakeTimers();
+    document.body.innerHTML = '<h1 id="hero">Treatment</h1><p id="other">x</p>';
+    const reapply = vi.fn();
+    install({ resolveAssignments: () => [assignment], diagnostics: {}, reapply });
+    await Promise.resolve();
+    document.querySelector("#other")!.textContent = "y";
+    await Promise.resolve();
+    vi.advanceTimersByTime(20);
+    expect(reapply).not.toHaveBeenCalled();
+  });
+
+  it("does not spend the cap on ancestor churn before repairing a real revert", async () => {
+    vi.useFakeTimers();
+    document.body.innerHTML = '<main id="wrapper"><h1 id="hero">Treatment</h1></main>';
+    const reapply = vi.fn(() => { document.querySelector("#hero")!.textContent = "Treatment"; });
+    install({ resolveAssignments: () => [assignment], diagnostics: {}, reapply, cap: 1 });
+    await Promise.resolve();
+    document.querySelector("#wrapper")!.className = "hydrated";
+    document.querySelector("#wrapper")!.append(document.createElement("span"));
+    await Promise.resolve();
+    vi.advanceTimersByTime(40);
+    expect(reapply).not.toHaveBeenCalled();
+    document.querySelector("#hero")!.textContent = "Server";
+    await Promise.resolve();
+    vi.advanceTimersByTime(40);
+    expect(reapply).toHaveBeenCalledTimes(1);
+    expect(document.querySelector("#hero")!.textContent).toBe("Treatment");
+  });
+
+  it("fails closed for withheld offers while reasserting authorized assignments", async () => {
+    vi.useFakeTimers();
+    document.body.innerHTML = '<h1 id="hero">Treatment</h1><p id="offer">Offer</p>';
+    const reapply = vi.fn();
+    install({
+      resolveAssignments: () => [assignment], diagnostics: {}, reapply,
+    });
+    await Promise.resolve();
+    document.querySelector("#offer")!.textContent = "Control";
+    await Promise.resolve();
+    vi.advanceTimersByTime(20);
+    expect(reapply).not.toHaveBeenCalled();
+    document.querySelector("#hero")!.textContent = "Server";
+    await Promise.resolve();
+    vi.advanceTimersByTime(20);
+    expect(reapply).toHaveBeenCalledOnce();
+  });
+
+  // F3
+  it("stops instead of repairing once the live artifact set is empty", async () => {
+    vi.useFakeTimers();
+    document.body.innerHTML = '<h1 id="hero">Treatment</h1>';
+    const reapply = vi.fn();
+    let live: Assignment[] = [assignment];
+    install({ resolveAssignments: () => live, diagnostics: {}, reapply });
+    await Promise.resolve();
+    live = [];
+    document.querySelector("#hero")!.textContent = "Server";
+    await Promise.resolve();
+    vi.advanceTimersByTime(40);
+    expect(reapply).not.toHaveBeenCalled();
+
+    // The watcher is dead by construction: a later live entry does not revive it.
+    live = [assignment];
+    document.querySelector("#hero")!.textContent = "Server again";
+    await Promise.resolve();
+    vi.advanceTimersByTime(40);
+    expect(reapply).not.toHaveBeenCalled();
+  });
+
+  it("repairs with the live assignment set, not the install-time one", async () => {
+    vi.useFakeTimers();
+    document.body.innerHTML = '<h1 id="hero">Treatment</h1>';
+    const reapply = vi.fn();
+    const current = { ...assignment } as Assignment;
+    install({ resolveAssignments: () => [current], diagnostics: {}, reapply });
+    await Promise.resolve();
+    document.querySelector("#hero")!.textContent = "Server";
+    await Promise.resolve();
+    vi.advanceTimersByTime(20);
+    expect(reapply).toHaveBeenCalledWith([current]);
+  });
+
+  it("defers structural assignments instead of counting unrepaired reverts", () => {
+    const structural = { ...assignment, mutations: [{ selector: "#hero", action: "insertAfter", html: "<p>Treatment</p>" }] } as Assignment;
+    expect(assignmentsHaveStructuralMutations([structural])).toBe(true);
+    expect(assignmentsHaveStructuralMutations([assignment])).toBe(false);
+  });
+
+  it.each([
+    ["variation JS", { js: "document.title='variation'" }, true],
+    ["experiment JS", { experimentJs: "document.title='experiment'" }, true],
+    ["external JS URL", { externalJsUrl: "https://cdn.example.test/treatment.js" }, true],
+    ["reset JS", { resetJs: "document.title='reset'", experimentResetJs: "document.title='experiment reset'" }, false],
+    ["CSS", { css: "#hero { color: red; }", experimentCss: "#hero { display: block; }" }, false],
+    ["empty variation JS", { js: "   " }, false],
+  ])("detects %s when deciding whether early reassert is safe", (_label, fields, expected) => {
+    expect(assignmentsHaveCustomJs([{ ...assignment, ...fields } as Assignment])).toBe(expected);
+  });
+
+  it("generation-scopes teardown so a late first init cannot stop the second observer", () => {
+    const runtime = runtimeSource();
+    expect(runtime).toMatch(/clearTimeout\(runtimeSharedState\.earlyReassertTeardownTimer\)/);
+    expect(runtime).toMatch(/if \(runtimeSharedState\.stopEarlyReassert !== stop\) return;/);
+  });
+
+  it("diagnoses rejected hydration waits and still enters teardown scheduling", () => {
+    const runtime = runtimeSource();
+    expect(runtime).toMatch(/\.catch\(\(\) => debugWarn\("hydration", "wait failed"\)\)\s*\.finally/);
+  });
+
+});

package/src/early-reassert.ts

@@ -0,0 +1,152 @@
+import type { Assignment } from "./types";
+
+export type EarlyReassertDiagnostics = {
+  early_apply_at?: number;
+  reasserts_count?: number;
+  revert_loops_detected?: number;
+};
+
+export function assignmentsHaveStructuralMutations(assignments: Assignment[]): boolean {
+  return assignments.some((assignment) => assignment.mutations.some((mutation) =>
+    mutation.action === "remove" || mutation.action?.startsWith("insert")));
+}
+
+export function assignmentsHaveCustomJs(assignments: Assignment[]): boolean {
+  return assignments.some((assignment) =>
+    Boolean(
+      assignment.js?.trim()
+      || assignment.experimentJs?.trim()
+      || assignment.externalJsUrl,
+    ));
+}
+
+const DEFAULT_CAP = 24;
+const LOOP_FRAME_LIMIT = 6;
+
+export function shouldUseEarlyReassert(input: {
+  applyTiming?: string;
+  hasTrustedPredecision: boolean;
+  consentGranted: boolean;
+  dntBlocked: boolean;
+  configSource: string;
+}): boolean {
+  return input.applyTiming === "early_reassert"
+    && input.configSource === "inline"
+    && input.hasTrustedPredecision
+    && input.consentGranted
+    && !input.dntBlocked;
+}
+
+/**
+ * Watches only treatment selectors and batches hydration repairs into the next
+ * animation frame. The observer is deliberately SDK-side: the inline decision
+ * bootstrap remains a small, synchronous decision-only artifact.
+ *
+ * The watcher never captures an assignment array. It resolves the live applied
+ * set through `resolveAssignments` at fire time, so a page teardown that drops
+ * the artifacts stops it by construction rather than through a
+ * `stopEarlyReassert()` call nobody makes.
+ */
+export function installEarlyReassert(input: {
+  resolveAssignments: () => Assignment[];
+  reapply: (assignments: Assignment[]) => void;
+  diagnostics: EarlyReassertDiagnostics;
+  timeoutMs?: number;
+  cap?: number;
+}): () => void {
+  if (typeof document === "undefined" || typeof MutationObserver === "undefined") return () => {};
+  const resolveWatchSet = (): { assignments: Assignment[]; selectors: string[] } => {
+    const assignments = input.resolveAssignments();
+    return {
+      assignments,
+      selectors: assignments.flatMap((assignment) =>
+        assignment.mutations.map((mutation) => mutation.selector)),
+    };
+  };
+  let hasObservedWatchSet = resolveWatchSet().selectors.length > 0;
+
+  const cap = Math.max(1, input.cap ?? DEFAULT_CAP);
+  let stopped = false;
+  let armed = false;
+  let frame: number | ReturnType<typeof setTimeout> | null = null;
+  let consecutiveFrames = 0;
+  let lastFrameAt = 0;
+  const matchesTreatment = (node: Node, selectors: string[]): boolean => {
+    const element = node instanceof Element ? node : node.parentElement;
+    if (!element) return false;
+    return selectors.some((selector) => {
+      try { return element.matches(selector) || Boolean(element.closest(selector)); }
+      catch { return false; }
+    });
+  };
+  const cancelFrame = () => {
+    if (frame === null) return;
+    if (typeof cancelAnimationFrame === "function") cancelAnimationFrame(frame as number);
+    else clearTimeout(frame as ReturnType<typeof setTimeout>);
+    frame = null;
+  };
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    observer.disconnect();
+    cancelFrame();
+    clearTimeout(timeout);
+  };
+  const run = (timestamp: number) => {
+    frame = null;
+    if (stopped) return;
+    // A selector this watcher armed for can still churn after its page was torn
+    // down. Resolve first: with no live artifact left there is nothing to
+    // repair, and re-applying would leave an unrevertable treatment behind.
+    const live = resolveWatchSet();
+    if (!live.selectors.length) {
+      if (hasObservedWatchSet) stop();
+      return;
+    }
+    hasObservedWatchSet = true;
+    const count = input.diagnostics.reasserts_count ?? 0;
+    if (count >= cap) {
+      input.diagnostics.revert_loops_detected = (input.diagnostics.revert_loops_detected ?? 0) + 1;
+      stop();
+      return;
+    }
+    consecutiveFrames = timestamp - lastFrameAt < 34 ? consecutiveFrames + 1 : 1;
+    lastFrameAt = timestamp;
+    if (consecutiveFrames > LOOP_FRAME_LIMIT) {
+      input.diagnostics.revert_loops_detected = (input.diagnostics.revert_loops_detected ?? 0) + 1;
+      stop();
+      return;
+    }
+    input.diagnostics.reasserts_count = count + 1;
+    input.reapply(live.assignments);
+    // The repair itself mutates the same nodes. Drop those synchronous records
+    // so only a later framework revert schedules another frame.
+    observer.takeRecords();
+  };
+  const schedule = () => {
+    if (stopped || frame !== null) return;
+    if (typeof requestAnimationFrame === "function") frame = requestAnimationFrame(run);
+    else frame = setTimeout(() => run(Date.now()), 16);
+  };
+  const observer = new MutationObserver((records) => {
+    if (!armed) return;
+    const live = resolveWatchSet();
+    if (!live.selectors.length) {
+      if (hasObservedWatchSet) stop();
+      return;
+    }
+    hasObservedWatchSet = true;
+    if (records.some((record) => matchesTreatment(record.target, live.selectors) || Array.from(record.addedNodes).some((node) => {
+      if (matchesTreatment(node, live.selectors)) return true;
+      if (!(node instanceof Element)) return false;
+      return live.selectors.some((selector) => {
+        try { return Boolean(node.querySelector(selector)); }
+        catch { return false; }
+      });
+    }))) schedule();
+  });
+  observer.observe(document.documentElement, { subtree: true, childList: true, attributes: true, characterData: true });
+  queueMicrotask(() => { observer.takeRecords(); armed = true; });
+  const timeout = setTimeout(stop, Math.max(250, input.timeoutMs ?? 8_000));
+  return stop;
+}