npm - @drip-apex/sdk - Versions diffs - 0.1.0 - Mend

@drip-apex/sdk 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (227) hide show

package/LICENSE +21 -0
package/README.md +46 -0
package/dist/_headers +3 -0
package/dist/bundle-report.json +564 -0
package/dist/drip.debug.js +2 -0
package/dist/drip.debug.js.map +1 -0
package/dist/drip.heatmap.js +2 -0
package/dist/drip.heatmap.js.map +1 -0
package/dist/drip.js +2 -0
package/dist/drip.js.map +1 -0
package/dist/drip.live.js +2 -0
package/dist/drip.live.js.map +1 -0
package/dist/editor.js +480 -0
package/dist/editor.js.map +7 -0
package/dist/index.mjs +645 -0
package/dist/index.mjs.map +7 -0
package/dist/metafiles/drip.debug.meta.json +973 -0
package/dist/metafiles/drip.heatmap.meta.json +918 -0
package/dist/metafiles/drip.live.meta.json +918 -0
package/dist/metafiles/drip.meta.json +973 -0
package/dist/metafiles/editor.meta.json +321 -0
package/dist/metafiles/index.meta.json +1039 -0
package/dist/metafiles/index.mjs.meta.json +78 -0
package/dist/react/index.js +16973 -0
package/dist/react/index.js.map +7 -0
package/dist/sri.json +27 -0
package/dist/types/analytics.d.ts +15 -0
package/dist/types/antiflicker.d.ts +14 -0
package/dist/types/assignment-store.d.ts +30 -0
package/dist/types/audit.d.ts +9 -0
package/dist/types/bucket.d.ts +2 -0
package/dist/types/bucketing-cleanup.d.ts +5 -0
package/dist/types/commerce-gift.d.ts +41 -0
package/dist/types/commerce-price.d.ts +22 -0
package/dist/types/commerce-shipping.d.ts +28 -0
package/dist/types/css.d.ts +5 -0
package/dist/types/cwv.d.ts +10 -0
package/dist/types/data-layer-normalize.d.ts +1 -0
package/dist/types/debug.d.ts +23 -0
package/dist/types/define.d.ts +87 -0
package/dist/types/devtools.d.ts +32 -0
package/dist/types/dom-trigger.d.ts +3 -0
package/dist/types/editor/api.d.ts +37 -0
package/dist/types/editor/artifacts.d.ts +15 -0
package/dist/types/editor/command-runtime.d.ts +48 -0
package/dist/types/editor/controller.d.ts +97 -0
package/dist/types/editor/device-preview.d.ts +23 -0
package/dist/types/editor/index.d.ts +9 -0
package/dist/types/editor/operator.d.ts +39 -0
package/dist/types/editor/picker.d.ts +23 -0
package/dist/types/editor/selector.d.ts +2 -0
package/dist/types/editor/types.d.ts +55 -0
package/dist/types/editor/view-kit.d.ts +33 -0
package/dist/types/editor/view.d.ts +5 -0
package/dist/types/editor-bootstrap.d.ts +37 -0
package/dist/types/exclusion-groups.d.ts +59 -0
package/dist/types/exposure-signals.d.ts +7 -0
package/dist/types/flags.d.ts +65 -0
package/dist/types/goals.d.ts +16 -0
package/dist/types/guards.d.ts +39 -0
package/dist/types/handover.d.ts +10 -0
package/dist/types/hash.d.ts +19 -0
package/dist/types/heatmap.d.ts +8 -0
package/dist/types/hideflicker.d.ts +15 -0
package/dist/types/hydration.d.ts +11 -0
package/dist/types/index.d.ts +144 -0
package/dist/types/js.d.ts +6 -0
package/dist/types/module.d.ts +4 -0
package/dist/types/money.d.ts +14 -0
package/dist/types/mutate.d.ts +34 -0
package/dist/types/observer-mute.d.ts +3 -0
package/dist/types/pii-keys.d.ts +1 -0
package/dist/types/prerequisites.d.ts +12 -0
package/dist/types/qa-assistant-state.d.ts +68 -0
package/dist/types/qa-assistant-view.d.ts +6 -0
package/dist/types/qa-assistant.d.ts +9 -0
package/dist/types/qa-toolbar.d.ts +19 -0
package/dist/types/react/index.d.ts +84 -0
package/dist/types/reassert-sentinel.d.ts +6 -0
package/dist/types/router.d.ts +9 -0
package/dist/types/runtime-tools.d.ts +50 -0
package/dist/types/runtime.d.ts +22 -0
package/dist/types/safe-regex.d.ts +6 -0
package/dist/types/sanitize.d.ts +5 -0
package/dist/types/semantic.d.ts +7 -0
package/dist/types/shopify-cart-events.d.ts +7 -0
package/dist/types/shopify-cart.d.ts +62 -0
package/dist/types/signals.d.ts +31 -0
package/dist/types/surface-signals.d.ts +6 -0
package/dist/types/targeting-diagnostics.d.ts +5 -0
package/dist/types/targeting.d.ts +50 -0
package/dist/types/test-fixtures/commerce.d.ts +12 -0
package/dist/types/track.d.ts +79 -0
package/dist/types/types.d.ts +859 -0
package/dist/types/wait.d.ts +7 -0
package/package.json +74 -0
package/src/analytics.ts +146 -0
package/src/antiflicker.test.ts +127 -0
package/src/antiflicker.ts +147 -0
package/src/assignment-store.test.ts +171 -0
package/src/assignment-store.ts +208 -0
package/src/audit.test.ts +17 -0
package/src/audit.ts +362 -0
package/src/bucket.test.ts +65 -0
package/src/bucket.ts +18 -0
package/src/bucketing-cleanup.test.ts +30 -0
package/src/bucketing-cleanup.ts +72 -0
package/src/bucketing-parity.test.ts +41 -0
package/src/commerce-analytics-lifecycle.test.ts +1416 -0
package/src/commerce-config-lifecycle.test.ts +274 -0
package/src/commerce-epoch-lifecycle.test.ts +62 -0
package/src/commerce-gift.test.ts +1293 -0
package/src/commerce-gift.ts +979 -0
package/src/commerce-offers-display.test.ts +154 -0
package/src/commerce-price.test.ts +1145 -0
package/src/commerce-price.ts +941 -0
package/src/commerce-revocation-lifecycle.test.ts +78 -0
package/src/commerce-shipping.test.ts +630 -0
package/src/commerce-shipping.ts +447 -0
package/src/config-fetch.test.ts +325 -0
package/src/css.ts +54 -0
package/src/cwv.test.ts +95 -0
package/src/cwv.ts +129 -0
package/src/data-layer-normalize.ts +21 -0
package/src/debug.test.ts +83 -0
package/src/debug.ts +138 -0
package/src/define.test.ts +327 -0
package/src/define.ts +208 -0
package/src/devtools.ts +582 -0
package/src/dom-trigger.test.ts +70 -0
package/src/dom-trigger.ts +55 -0
package/src/editor/api.test.ts +154 -0
package/src/editor/api.ts +185 -0
package/src/editor/artifacts.test.ts +57 -0
package/src/editor/artifacts.ts +115 -0
package/src/editor/command-runtime.test.ts +225 -0
package/src/editor/command-runtime.ts +572 -0
package/src/editor/controller.test.ts +371 -0
package/src/editor/controller.ts +596 -0
package/src/editor/device-preview.test.ts +60 -0
package/src/editor/device-preview.ts +120 -0
package/src/editor/index.test.ts +161 -0
package/src/editor/index.ts +169 -0
package/src/editor/operator.test.ts +148 -0
package/src/editor/operator.ts +256 -0
package/src/editor/picker.test.ts +58 -0
package/src/editor/picker.ts +152 -0
package/src/editor/selector.test.ts +44 -0
package/src/editor/selector.ts +110 -0
package/src/editor/types.ts +92 -0
package/src/editor/view-kit.ts +162 -0
package/src/editor/view.test.ts +535 -0
package/src/editor/view.ts +1395 -0
package/src/editor-bootstrap.test.ts +116 -0
package/src/editor-bootstrap.ts +213 -0
package/src/event-schema-contract.test.ts +35 -0
package/src/exclusion-groups.test.ts +383 -0
package/src/exclusion-groups.ts +270 -0
package/src/exposure-signals.test.ts +182 -0
package/src/exposure-signals.ts +110 -0
package/src/flags.test.ts +322 -0
package/src/flags.ts +201 -0
package/src/goals.test.ts +42 -0
package/src/goals.ts +200 -0
package/src/guards.test.ts +249 -0
package/src/guards.ts +250 -0
package/src/handover-cache-order.test.ts +32 -0
package/src/handover.test.ts +349 -0
package/src/handover.ts +309 -0
package/src/hash.ts +214 -0
package/src/heatmap.test.ts +305 -0
package/src/heatmap.ts +373 -0
package/src/hideflicker.ts +21 -0
package/src/hydration.test.ts +252 -0
package/src/hydration.ts +203 -0
package/src/index.ts +7513 -0
package/src/init-empty.test.ts +5572 -0
package/src/js.test.ts +26 -0
package/src/js.ts +61 -0
package/src/module.ts +50 -0
package/src/money.test.ts +35 -0
package/src/money.ts +53 -0
package/src/mutate.test.ts +304 -0
package/src/mutate.ts +469 -0
package/src/observer-mute.test.ts +88 -0
package/src/observer-mute.ts +45 -0
package/src/page-trigger.test.ts +84 -0
package/src/personalization.test.ts +68 -0
package/src/pii-keys.ts +17 -0
package/src/prerequisites.test.ts +39 -0
package/src/prerequisites.ts +94 -0
package/src/qa-assistant-state.test.ts +471 -0
package/src/qa-assistant-state.ts +505 -0
package/src/qa-assistant-view.test.ts +185 -0
package/src/qa-assistant-view.ts +768 -0
package/src/qa-assistant.ts +40 -0
package/src/qa-toolbar.ts +444 -0
package/src/react/index.test.tsx +177 -0
package/src/react/index.tsx +252 -0
package/src/reassert-sentinel.test.ts +314 -0
package/src/reassert-sentinel.ts +191 -0
package/src/router.test.ts +78 -0
package/src/router.ts +92 -0
package/src/runtime-tools.test.ts +112 -0
package/src/runtime-tools.ts +403 -0
package/src/runtime.test.ts +217 -0
package/src/runtime.ts +268 -0
package/src/safe-regex.ts +35 -0
package/src/sanitize.ts +34 -0
package/src/semantic.ts +245 -0
package/src/shopify-cart-events.test.ts +76 -0
package/src/shopify-cart-events.ts +115 -0
package/src/shopify-cart.test.ts +2823 -0
package/src/shopify-cart.ts +1256 -0
package/src/signals.ts +226 -0
package/src/surface-signals.test.ts +83 -0
package/src/surface-signals.ts +165 -0
package/src/targeting-diagnostics.ts +560 -0
package/src/targeting.detailed.test.ts +443 -0
package/src/targeting.test.ts +1054 -0
package/src/targeting.ts +1024 -0
package/src/test-fixtures/commerce.ts +65 -0
package/src/track.test.ts +817 -0
package/src/track.ts +519 -0
package/src/types.ts +991 -0
package/src/wait.test.ts +96 -0
package/src/wait.ts +238 -0

