@coframe/sdk 1.1.9 → 1.1.11

package/README.md

@@ -40,6 +40,24 @@ await init({
 
 `init()` accepts `config` and optional `projectData`, so npm consumers do not need to manually populate `window.CFQ` first.
 
+### URL controls
+
+The npm entry uses the same browser URL controls as the script-tag and Edge
+installations:
+
+- `cf_disable` skips initialization and reveals any antiflicker state.
+- `coframe_variant_id` previews one or more comma-separated variant IDs.
+- `coframe_should_send_events=true` allows events during preview for testing.
+
+When `enableDebug: true` is set for the project, open the Launcher with
+`cf_debug=true` and use **Keep across navigation** in the Preview Session
+tool to keep the selected variants active for the current tab.
+
+For SSR, pass the complete request URL, including its query string, as
+`currentUrl`. This is required for query-sensitive targeting and allows
+`getProjectData()` to short-circuit before any request when `cf_disable` is
+present.
+
 ### React
 
 ```tsx
@@ -60,6 +78,8 @@ export default function App({ children }) {
 ```
 
 Mount the provider once at the root of your app. It initializes the SDK on mount and keeps treatment state available to child components.
+Keep it mounted across client-side route changes; runtime commands and the SDK's
+navigation observer handle subsequent page changes without remounting it.
 
 ### Server prefetch
 
@@ -148,6 +168,10 @@ import { CoframeProvider } from '@coframe/sdk/react'
 </CoframeProvider>
 ```
 
+If your privacy policy permits treatment analytics before cookie consent, use
+`onTreatmentAppliedBulkV2WithoutConsent` instead. It has the same callback
+arguments and does not fire again when consent is later granted.
+
 Outside React, you can also register callbacks from the main entry:
 
 ```ts
@@ -159,6 +183,7 @@ import { onLog, onTreatmentApplied } from '@coframe/sdk'
 - `getProjectData()` is intended for SSR and edge runtimes that can provide a full request URL and request headers.
 - In Pages Router or Remix, per-request server loaders are the most straightforward place to call it.
 - In App Router, keep the provider mounted in a persistent shell, but be careful about request URL handling in `layout.tsx` if you need query-sensitive SSR targeting.
+- The npm runtime reveals antiflicker styles but cannot insert them early enough to protect the initial paint. Render `antiflickerCSS` from `getProjectData()` in the server document head, or place equivalent static CSS and a timeout fallback there before application content.
 
 ## Package layout
 

package/dist/pkg/cf.cjs.js

@@ -859,6 +859,88 @@ const isSegmentEmpty = (segment) => {
     return segment.xpath === '';
 };
 
+function parseQueryString(query) {
+    const params = {};
+    const cleanQuery = query.startsWith('?') ? query.slice(1) : query;
+    if (!cleanQuery)
+        return params;
+    for (const pair of cleanQuery.split('&')) {
+        if (!pair)
+            continue;
+        const [key, value = ''] = pair.split('=').map(decodeURIComponent);
+        if (!(key in params)) {
+            params[key] = value;
+        }
+    }
+    return params;
+}
+function createURLSearchParams(query) {
+    if (typeof URLSearchParams !== 'undefined') {
+        const nativeParams = new URLSearchParams(query);
+        return {
+            get: (key) => nativeParams.get(key),
+        };
+    }
+    const simpleParams = parseQueryString(query);
+    return {
+        get: (key) => { var _a; return (_a = simpleParams[key]) !== null && _a !== void 0 ? _a : null; },
+    };
+}
+function getUrlSearchParams(url) {
+    const searchIndex = url.indexOf('?');
+    const firstHashIndex = url.indexOf('#');
+    if (searchIndex === -1 ||
+        (firstHashIndex !== -1 && firstHashIndex < searchIndex)) {
+        return createURLSearchParams('');
+    }
+    const hashIndex = url.indexOf('#', searchIndex);
+    const search = hashIndex !== -1
+        ? url.substring(searchIndex, hashIndex)
+        : url.substring(searchIndex);
+    return createURLSearchParams(search);
+}
+
+const COFRAME_DEBUG_QUERY_PARAM = 'cf_debug';
+const COFRAME_TOOL_INTERACTION_ATTRIBUTE = 'data-cf-t';
+const COFRAME_DEBUG_TOOLS_SESSION_STORAGE_KEY = 'cf.tools.enabled';
+const COFRAME_DEBUG_TOOLS_STATE_STORAGE_KEY = 'cf.tools.session';
+const ENABLED_VALUE = 'true';
+function enableDebugToolsSession() {
+    try {
+        window.sessionStorage.setItem(COFRAME_DEBUG_TOOLS_SESSION_STORAGE_KEY, ENABLED_VALUE);
+    }
+    catch (_a) {
+    }
+}
+function clearDebugToolsSession() {
+    try {
+        window.sessionStorage.removeItem(COFRAME_DEBUG_TOOLS_SESSION_STORAGE_KEY);
+        window.sessionStorage.removeItem(COFRAME_DEBUG_TOOLS_STATE_STORAGE_KEY);
+    }
+    catch (_a) {
+    }
+}
+function isDebugToolsSessionEnabled(allowed) {
+    if (!allowed) {
+        clearDebugToolsSession();
+        return false;
+    }
+    const enabledByUrl = getUrlSearchParams(getCurrentPageUrl()).get(COFRAME_DEBUG_QUERY_PARAM) ===
+        ENABLED_VALUE;
+    if (enabledByUrl) {
+        enableDebugToolsSession();
+        return true;
+    }
+    try {
+        const enabled = window.sessionStorage.getItem(COFRAME_DEBUG_TOOLS_SESSION_STORAGE_KEY) ===
+            ENABLED_VALUE;
+        return enabled;
+    }
+    catch (_a) {
+        return false;
+    }
+}
+
 const USER_CONTEXT_KEY_PREFIX = 'x-ctx-';
 const MAX_USER_CONTEXT_JSON_BYTES = 4096;
 function userContextJsonByteLength(userContext) {
@@ -1037,6 +1119,12 @@ function queueVariantViewEvent(coframe, { projectId, sessionId, orgId, userToken
 }
 function sendPageEngagementEvent(coframe, eventType, event, { projectId, sessionId, duration = 0, userToken, personalizationHeaders, }) {
     var _a;
+    if (event
+        .composedPath()
+        .some((target) => target instanceof Element &&
+        target.hasAttribute(COFRAME_TOOL_INTERACTION_ATTRIBUTE))) {
+        return;
+    }
     const startTime = performance.now();
     const x = event.clientX + window.scrollX;
     const y = event.clientY + window.scrollY;
@@ -1823,6 +1911,7 @@ const waitForBody = (timeout = 10000) => {
 function revealPage() {
     document.dispatchEvent(new CustomEvent('coframe:show', {}));
     document.documentElement.style.setProperty('--cf-show', '1');
+    document.documentElement.style.setProperty('--cf-visibility', 'visible');
 }
 async function replaceVariants(variants, orgId, logger, nonce) {
     const failedReplacements = [];
@@ -2215,44 +2304,8 @@ function debounce(func, wait) {
         }, wait);
     };
 }
-function parseQueryString(query) {
-    const params = {};
-    const cleanQuery = query.startsWith('?') ? query.slice(1) : query;
-    if (!cleanQuery)
-        return params;
-    for (const pair of cleanQuery.split('&')) {
-        if (!pair)
-            continue;
-        const [key, value = ''] = pair.split('=').map(decodeURIComponent);
-        if (!(key in params)) {
-            params[key] = value;
-        }
-    }
-    return params;
-}
-function createURLSearchParams(query) {
-    if (typeof URLSearchParams !== 'undefined') {
-        const nativeParams = new URLSearchParams(query);
-        return {
-            get: (key) => nativeParams.get(key),
-        };
-    }
-    const simpleParams = parseQueryString(query);
-    return {
-        get: (key) => { var _a; return (_a = simpleParams[key]) !== null && _a !== void 0 ? _a : null; },
-    };
-}
 function getCurrentUrlSearchParams() {
-    const url = getCurrentPageUrl();
-    const searchIndex = url.indexOf('?');
-    if (searchIndex === -1) {
-        return createURLSearchParams('');
-    }
-    const hashIndex = url.indexOf('#', searchIndex);
-    const search = hashIndex !== -1
-        ? url.substring(searchIndex, hashIndex)
-        : url.substring(searchIndex);
-    return createURLSearchParams(search);
+    return getUrlSearchParams(getCurrentPageUrl());
 }
 
 const defaultScale = 100000;
@@ -2487,6 +2540,44 @@ async function getVariantsAndElements(personalizationHeaders, project, previewVa
     });
 }
 
+const COFRAME_PREVIEW_SESSION_STORAGE_KEY = 'coframe.preview_variant';
+const COFRAME_PREVIEW_VARIANT_QUERY_PARAM = 'coframe_variant_id';
+function normalizePreviewVariantId(raw) {
+    if (!raw)
+        return null;
+    const ids = raw
+        .split(',')
+        .map((id) => id.trim())
+        .filter(Boolean);
+    return ids.length > 0 ? ids.join(',') : null;
+}
+function readPreviewVariantIdFromUrl(url = window.location.href) {
+    try {
+        return normalizePreviewVariantId(getUrlSearchParams(url).get(COFRAME_PREVIEW_VARIANT_QUERY_PARAM));
+    }
+    catch (_a) {
+        return null;
+    }
+}
+function readStoredPreviewVariantId() {
+    try {
+        return normalizePreviewVariantId(window.sessionStorage.getItem(COFRAME_PREVIEW_SESSION_STORAGE_KEY));
+    }
+    catch (_a) {
+        return null;
+    }
+}
+function resolvePreviewSource(url = window.location.href) {
+    const urlVariantId = readPreviewVariantIdFromUrl(url);
+    const storedVariantId = readStoredPreviewVariantId();
+    return {
+        effectiveVariantId: urlVariantId || storedVariantId,
+        isKeptForSession: Boolean(storedVariantId && storedVariantId === (urlVariantId || storedVariantId)),
+        storedVariantId,
+        urlVariantId,
+    };
+}
+
 function buildSessionContext(isInitialApply) {
     const context = {};
     const viewport = getScreenSize();
@@ -2640,220 +2731,6 @@ function rebindMetrics(coframe, logger, metrics, nonce) {
     }
 }
 
-function getActivePreviewModes(sessionPreview) {
-    if (!sessionPreview.isSessionPreviewActive ||
-        !sessionPreview.previewVariantId) {
-        return [];
-    }
-    return [
-        {
-            id: 'session-preview',
-            label: 'Preview on',
-            title: `Session preview is active for ${sessionPreview.previewVariantId}`,
-            variantIds: sessionPreview.previewVariantId
-                .split(',')
-                .map((id) => id.trim())
-                .filter(Boolean),
-        },
-    ];
-}
-
-const PREVIEW_UI_PROTOCOL_VERSION = 1;
-
-const SESSION_VARIANT_KEY = 'coframe.preview_variant';
-const PREVIEW_VARIANT_QUERY_PARAM = 'coframe_variant_id';
-const KEEP_PREVIEW_FOR_SESSION_QUERY_PARAM = 'keep_preview_for_session';
-let previewDismissed = false;
-function dismissSessionPreview() {
-    previewDismissed = true;
-    clearPreviewVariantId();
-    const url = new URL(window.location.href);
-    url.searchParams.delete(PREVIEW_VARIANT_QUERY_PARAM);
-    url.searchParams.delete(KEEP_PREVIEW_FOR_SESSION_QUERY_PARAM);
-    window.history.replaceState(window.history.state, '', url);
-    window.location.reload();
-}
-function normalizeVariantIds(raw) {
-    if (!raw)
-        return null;
-    const ids = raw
-        .split(',')
-        .map((id) => id.trim())
-        .filter(Boolean);
-    return ids.length > 0 ? ids.join(',') : null;
-}
-function readPreviewVariantId() {
-    try {
-        return sessionStorage.getItem(SESSION_VARIANT_KEY);
-    }
-    catch (_a) {
-        return null;
-    }
-}
-function persistPreviewVariantId(variantId) {
-    const normalized = normalizeVariantIds(variantId);
-    if (!normalized)
-        return;
-    try {
-        sessionStorage.setItem(SESSION_VARIANT_KEY, normalized);
-    }
-    catch (_a) {
-    }
-}
-function clearPreviewVariantId() {
-    try {
-        sessionStorage.removeItem(SESSION_VARIANT_KEY);
-    }
-    catch (_a) {
-    }
-}
-function resolvePreviewSource(urlParams = getCurrentUrlSearchParams()) {
-    return {
-        urlVariantId: urlParams.get(PREVIEW_VARIANT_QUERY_PARAM),
-        storedVariantId: readPreviewVariantId(),
-        keepForSession: urlParams.get(KEEP_PREVIEW_FOR_SESSION_QUERY_PARAM) === 'true',
-    };
-}
-function resolveSessionPreviewState() {
-    if (previewDismissed) {
-        return { isSessionPreviewActive: false, previewVariantId: null };
-    }
-    const previewSource = resolvePreviewSource();
-    const urlVariantId = normalizeVariantIds(previewSource.urlVariantId);
-    if (urlVariantId && previewSource.keepForSession) {
-        return {
-            isSessionPreviewActive: true,
-            previewVariantId: urlVariantId,
-        };
-    }
-    if (urlVariantId) {
-        return { isSessionPreviewActive: false, previewVariantId: null };
-    }
-    const storedVariantId = normalizeVariantIds(previewSource.storedVariantId);
-    return {
-        isSessionPreviewActive: !!storedVariantId,
-        previewVariantId: storedVariantId,
-    };
-}
-
-const PREVIEW_UI_SCRIPT_ID = 'coframe-preview-ui-script';
-const PREVIEW_UI_URL = "https://edge.cofra.me/preview-ui/latest.js";
-let loadPromise = null;
-let latestState = { modes: [] };
-let nonce;
-let logger;
-let mounted = false;
-function reportError(message, error) {
-    const errorMessage = error instanceof Error ? error.message : String(error);
-    if (logger) {
-        logger.warn(message, 'preview_ui_unavailable', { error: errorMessage });
-        return;
-    }
-    console.warn(`[Coframe] ${message}`, error);
-}
-function getPreviewUI() {
-    const api = window.CoframePreviewUI;
-    return (api === null || api === void 0 ? void 0 : api.protocolVersion) === PREVIEW_UI_PROTOCOL_VERSION ? api : undefined;
-}
-function loadPreviewUI() {
-    const existing = getPreviewUI();
-    if (existing)
-        return Promise.resolve(existing);
-    if (loadPromise)
-        return loadPromise;
-    loadPromise = new Promise((resolve, reject) => {
-        const script = document.createElement('script');
-        script.id = PREVIEW_UI_SCRIPT_ID;
-        script.async = true;
-        script.src = PREVIEW_UI_URL;
-        if (nonce)
-            script.nonce = nonce;
-        script.onload = () => {
-            const api = getPreviewUI();
-            if (!api) {
-                reject(new Error('Preview UI protocol is missing or incompatible'));
-                return;
-            }
-            resolve(api);
-        };
-        script.onerror = () => {
-            reject(new Error('Preview UI script failed to load'));
-        };
-        document.head.appendChild(script);
-    });
-    return loadPromise;
-}
-function renderPreviewUI(api) {
-    try {
-        if (latestState.modes.length === 0) {
-            api.unmount();
-            mounted = false;
-        }
-        else if (mounted) {
-            api.update(latestState);
-        }
-        else {
-            api.mount({ state: latestState, nonce, onDismiss: dismissPreviewPanel });
-            mounted = true;
-        }
-    }
-    catch (error) {
-        reportError('Preview UI could not be rendered', error);
-    }
-}
-function dismissPreviewPanel() {
-    dismissSessionPreview();
-    latestState = { modes: [] };
-    const api = getPreviewUI();
-    if (api)
-        renderPreviewUI(api);
-}
-function modesWithVariants(sessionPreview, variantsAndElements, applied = true) {
-    const activeModes = getActivePreviewModes(sessionPreview);
-    if (activeModes.length === 0)
-        return [];
-    const currentPageVariantIds = new Set((variantsAndElements === null || variantsAndElements === void 0 ? void 0 : variantsAndElements.map(({ variant }) => variant.id)) || []);
-    const slugById = new Map((variantsAndElements === null || variantsAndElements === void 0 ? void 0 : variantsAndElements.map(({ variant }) => [variant.id, variant.slug])) || []);
-    return activeModes.map((mode) => ({
-        id: mode.id,
-        label: mode.label,
-        title: mode.title,
-        variants: mode.variantIds.map((id) => ({
-            id,
-            slug: slugById.get(id) || null,
-            status: variantsAndElements
-                ? applied && currentPageVariantIds.has(id)
-                    ? 'active'
-                    : 'inactive'
-                : 'pending',
-        })),
-    }));
-}
-function resolveSessionPreviewPanel(sessionPreview, previewNonce, previewLogger) {
-    const modes = modesWithVariants(sessionPreview);
-    if (modes.length === 0)
-        return;
-    nonce = previewNonce;
-    logger = previewLogger;
-    latestState = { modes };
-    const existing = getPreviewUI();
-    if (existing) {
-        renderPreviewUI(existing);
-        return;
-    }
-    void loadPreviewUI()
-        .then(renderPreviewUI)
-        .catch((error) => reportError('Preview UI could not be loaded', error));
-}
-function updatePreviewPanel(variantsAndElements, sessionPreview, applied = true) {
-    latestState = {
-        modes: modesWithVariants(sessionPreview, variantsAndElements, applied),
-    };
-    const api = getPreviewUI();
-    if (api)
-        renderPreviewUI(api);
-}
-
 let lastUrl = null;
 function observeUrlChanges(baseUrlMatch, onUrlChange) {
     const tryTrack = () => {
@@ -3208,21 +3085,23 @@ function setupTracking(Coframe, projectResult, previewVariantId, executionStartT
 }
 
 function resolvePreview(pageUrl, previewVariantId, isSessionVariant) {
-    let urlPreviewVariantId = null;
-    try {
-        urlPreviewVariantId = new URL(pageUrl).searchParams.get('coframe_variant_id');
-    }
-    catch (_a) {
-        urlPreviewVariantId = getCurrentUrlSearchParams().get('coframe_variant_id');
+    const previewSource = resolvePreviewSource(pageUrl);
+    if (previewSource.urlVariantId) {
+        return {
+            previewVariantId: previewSource.urlVariantId,
+            isSessionVariant: previewSource.isKeptForSession,
+        };
     }
-    if (urlPreviewVariantId) {
-        return { previewVariantId: urlPreviewVariantId, isSessionVariant: false };
+    if (previewSource.storedVariantId) {
+        return {
+            previewVariantId: previewSource.storedVariantId,
+            isSessionVariant: true,
+        };
     }
     if (previewVariantId) {
         return { previewVariantId, isSessionVariant };
     }
-    const stored = readPreviewVariantId();
-    return { previewVariantId: stored, isSessionVariant: !!stored };
+    return { previewVariantId: null, isSessionVariant: false };
 }
 async function awaitHydration(config, Coframe, project) {
     var _a, _b;
@@ -3355,8 +3234,6 @@ function createApplyVariants(Coframe, config, previewVariantId, isSessionVariant
         Coframe.experimentInfo = experimentsInfo;
         Coframe.variantsAndElements = variantsAndElements;
         setFrameActivated(hasActivatedFrames);
-        const sessionPreview = resolveSessionPreviewState();
-        updatePreviewPanel(variantsAndElements, sessionPreview, !config.trackingOnly);
         if (Coframe.debug) {
             Coframe.debug.project = pageProject;
             Coframe.debug.frames = pageProject.frames;
@@ -3376,11 +3253,6 @@ function createApplyVariants(Coframe, config, previewVariantId, isSessionVariant
 async function modifyPage(Coframe, configResult, projectResult, analytics) {
     const { config, timeoutMs, previewVariantId, isSessionVariant, integrationStartTime, executionStartTime, } = configResult;
     const { project: cdnProject, personalizationHeaders } = projectResult;
-    if (resolveSessionPreviewState().isSessionPreviewActive) {
-        waitForBody(timeoutMs)
-            .then(() => resolveSessionPreviewPanel(resolveSessionPreviewState(), config.nonce, Coframe.logger))
-            .catch(() => { });
-    }
     if (!(await awaitHydration(config, Coframe, cdnProject)))
         return;
     if (cdnProject.tags) {
@@ -3473,15 +3345,13 @@ async function resolveConfig(Coframe, revealPage) {
     }
     Coframe.projectId = projectId;
     const urlParams = getCurrentUrlSearchParams();
-    const previewSource = resolvePreviewSource(urlParams);
+    const previewSource = resolvePreviewSource();
     const shouldSendEventsParam = urlParams.get('coframe_should_send_events');
     let previewVariantId = null;
     let isSessionVariant = false;
     if (previewSource.urlVariantId) {
         previewVariantId = previewSource.urlVariantId;
-        if (previewSource.keepForSession) {
-            persistPreviewVariantId(previewSource.urlVariantId);
-        }
+        isSessionVariant = previewSource.isKeptForSession;
     }
     else if (previewSource.storedVariantId) {
         previewVariantId = previewSource.storedVariantId;
@@ -3581,6 +3451,66 @@ async function resolveProject(Coframe, previewVariantId, isSessionVariant, confi
     };
 }
 
+const COFRAME_LAUNCHER_PROTOCOL_VERSION = 1;
+
+const LAUNCHER_SCRIPT_ID = 'coframe-tools-launcher-script';
+const LAUNCHER_URL = "https://edge.cofra.me/launcher/latest.js";
+let loading = false;
+function getLauncher() {
+    const launcher = window.CoframeLauncher;
+    return (launcher === null || launcher === void 0 ? void 0 : launcher.protocolVersion) === COFRAME_LAUNCHER_PROTOCOL_VERSION
+        ? launcher
+        : undefined;
+}
+function exitDebugSession() {
+    clearDebugToolsSession();
+    const url = new URL(window.location.href);
+    url.searchParams.delete(COFRAME_DEBUG_QUERY_PARAM);
+    window.history.replaceState(window.history.state, '', url);
+}
+function mountLauncher(nonce) {
+    const launcher = getLauncher();
+    if (!launcher)
+        return false;
+    launcher.mount({ nonce, onExitDebugSession: exitDebugSession });
+    return true;
+}
+function loadLauncherIfEnabled(enabled, nonce) {
+    if (typeof window === 'undefined')
+        return;
+    let sessionEnabled = false;
+    try {
+        sessionEnabled = isDebugToolsSessionEnabled(enabled);
+    }
+    catch (error) {
+        console.warn('[Coframe] Unable to determine Debug Tools session', error);
+        return;
+    }
+    if (!sessionEnabled || mountLauncher(nonce) || loading) {
+        return;
+    }
+    loading = true;
+    const script = document.createElement('script');
+    script.id = LAUNCHER_SCRIPT_ID;
+    script.async = true;
+    script.src = LAUNCHER_URL;
+    if (nonce)
+        script.nonce = nonce;
+    script.onload = () => {
+        loading = false;
+        if (!mountLauncher(nonce)) {
+            document.head.removeChild(script);
+            console.warn('[Coframe] Launcher protocol is missing or incompatible');
+        }
+    };
+    script.onerror = () => {
+        loading = false;
+        document.head.removeChild(script);
+        console.warn('[Coframe] Launcher script failed to load');
+    };
+    document.head.appendChild(script);
+}
+
 function injectOptions(options) {
     var _a;
     if (options.config) {
@@ -3646,6 +3576,12 @@ const Coframe = {
 };
 Coframe.logger = createLogger(() => Coframe);
 async function init(options) {
+    if (typeof window !== 'undefined' &&
+        /cf_disable/.test(window.location.search)) {
+        console.warn('[Coframe] Disabled via URL parameter');
+        revealPage();
+        return;
+    }
     if (options)
         injectOptions(options);
     const gracefulExit = (msg) => {
@@ -3656,6 +3592,7 @@ async function init(options) {
     const configResult = await resolveConfig(Coframe, revealPage);
     if (!configResult)
         return;
+    loadLauncherIfEnabled(configResult.config.enableDebug === true, configResult.config.nonce);
     const projectResult = await resolveProject(Coframe, configResult.previewVariantId, configResult.isSessionVariant, configResult.config);
     if (!projectResult)
         return;