@drip-apex/sdk 0.1.0 → 0.3.0

package/src/antiflicker.test.ts

@@ -1,7 +1,15 @@
 // @vitest-environment jsdom
 
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { applyAntiFlicker, removeAntiFlicker, resolveAntiFlickerCss } from "./antiflicker";
+import {
+  applyAntiFlicker,
+  bootedTooLateForAntiFlicker,
+  removeAntiFlicker,
+  resolveAntiFlickerCss,
+} from "./antiflicker";
+
+const style = (ownerDocument: Document = document): HTMLStyleElement | null =>
+  ownerDocument.getElementById("drip-antiflicker") as HTMLStyleElement | null;
 
 afterEach(() => {
   vi.unstubAllGlobals();
@@ -15,81 +23,252 @@ afterEach(() => {
 });
 
 describe("anti-flicker css resolution", () => {
+  const stubNavigationTiming = (
+    now: number,
+    navigation?: Pick<PerformanceNavigationTiming, "startTime" | "domContentLoadedEventEnd">,
+    paintEntries: Pick<PerformanceEntry, "name" | "startTime">[] = [],
+  ) => {
+    vi.stubGlobal("performance", {
+      now: () => now,
+      getEntriesByType: (type: string) => {
+        if (type === "paint") return paintEntries;
+        return type === "navigation" && navigation ? [navigation] : [];
+      },
+    });
+  };
+
+  it("skips runtime hiding after a recorded paint even inside the timing thresholds", () => {
+    vi.useFakeTimers();
+    stubNavigationTiming(
+      300,
+      { startTime: 0, domContentLoadedEventEnd: 150 },
+      [{ name: "first-paint", startTime: 100 }],
+    );
+
+    expect(applyAntiFlicker(
+      "full", 100, undefined, undefined, bootedTooLateForAntiFlicker(),
+    )).toBe(false);
+    expect(style()).toBeNull();
+  });
+
+  it("skips runtime hiding when the SDK boots after the first-paint window", () => {
+    vi.useFakeTimers();
+    stubNavigationTiming(500, { startTime: 0, domContentLoadedEventEnd: 100 });
+
+    expect(applyAntiFlicker(
+      "full", 100, undefined, undefined, bootedTooLateForAntiFlicker(),
+    )).toBe(false);
+    expect(style()).toBeNull();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("skips runtime hiding more than two seconds after navigation starts", () => {
+    vi.useFakeTimers();
+    stubNavigationTiming(2_001, { startTime: 0, domContentLoadedEventEnd: 0 });
+
+    expect(applyAntiFlicker(
+      "full", 100, undefined, undefined, bootedTooLateForAntiFlicker(),
+    )).toBe(false);
+    expect(style()).toBeNull();
+  });
+
+  it("keeps runtime hiding unchanged during an early boot", () => {
+    vi.useFakeTimers();
+    stubNavigationTiming(200, { startTime: 0, domContentLoadedEventEnd: 0 });
+
+    expect(applyAntiFlicker(
+      "full", 100, undefined, undefined, bootedTooLateForAntiFlicker(),
+    )).toBe(true);
+    expect(style()?.textContent).toContain("opacity: 0");
+    vi.advanceTimersByTime(100);
+    expect(style()?.textContent).not.toMatch(/\bopacity\s*:/);
+  });
+
+  it("falls back to navigation thresholds without Paint Timing API support", () => {
+    vi.useFakeTimers();
+    vi.stubGlobal("performance", {
+      now: () => 200,
+      getEntriesByType: undefined,
+      timing: {
+        navigationStart: Date.now() - 200,
+        domContentLoadedEventEnd: 0,
+      },
+    });
+
+    expect(applyAntiFlicker(
+      "full", 100, undefined, undefined, bootedTooLateForAntiFlicker(),
+    )).toBe(true);
+    expect(style()?.textContent).toContain("opacity: 0");
+  });
+
+  it("defaults safely to current hiding behavior without navigation timing entries", () => {
+    vi.useFakeTimers();
+    stubNavigationTiming(5_000);
+
+    expect(applyAntiFlicker(
+      "full", 100, undefined, undefined, bootedTooLateForAntiFlicker(),
+    )).toBe(true);
+    expect(style()?.textContent).toContain("opacity: 0");
+  });
+
+  it("leaves the edge pre-paint path unaffected when the runtime guard is not requested", () => {
+    vi.useFakeTimers();
+    stubNavigationTiming(5_000, { startTime: 0, domContentLoadedEventEnd: 100 });
+
+    expect(applyAntiFlicker("full", 100)).toBe(true);
+    expect(style()?.textContent).toContain("opacity: 0");
+  });
+
   it("does not fall back to full-page hiding for scoped mode without selectors", () => {
     expect(resolveAntiFlickerCss("scoped")).toBeNull();
     expect(resolveAntiFlickerCss("scoped", [])).toBeNull();
   });
 
-  it("builds scoped css when selectors are available", () => {
+  it("builds class-free scoped css when selectors are available", () => {
     const css = resolveAntiFlickerCss("scoped", [".hero h1", ".cta"]);
-    expect(css).toContain(".hero h1,.cta");
-    expect(css).toContain("visibility: hidden");
+    expect(css).toBe(".hero h1,.cta { visibility: hidden !important; }");
+    expect(css).not.toContain("drip-af");
   });
 
-  it("preserves explicit full-page hiding", () => {
-    const css = resolveAntiFlickerCss("full");
-    expect(css).toContain("html.drip-af");
-    expect(css).toContain("opacity: 0");
+  it("preserves explicit full-page hiding without a root class", () => {
+    expect(resolveAntiFlickerCss("full")).toBe("html { opacity: 0 !important; }");
   });
 
-  it("binds reveal timers to their owner document after the global DOM tears down", () => {
+  it("uses the style element as the only DOM footprint throughout the lifecycle", () => {
+    vi.useFakeTimers();
+    const root = document.documentElement;
+    root.setAttribute("lang", "en");
+    root.setAttribute("data-framework", "remix");
+    const initialAttributes = Array.from(root.attributes, ({ name, value }) => [name, value]);
+    const initialClassName = root.className;
+
+    applyAntiFlicker("scoped", 100, [".hero", ".cta"]);
+    expect(style()?.textContent).toBe(".hero,.cta { visibility: hidden !important; }");
+    expect(root.className).toBe(initialClassName);
+    expect(Array.from(root.attributes, ({ name, value }) => [name, value])).toEqual(initialAttributes);
+
+    vi.advanceTimersByTime(80);
+    expect(style()?.textContent).toBe(
+      ".hero,.cta { visibility: visible !important; transition: visibility 0s, opacity 0.05s ease-in !important; }",
+    );
+    expect(root.className).toBe(initialClassName);
+    expect(Array.from(root.attributes, ({ name, value }) => [name, value])).toEqual(initialAttributes);
+
+    vi.advanceTimersByTime(100);
+    expect(style()).toBeNull();
+    expect(root.className).toBe(initialClassName);
+    expect(Array.from(root.attributes, ({ name, value }) => [name, value])).toEqual(initialAttributes);
+
+    root.removeAttribute("lang");
+    root.removeAttribute("data-framework");
+  });
+
+  it("keeps full mode hidden at progressive reveal and releases it at hard timeout", () => {
     vi.useFakeTimers();
     applyAntiFlicker("full", 100);
+    expect(style()?.textContent).toBe("html { opacity: 0 !important; }");
 
-    const ownerDocument = document;
-    expect(ownerDocument.documentElement.classList.contains("drip-af")).toBe(true);
-    expect(ownerDocument.getElementById("drip-antiflicker")).not.toBeNull();
+    vi.advanceTimersByTime(80);
+    expect(style()?.textContent).toBe(
+      "html { opacity: 0 !important; transition: opacity 0.05s ease-in !important; }",
+    );
+
+    vi.advanceTimersByTime(19);
+    expect(style()?.textContent).toContain("opacity: 0 !important");
+
+    vi.advanceTimersByTime(1);
+    expect(style()?.textContent).toBe(
+      "html { transition: opacity 0.05s ease-in !important; }",
+    );
+    expect(style()?.textContent).not.toMatch(/\bopacity\s*:/);
+  });
+
+  it("restores natural full-page opacity when removed before hard timeout", () => {
+    vi.useFakeTimers();
+    applyAntiFlicker("full", 1_000);
+
+    removeAntiFlicker();
+
+    expect(style()?.textContent).toBe(
+      "html { transition: opacity 0.05s ease-in !important; }",
+    );
+    expect(style()?.textContent).not.toMatch(/\bopacity\s*:/);
+  });
+
+  it("preserves custom CSS until progressive reveal, then releases it", () => {
+    vi.useFakeTimers();
+    applyAntiFlicker("custom", 100, undefined, "body { filter: blur(2px); }");
+    expect(style()?.textContent).toBe("body { filter: blur(2px); }");
+    vi.advanceTimersByTime(80);
+    expect(style()?.textContent).toBe("");
+    vi.advanceTimersByTime(100);
+    expect(style()).toBeNull();
+  });
+
+  it("removes legacy root classes defensively on arm and cleanup", () => {
+    vi.useFakeTimers();
+    document.documentElement.className = "shop drip-af drip-af-reveal";
+    applyAntiFlicker("full", 100);
+    expect(document.documentElement.className).toBe("shop");
+    document.documentElement.classList.add("drip-af", "drip-af-reveal");
+    removeAntiFlicker();
+    expect(document.documentElement.className).toBe("shop");
+  });
 
+  it("binds reveal timers to their owner document after the global DOM tears down", () => {
+    vi.useFakeTimers();
+    applyAntiFlicker("full", 100);
+    const ownerDocument = document;
     vi.stubGlobal("document", undefined);
     expect(() => vi.advanceTimersByTime(180)).not.toThrow();
-
-    expect(ownerDocument.documentElement.classList.contains("drip-af")).toBe(false);
-    expect(ownerDocument.documentElement.classList.contains("drip-af-reveal")).toBe(false);
-    expect(ownerDocument.getElementById("drip-antiflicker")).toBeNull();
+    expect(style(ownerDocument)).toBeNull();
   });
 
   it("clears old timers and supports a fresh anti-flicker cycle after cleanup", () => {
     vi.useFakeTimers();
     applyAntiFlicker("full", 1_000);
-
     removeAntiFlicker();
     vi.advanceTimersByTime(80);
-    expect(document.getElementById("drip-antiflicker")).toBeNull();
-    expect(document.documentElement.classList.contains("drip-af-reveal")).toBe(false);
+    expect(style()).toBeNull();
 
     applyAntiFlicker("full", 200);
     vi.advanceTimersByTime(160);
-    expect(document.documentElement.classList.contains("drip-af-reveal")).toBe(true);
+    expect(style()?.textContent).toContain("opacity: 0");
     vi.advanceTimersByTime(120);
-
-    expect(document.getElementById("drip-antiflicker")).toBeNull();
-    expect(document.documentElement.classList.contains("drip-af")).toBe(false);
-    expect(document.documentElement.classList.contains("drip-af-reveal")).toBe(false);
+    expect(style()).toBeNull();
   });
 
   it("re-arms immediately when re-init starts during reveal cleanup", () => {
     vi.useFakeTimers();
     applyAntiFlicker("full", 1_000);
-    const originalStyle = document.getElementById("drip-antiflicker");
+    const originalStyle = style();
 
     removeAntiFlicker();
-    expect(document.documentElement.classList.contains("drip-af-reveal")).toBe(true);
+    expect(originalStyle?.textContent).not.toMatch(/\bopacity\s*:/);
     applyAntiFlicker("full", 200);
 
-    expect(document.getElementById("drip-antiflicker")).toBe(originalStyle);
-    expect(document.documentElement.classList.contains("drip-af")).toBe(true);
-    expect(document.documentElement.classList.contains("drip-af-reveal")).toBe(false);
-
+    expect(style()).toBe(originalStyle);
+    expect(style()?.textContent).toContain("opacity: 0");
     vi.advanceTimersByTime(160);
-    expect(document.documentElement.classList.contains("drip-af-reveal")).toBe(true);
+    expect(style()?.textContent).toContain("opacity: 0");
     vi.advanceTimersByTime(120);
-    expect(document.getElementById("drip-antiflicker")).toBeNull();
+    expect(style()).toBeNull();
+  });
+
+  it("keeps an existing armed barrier and its timers", () => {
+    vi.useFakeTimers();
+    applyAntiFlicker("full", 100);
+    const originalStyle = style();
+    applyAntiFlicker("scoped", 1_000, [".hero"]);
+    expect(style()).toBe(originalStyle);
+    expect(style()?.textContent).toContain("opacity: 0");
+    vi.advanceTimersByTime(80);
+    expect(style()?.textContent).toContain("opacity: 0");
   });
 
   it("is safe when invoked without a DOM", () => {
     vi.useFakeTimers();
     vi.stubGlobal("document", undefined);
-
     expect(() => applyAntiFlicker("full", 100)).not.toThrow();
     expect(() => removeAntiFlicker()).not.toThrow();
     expect(vi.getTimerCount()).toBe(0);
@@ -100,13 +279,9 @@ describe("anti-flicker css resolution", () => {
     applyAntiFlicker("full", 1_000);
     const ownerDocument = document;
     vi.stubGlobal("document", undefined);
-
     expect(() => removeAntiFlicker()).not.toThrow();
     vi.advanceTimersByTime(80);
-
-    expect(ownerDocument.getElementById("drip-antiflicker")).toBeNull();
-    expect(ownerDocument.documentElement.classList.contains("drip-af")).toBe(false);
-    expect(ownerDocument.documentElement.classList.contains("drip-af-reveal")).toBe(false);
+    expect(style(ownerDocument)).toBeNull();
   });
 
   it("cleans its owner when the ambient document changes", () => {
@@ -116,12 +291,9 @@ describe("anti-flicker css resolution", () => {
     const replacementDocument = document.implementation.createHTMLDocument("replacement");
     vi.stubGlobal("document", replacementDocument);
 
-    removeAntiFlicker();
-    vi.advanceTimersByTime(80);
-
-    expect(ownerDocument.getElementById("drip-antiflicker")).toBeNull();
-    expect(ownerDocument.documentElement.classList.contains("drip-af")).toBe(false);
-    expect(ownerDocument.documentElement.classList.contains("drip-af-reveal")).toBe(false);
+    applyAntiFlicker("full", 100);
+    expect(style(ownerDocument)).toBeNull();
+    expect(style(replacementDocument)?.textContent).toContain("opacity: 0");
     expect(replacementDocument.documentElement.className).toBe("");
   });
 });

package/src/antiflicker.ts

@@ -4,15 +4,22 @@ const STYLE_ID = "drip-antiflicker";
 const DEFAULT_TIMEOUT_MS = 1200;
 const PROGRESSIVE_REVEAL_RATIO = 0.8; // Start progressive reveal at 80% of timeout
 const REVEAL_CLEANUP_MS = 80;
+const MAX_NAVIGATION_AGE_MS = 2_000;
+const MAX_POST_DOM_CONTENT_LOADED_MS = 250;
+const PAINT_TIMING_EPSILON_MS = 50;
 
-const FULL_PAGE_CSS =
-  "html.drip-af { opacity: 0 !important; }" +
-  " html.drip-af-reveal { transition: opacity 0.05s ease-in !important; }";
+const FULL_PAGE_CSS = "html { opacity: 0 !important; }";
+const FULL_PAGE_PROGRESSIVE_CSS =
+  "html { opacity: 0 !important; transition: opacity 0.05s ease-in !important; }";
+const FULL_PAGE_REVEAL_CSS =
+  "html { transition: opacity 0.05s ease-in !important; }";
 
 let progressiveRevealTimer: ReturnType<typeof setTimeout> | null = null;
 let hardRevealTimer: ReturnType<typeof setTimeout> | null = null;
 let cleanupTimer: ReturnType<typeof setTimeout> | null = null;
 let antiFlickerOwnerDocument: Document | null = null;
+let antiFlickerProgressiveCss = "";
+let antiFlickerRevealCss = "";
 
 function activeDocument(): Document | null {
   if (typeof document === "undefined" || !document.documentElement) return null;
@@ -37,7 +44,11 @@ function clearTimers(): void {
 function cleanupDocumentImmediately(ownerDocument: Document): void {
   ownerDocument.documentElement?.classList.remove("drip-af", "drip-af-reveal");
   ownerDocument.getElementById(STYLE_ID)?.remove();
-  if (antiFlickerOwnerDocument === ownerDocument) antiFlickerOwnerDocument = null;
+  if (antiFlickerOwnerDocument === ownerDocument) {
+    antiFlickerOwnerDocument = null;
+    antiFlickerProgressiveCss = "";
+    antiFlickerRevealCss = "";
+  }
 }
 
 export function resolveAntiFlickerCss(
@@ -57,13 +68,37 @@ export function resolveAntiFlickerCss(
     }
 
     const selectorList = scopedSelectors.join(",");
+    return selectorList + " { visibility: hidden !important; }";
+  }
+
+  return FULL_PAGE_CSS;
+}
+
+function resolveAntiFlickerProgressiveCss(
+  mode: AntiFlickerMode,
+  scopedSelectors?: string[],
+): string {
+  if (mode === "scoped" && scopedSelectors?.length) {
     return (
-      selectorList + " { visibility: hidden !important; }" +
-      " .drip-af-reveal " + selectorList + " { visibility: visible !important; transition: visibility 0s, opacity 0.05s ease-in !important; }"
+      scopedSelectors.join(",") +
+      " { visibility: visible !important; transition: visibility 0s, opacity 0.05s ease-in !important; }"
     );
   }
 
-  return FULL_PAGE_CSS;
+  if (mode === "full") return FULL_PAGE_PROGRESSIVE_CSS;
+  return "";
+}
+
+function resolveAntiFlickerRevealCss(
+  mode: AntiFlickerMode,
+  scopedSelectors?: string[],
+): string {
+  if (mode === "scoped") {
+    return resolveAntiFlickerProgressiveCss(mode, scopedSelectors);
+  }
+
+  if (mode === "full") return FULL_PAGE_REVEAL_CSS;
+  return "";
 }
 
 /**
@@ -73,50 +108,49 @@ export function resolveAntiFlickerCss(
  * - "off": no-op.
  * Scoped mode is a no-op when no selectors are available.
  *
- * Progressive reveal: at 80% of timeout, begins a CSS transition to fade
- * content in gradually rather than a sudden flash at timeout expiry.
+ * Progressive reveal: at 80% of timeout, scoped mode reveals its selectors.
+ * Full mode stays hidden and only pre-arms its opacity transition.
  */
 export function applyAntiFlicker(
   mode: AntiFlickerMode = "scoped",
   timeoutMs: number = DEFAULT_TIMEOUT_MS,
   scopedSelectors?: string[],
   customCss?: string,
-): void {
+  bootedTooLate = false,
+): boolean {
+  if (bootedTooLate) return false;
   const ownerDocument = activeDocument();
-  if (!ownerDocument) return;
+  if (!ownerDocument) return false;
+  const root = ownerDocument.documentElement;
+  // Remove state left by older SDK embeds without ever adding root classes.
+  root.classList.remove("drip-af", "drip-af-reveal");
   const existingStyle = ownerDocument.getElementById(STYLE_ID);
   // A live barrier owns its current timers. During the short reveal cleanup
   // window, however, network config or re-init may need to arm a fresh barrier
   // immediately against the same document.
-  if (existingStyle && cleanupTimer === null) return;
+  if (existingStyle && cleanupTimer === null) return true;
   const css = resolveAntiFlickerCss(mode, scopedSelectors, customCss);
-  if (!css) return;
+  if (!css) return false;
   clearTimers();
   if (antiFlickerOwnerDocument && antiFlickerOwnerDocument !== ownerDocument) {
     cleanupDocumentImmediately(antiFlickerOwnerDocument);
   }
   antiFlickerOwnerDocument = ownerDocument;
+  antiFlickerProgressiveCss = resolveAntiFlickerProgressiveCss(mode, scopedSelectors);
+  antiFlickerRevealCss = resolveAntiFlickerRevealCss(mode, scopedSelectors);
 
-  const root = ownerDocument.documentElement;
   const style = existingStyle ?? ownerDocument.createElement("style");
   style.id = STYLE_ID;
 
   style.textContent = css;
-  root.classList.remove("drip-af-reveal");
-  if (mode === "full") {
-    root.classList.add("drip-af");
-  } else {
-    root.classList.remove("drip-af");
-  }
 
   if (!style.isConnected) (ownerDocument.head || root).appendChild(style);
 
-  // Progressive reveal: at 80% of timeout, begin transition before hard timeout
+  // At 80%, scoped mode reveals while full mode only pre-arms its transition.
   const progressiveMs = Math.round(timeoutMs * PROGRESSIVE_REVEAL_RATIO);
   progressiveRevealTimer = setTimeout(() => {
     progressiveRevealTimer = null;
-    // Add reveal class to start transition (content fades in over 50ms)
-    root.classList.add("drip-af-reveal");
+    style.textContent = antiFlickerProgressiveCss;
   }, progressiveMs);
 
   // Hard timeout: fully remove anti-flicker
@@ -124,21 +158,62 @@ export function applyAntiFlicker(
     hardRevealTimer = null;
     removeAntiFlickerFrom(ownerDocument);
   }, timeoutMs);
+  return true;
+}
+
+/**
+ * Runtime-loaded SDKs must not introduce a hiding barrier after the browser
+ * has likely painted. Inline edge bootstrap callers deliberately do not opt
+ * into this guard because their barrier is installed synchronously pre-paint.
+ */
+export function bootedTooLateForAntiFlicker(): boolean {
+  if (typeof performance === "undefined") return false;
+
+  try {
+    const now = performance.now();
+    const paintEntries = performance.getEntriesByType?.("paint") ?? [];
+    if (paintEntries.some((entry) =>
+      (entry.name === "first-paint" || entry.name === "first-contentful-paint")
+      && entry.startTime <= now - PAINT_TIMING_EPSILON_MS
+    )) return true;
+
+    const navigation = performance.getEntriesByType?.("navigation")?.[0] as
+      | PerformanceNavigationTiming
+      | undefined;
+    if (navigation) {
+      if (now - navigation.startTime > MAX_NAVIGATION_AGE_MS) return true;
+      return navigation.domContentLoadedEventEnd > 0
+        && now - navigation.domContentLoadedEventEnd > MAX_POST_DOM_CONTENT_LOADED_MS;
+    }
+
+    const timing = performance.timing;
+    if (!timing?.navigationStart) return false;
+    const wallNow = Date.now();
+    if (wallNow - timing.navigationStart > MAX_NAVIGATION_AGE_MS) return true;
+    return timing.domContentLoadedEventEnd > 0
+      && wallNow - timing.domContentLoadedEventEnd > MAX_POST_DOM_CONTENT_LOADED_MS;
+  } catch {
+    return false;
+  }
 }
 
 function removeAntiFlickerFrom(ownerDocument: Document | null): void {
   clearTimers();
   if (!ownerDocument?.documentElement) return;
   const root = ownerDocument.documentElement;
-  root.classList.remove("drip-af");
-  root.classList.add("drip-af-reveal");
+  root.classList.remove("drip-af", "drip-af-reveal");
   const el = ownerDocument.getElementById(STYLE_ID);
-  // Remove style (if present) and class after transition completes
+  if (el) el.textContent = antiFlickerRevealCss;
+  // Remove the style after the existing transition cleanup window completes.
   cleanupTimer = setTimeout(() => {
     cleanupTimer = null;
     el?.remove();
-    root.classList.remove("drip-af-reveal");
-    if (antiFlickerOwnerDocument === ownerDocument) antiFlickerOwnerDocument = null;
+    root.classList.remove("drip-af", "drip-af-reveal");
+    if (antiFlickerOwnerDocument === ownerDocument) {
+      antiFlickerOwnerDocument = null;
+      antiFlickerProgressiveCss = "";
+      antiFlickerRevealCss = "";
+    }
   }, REVEAL_CLEANUP_MS);
 }