package/src/hydration.test.ts ADDED Viewed

@@ -0,0 +1,252 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  assignmentsHaveVisualWork,
+  awaitHydration,
+  detectSsrFramework,
+  holdMutations,
+  releaseMutations,
+  resetHydrationState,
+  signalHydrated,
+} from "./hydration";
+import type { Assignment } from "./types";
+function clearFrameworkMarkers(): void {
+  document.documentElement.innerHTML = "<head></head><body></body>";
+  delete (window as Window & { __NUXT__?: unknown }).__NUXT__;
+  delete (window as Window & { __NEXT_DATA__?: unknown }).__NEXT_DATA__;
+}
+describe("hydration coexistence gate", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    resetHydrationState();
+    clearFrameworkMarkers();
+    delete (window as Window & { __dripPerf?: unknown }).__dripPerf;
+    vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => (
+      setTimeout(() => callback(performance.now()), 16) as unknown as number
+    ));
+    vi.stubGlobal("cancelAnimationFrame", (id: number) => clearTimeout(id));
+  });
+  afterEach(() => {
+    resetHydrationState();
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+  it("detects Nuxt, Next, and generic server-rendered markers", () => {
+    expect(detectSsrFramework()).toBeNull();
+    (window as Window & { __NUXT__?: unknown }).__NUXT__ = {};
+    expect(detectSsrFramework()).toBe("nuxt");
+    clearFrameworkMarkers();
+    document.body.innerHTML = '<div id="__nuxt"></div>';
+    expect(detectSsrFramework()).toBe("nuxt");
+    clearFrameworkMarkers();
+    (window as Window & { __NEXT_DATA__?: unknown }).__NEXT_DATA__ = {};
+    expect(detectSsrFramework()).toBe("next");
+    clearFrameworkMarkers();
+    document.body.innerHTML = '<div id="__next"></div>';
+    expect(detectSsrFramework()).toBe("next");
+    clearFrameworkMarkers();
+    (window as Window & { __next_f?: unknown }).__next_f = [];
+    expect(detectSsrFramework()).toBe("next");
+    delete (window as Window & { __next_f?: unknown }).__next_f;
+    clearFrameworkMarkers();
+    document.head.innerHTML = '<script src="/_next/static/chunks/app/layout.js"></script>';
+    expect(detectSsrFramework()).toBe("next");
+    clearFrameworkMarkers();
+    document.body.innerHTML = '<main data-server-rendered="true"></main>';
+    expect(detectSsrFramework()).toBe("server-rendered");
+  });
+  it("resolves on the drip:hydrated document event", async () => {
+    document.body.innerHTML = '<div id="__next"></div>';
+    const gate = awaitHydration(1_000);
+    document.dispatchEvent(new CustomEvent("drip:hydrated"));
+    await expect(gate).resolves.toBeUndefined();
+    expect((window as Window & { __dripPerf?: Record<string, unknown> }).__dripPerf).toMatchObject({
+      hydration_detected_at: expect.any(Number),
+      apply_delayed_ms: expect.any(Number),
+    });
+  });
+  it("re-detects SSR markers after DOMContentLoaded for head installs", async () => {
+    // A head install runs before the body markers are parsed.
+    Object.defineProperty(document, "readyState", { value: "loading", configurable: true });
+    try {
+      const gate = awaitHydration(3_000, { waitForHydration: true });
+      let resolved = false;
+      void gate.then(() => { resolved = true; });
+      // The parser reaches the SSR root, then DOMContentLoaded fires.
+      document.body.innerHTML = '<div id="__next"></div>';
+      Object.defineProperty(document, "readyState", { value: "interactive", configurable: true });
+      document.dispatchEvent(new Event("DOMContentLoaded"));
+      await Promise.resolve();
+      await Promise.resolve();
+      expect(resolved).toBe(false);
+      document.dispatchEvent(new CustomEvent("drip:hydrated"));
+      await expect(gate).resolves.toBeUndefined();
+    } finally {
+      Object.defineProperty(document, "readyState", { value: "complete", configurable: true });
+    }
+  });
+  it("honors an explicit hydration signal before DOMContentLoaded", async () => {
+    Object.defineProperty(document, "readyState", { value: "loading", configurable: true });
+    try {
+      const gate = awaitHydration(3_000, { waitForHydration: true });
+      let resolved = false;
+      void gate.then(() => { resolved = true; });
+      signalHydrated();
+      await Promise.resolve();
+      await Promise.resolve();
+      await expect(gate).resolves.toBeUndefined();
+      expect(resolved).toBe(true);
+    } finally {
+      Object.defineProperty(document, "readyState", { value: "complete", configurable: true });
+    }
+  });
+  it("does not restart the timeout after the head-install budget is exhausted", async () => {
+    Object.defineProperty(document, "readyState", { value: "loading", configurable: true });
+    try {
+      const gate = awaitHydration(500, { waitForHydration: true });
+      let resolved = false;
+      void gate.then(() => { resolved = true; });
+      // The SSR marker appears, but DOMContentLoaded never arrives before the
+      // configured deadline. Re-detection must fail open at that deadline.
+      document.body.innerHTML = '<div id="__next"></div>';
+      await vi.advanceTimersByTimeAsync(500);
+      // Vitest schedules the recursive zero-budget fail-open timer on the next
+      // fake-clock tick after the original deadline callback.
+      await vi.advanceTimersByTimeAsync(1);
+      await expect(gate).resolves.toBeUndefined();
+      expect(resolved).toBe(true);
+    } finally {
+      Object.defineProperty(document, "readyState", { value: "complete", configurable: true });
+    }
+  });
+  it("fails open at the head-install deadline without a framework marker or DOMContentLoaded", async () => {
+    Object.defineProperty(document, "readyState", { value: "loading", configurable: true });
+    try {
+      const gate = awaitHydration(500, { waitForHydration: true });
+      let resolved = false;
+      void gate.then(() => { resolved = true; });
+      await vi.advanceTimersByTimeAsync(500);
+      await vi.advanceTimersByTimeAsync(1);
+      await expect(gate).resolves.toBeUndefined();
+      expect(resolved).toBe(true);
+      expect((window as Window & { __dripPerf?: Record<string, unknown> }).__dripPerf?.hydration_timeout).toBe(true);
+    } finally {
+      Object.defineProperty(document, "readyState", { value: "complete", configurable: true });
+    }
+  });
+  it("resolves when the hydrated command signal is received", async () => {
+    document.body.innerHTML = '<div id="__nuxt"></div>';
+    const gate = awaitHydration(1_000);
+    signalHydrated();
+    await expect(gate).resolves.toBeUndefined();
+  });
+  it("honors an explicit hydration wait without known framework markers", async () => {
+    const gate = awaitHydration(1_000, { waitForHydration: true });
+    let resolved = false;
+    void gate.then(() => { resolved = true; });
+    await vi.advanceTimersByTimeAsync(200);
+    expect(resolved).toBe(false);
+    signalHydrated();
+    await expect(gate).resolves.toBeUndefined();
+  });
+  it("waits for two quiet frames and at least 50ms after framework mutations", async () => {
+    document.body.innerHTML = '<div id="__next"></div>';
+    const gate = awaitHydration(1_000);
+    document.getElementById("__next")?.appendChild(document.createElement("section"));
+    await Promise.resolve();
+    await vi.advanceTimersByTimeAsync(96);
+    await expect(gate).resolves.toBeUndefined();
+  });
+  it("fails open on the hard hydration timeout", async () => {
+    document.body.innerHTML = '<div id="__next"></div>';
+    vi.stubGlobal("requestAnimationFrame", vi.fn(() => 1));
+    const gate = awaitHydration(500);
+    await vi.advanceTimersByTimeAsync(500);
+    await expect(gate).resolves.toBeUndefined();
+    expect((window as Window & { __dripPerf?: Record<string, unknown> }).__dripPerf?.hydration_timeout).toBe(true);
+  });
+  it("composes nested holds and releases only when the counter reaches zero", async () => {
+    expect(holdMutations()).toBe(1);
+    expect(holdMutations()).toBe(2);
+    const gate = awaitHydration(1_000, { waitForHydration: false });
+    expect(releaseMutations()).toBe(1);
+    let resolved = false;
+    void gate.then(() => { resolved = true; });
+    await Promise.resolve();
+    expect(resolved).toBe(false);
+    expect(releaseMutations()).toBe(0);
+    await expect(gate).resolves.toBeUndefined();
+  });
+  it("fails open a held mutation gate at the configured timeout", async () => {
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    holdMutations();
+    const gate = awaitHydration(500, { waitForHydration: false });
+    await vi.advanceTimersByTimeAsync(500);
+    await expect(gate).resolves.toBeUndefined();
+    expect((window as Window & { __dripPerf?: Record<string, unknown> }).__dripPerf?.hold_timeout).toBe(true);
+  });
+});
+describe("assignmentsHaveVisualWork", () => {
+  const assignment = (overrides: Partial<Assignment> = {}): Assignment => ({
+    experimentId: "exp-1",
+    variationId: "var-1",
+    index: 1,
+    isControl: false,
+    hashValue: "hash-1",
+    mutations: [],
+    ...overrides,
+  });
+  it("reports no visual work for empty or control/no-mutation sets", () => {
+    expect(assignmentsHaveVisualWork([])).toBe(false);
+    expect(assignmentsHaveVisualWork([assignment()])).toBe(false);
+  });
+  it("detects mutations, variation code, and experiment code", () => {
+    expect(
+      assignmentsHaveVisualWork([
+        assignment({ mutations: [{ selector: "h1", action: "text", text: "x" }] }),
+      ]),
+    ).toBe(true);
+    expect(assignmentsHaveVisualWork([assignment({ css: ".a{}" })])).toBe(true);
+    expect(assignmentsHaveVisualWork([assignment({ js: "1" })])).toBe(true);
+    expect(assignmentsHaveVisualWork([assignment({ experimentCss: ".b{}" })])).toBe(true);
+    expect(assignmentsHaveVisualWork([assignment({ experimentJs: "1" })])).toBe(true);
+    expect(
+      assignmentsHaveVisualWork([assignment({ externalJsUrl: "https://cdn.example/x.js" })]),
+    ).toBe(true);
+  });
+});

package/src/hydration.ts ADDED Viewed

@@ -0,0 +1,203 @@
+import { registerMutedObserver, unregisterMutedObserver } from "./observer-mute";
+import { isCommercePriceWorkPending } from "./commerce-price";
+import type { Assignment, CommercePriceSettings } from "./types";
+let holds = 0;
+let hydratedAt = 0;
+const signals = new Set<() => void>();
+function perf(): Record<string, unknown> | null {
+  if (typeof window === "undefined") return null;
+  const target = window as Window & { __dripPerf?: Record<string, unknown> };
+  return target.__dripPerf = target.__dripPerf ?? {};
+}
+export function detectSsrFramework(): "nuxt" | "next" | "server-rendered" | null {
+  if (typeof window === "undefined" || typeof document === "undefined") return null;
+  const runtime = window as Window & { __NUXT__?: unknown; __NEXT_DATA__?: unknown; __next_f?: unknown };
+  if (runtime.__NUXT__ !== undefined || document.querySelector("#__nuxt")) return "nuxt";
+  if (
+    runtime.__NEXT_DATA__ !== undefined ||
+    runtime.__next_f !== undefined ||
+    document.querySelector("#__next") ||
+    document.querySelector('script[src*="/_next/static/"]')
+  ) return "next";
+  return document.querySelector("[data-server-rendered]") ? "server-rendered" : null;
+}
+export function holdMutations(): number {
+  return ++holds;
+}
+export function releaseMutations(): number {
+  holds = Math.max(0, holds - 1);
+  if (!holds) signals.forEach((signal) => signal());
+  return holds;
+}
+export function hasMutationHold(): boolean {
+  return holds > 0;
+}
+export function signalHydrated(): void {
+  hydratedAt ||= Date.now();
+  signals.forEach((signal) => signal());
+}
+export function awaitHydration(
+  timeoutMs: number,
+  options: { waitForHydration?: boolean } = {},
+): Promise<void> {
+  const started = Date.now();
+  const boundedTimeoutMs = Number.isFinite(timeoutMs)
+    ? Math.max(0, Math.min(10_000, timeoutMs))
+    : 3_000;
+  if (
+    boundedTimeoutMs > 0 &&
+    options.waitForHydration !== false &&
+    !hydratedAt &&
+    typeof document !== "undefined" &&
+    document.readyState === "loading" &&
+    detectSsrFramework() === null
+  ) {
+    // Head installs run before the SSR root markers (#__next, #__nuxt,
+    // data-server-rendered) are parsed; deciding "no hydration" now would
+    // silently skip after_hydration exactly where it matters. Re-detect
+    // once the DOM is available — racing the same hard timeout so a
+    // delayed DOMContentLoaded can never hold the gate past the budget.
+    return new Promise((resolve) => {
+      let settled = false;
+      const proceed = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(fallback);
+        document.removeEventListener("DOMContentLoaded", proceed);
+        signals.delete(proceed);
+        const remaining = Math.max(0, boundedTimeoutMs - (Date.now() - started));
+        void awaitHydration(remaining, options).then(resolve);
+      };
+      document.addEventListener("DOMContentLoaded", proceed, { once: true });
+      // A framework can call drip.hydrated() before the parser reaches the
+      // root marker/DOMContentLoaded. Let that explicit signal re-enter the
+      // normal gate immediately instead of waiting for the hard deadline.
+      signals.add(proceed);
+      const fallback = setTimeout(proceed, boundedTimeoutMs);
+    });
+  }
+  const frameworkDetected = detectSsrFramework() !== null;
+  const explicitHydrationWait = options.waitForHydration === true;
+  const needsHydration =
+    options.waitForHydration !== false &&
+    !hydratedAt &&
+    (explicitHydrationWait || frameworkDetected);
+  if (!needsHydration && !holds) return Promise.resolve();
+  return new Promise((resolve) => {
+    let hydrationDone = !needsHydration;
+    let settled = false;
+    let observer: MutationObserver | null = null;
+    let frame = 0;
+    let quietFrames = 0;
+    let lastMutation = Date.now();
+    const finish = (timedOut = false) => {
+      if (settled) return;
+      settled = true;
+      const hydrationTimeout = timedOut && !hydrationDone;
+      const holdTimeout = timedOut && holds > 0;
+      if (hydrationTimeout) hydratedAt = Date.now();
+      if (holdTimeout) {
+        holds = 0;
+        console.warn("[drip] Mutation hold timed out; applying fail-open");
+      }
+      const metrics = perf();
+      if (metrics) {
+        if (needsHydration || hydratedAt) metrics.hydration_detected_at = hydratedAt || Date.now();
+        metrics.apply_delayed_ms = Math.max(0, Date.now() - started);
+        if (hydrationTimeout) metrics.hydration_timeout = true;
+        if (holdTimeout) metrics.hold_timeout = true;
+      }
+      signals.delete(check);
+      clearTimeout(timer);
+      if (frame) cancelAnimationFrame(frame);
+      if (observer) {
+        observer.disconnect();
+        unregisterMutedObserver(observer);
+      }
+      resolve();
+    };
+    function check() {
+      if (hydratedAt) hydrationDone = true;
+      if (hydrationDone && !holds) finish();
+    }
+    const onFrame = () => {
+      quietFrames = Date.now() - lastMutation >= 50 ? quietFrames + 1 : 0;
+      if (quietFrames === 2) {
+        hydratedAt = Date.now();
+        hydrationDone = true;
+        check();
+      } else if (!settled) frame = requestAnimationFrame(onFrame);
+    };
+    const beginQuiet = () => {
+      if (!needsHydration || hydrationDone || settled) return;
+      if (typeof MutationObserver === "undefined" || !document.documentElement) {
+        hydrationDone = true;
+        check();
+        return;
+      }
+      const onRecords: MutationCallback = () => {
+        lastMutation = Date.now();
+        quietFrames = 0;
+      };
+      observer = new MutationObserver(onRecords);
+      registerMutedObserver(observer, onRecords);
+      observer.observe(document.documentElement, { attributes: true, characterData: true, childList: true, subtree: true });
+      frame = requestAnimationFrame(onFrame);
+    };
+    signals.add(check);
+    const timer = setTimeout(() => finish(true), boundedTimeoutMs);
+    if (needsHydration && frameworkDetected) {
+      if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", beginQuiet, { once: true });
+      else beginQuiet();
+    }
+    check();
+  });
+}
+export function resetHydrationState(): void {
+  holds = 0;
+  hydratedAt = 0;
+  signals.forEach((signal) => signal());
+}
+// The anti-flicker reveal happens inside applyAssignments(), so deferring the
+// apply (hydration wait / pre-init hold) is only justified when the assignment
+// set carries visual work to coordinate. Untreated visitors — traffic-excluded
+// or control/no-mutation assignments — must apply and reveal immediately.
+export function assignmentsHaveVisualWork(
+  assignments: Assignment[],
+  priceSettings?: CommercePriceSettings,
+): boolean {
+  return (
+    assignments.some(
+      (assignment) =>
+        assignment.mutations.length > 0 ||
+        Boolean(
+          assignment.css ||
+            assignment.js ||
+            assignment.externalCssUrl ||
+            assignment.externalJsUrl ||
+            assignment.experimentCss ||
+            assignment.experimentJs,
+        ),
+    ) || isCommercePriceWorkPending(priceSettings, assignments)
+  );
+}
+if (typeof document !== "undefined" && typeof document.addEventListener === "function") {
+  document.addEventListener("drip:hydrated", signalHydrated);
+}