@webiny/website-builder-sdk 0.0.0-unstable.eb196ccd2f → 0.0.0-unstable.eb81deee7e

package/experiments/render.js

@@ -0,0 +1,149 @@
+import { nanoid } from "nanoid";
+import { getHeadersProvider } from "../headersProvider.js";
+import { assignVariant, forcedAssignment } from "./bucketing.js";
+import { getAnalyticsProvider } from "./analyticsProvider.js";
+const DEFAULT_VISITOR_COOKIE = "wb_ab_vid";
+const FORCED_VARIANT_PARAM = "wb-variant";
+const DEFAULT_GEO_HEADERS = [
+    "x-vercel-ip-country",
+    "cloudfront-viewer-country",
+    "cf-ipcountry",
+    "x-country-code"
+];
+const readCookie = (cookieHeader, name)=>{
+    if (!cookieHeader) return;
+    for (const part of cookieHeader.split(";")){
+        const index = part.indexOf("=");
+        if (-1 === index) continue;
+        const key = part.slice(0, index).trim();
+        if (key === name) return decodeURIComponent(part.slice(index + 1).trim());
+    }
+};
+const detectDevice = (userAgent)=>{
+    if (!userAgent) return;
+    if (/iPad|Tablet|PlayBook|Silk/i.test(userAgent)) return "tablet";
+    if (/Mobi|Android.+Mobile|iPhone|iPod|Windows Phone/i.test(userAgent)) return "mobile";
+    return "desktop";
+};
+const resolveVisitorContext = async (options = {})=>{
+    const cookieName = options.cookieName ?? DEFAULT_VISITOR_COOKIE;
+    const generate = options.generateVisitorId ?? (()=>nanoid());
+    let headers;
+    const provider = getHeadersProvider();
+    if (provider) try {
+        headers = await provider();
+    } catch  {
+        headers = void 0;
+    }
+    let visitorId = options.visitorId;
+    let generatedVisitorId = false;
+    if (!visitorId) visitorId = readCookie(headers?.get("cookie"), cookieName);
+    if (!visitorId) {
+        visitorId = generate();
+        generatedVisitorId = true;
+    }
+    let country = options.country;
+    if (!country && headers) for (const header of options.geoHeaders ?? DEFAULT_GEO_HEADERS){
+        const value = headers.get(header);
+        if (value) {
+            country = value.toUpperCase();
+            break;
+        }
+    }
+    const device = options.device ?? detectDevice(headers?.get("user-agent"));
+    return {
+        context: {
+            visitorId,
+            country,
+            device
+        },
+        generatedVisitorId
+    };
+};
+const resolveForcedVariantId = (options)=>{
+    if (options.forcedVariantId) return options.forcedVariantId;
+    const raw = options.searchParams?.[FORCED_VARIANT_PARAM];
+    return Array.isArray(raw) ? raw[0] : raw;
+};
+const overlayVariant = (baseline, variant)=>({
+        ...baseline,
+        properties: variant.properties,
+        bindings: variant.bindings,
+        elements: variant.elements,
+        extensions: variant.extensions,
+        metadata: variant.metadata
+    });
+const getPageWithExperiment = async (sdk, path, options = {})=>{
+    const [controlPage, experiment] = await Promise.all([
+        sdk.getPage(path),
+        sdk.getPageExperiment(path)
+    ]);
+    if (!experiment || !controlPage) return {
+        page: controlPage,
+        experiment: experiment ?? null,
+        assignment: null
+    };
+    if ("running" !== experiment.status) return {
+        page: controlPage,
+        experiment,
+        assignment: null
+    };
+    if (sdk.getExperimentPaused) {
+        const paused = await sdk.getExperimentPaused(experiment.experimentId).catch(()=>false);
+        if (paused) return {
+            page: controlPage,
+            experiment,
+            assignment: null
+        };
+    }
+    const forcedVariantId = resolveForcedVariantId(options);
+    const { context, generatedVisitorId } = await resolveVisitorContext(options);
+    let assignment = null;
+    if (forcedVariantId) assignment = forcedAssignment(experiment, forcedVariantId);
+    if (!assignment) assignment = assignVariant(experiment, context);
+    let page = controlPage;
+    if (!assignment.isControl) {
+        const variant = await sdk.getVariantContent(assignment.variantId);
+        if (variant) page = overlayVariant(controlPage, variant);
+        else assignment = {
+            variantId: experiment.controlVariantId,
+            isControl: true,
+            excluded: assignment.excluded,
+            forced: assignment.forced
+        };
+    }
+    const shouldEmit = (options.emitExposure ?? true) && !assignment.excluded && !assignment.forced;
+    if (shouldEmit) {
+        const provider = getAnalyticsProvider(experiment.analytics.provider);
+        if (provider) {
+            const experimentKey = "string" == typeof experiment.analytics.experimentKey ? experiment.analytics.experimentKey : void 0;
+            try {
+                await provider.emitExposure({
+                    experimentId: experiment.experimentId,
+                    experimentKey,
+                    variantId: assignment.variantId,
+                    revisionId: experiment.revisionId,
+                    tenantId: experiment.tenantId,
+                    visitorId: context.visitorId,
+                    pageId: experiment.pageEntryId,
+                    path: experiment.path,
+                    timestamp: new Date().toISOString()
+                });
+            } catch  {}
+        }
+    }
+    const result = {
+        page,
+        experiment,
+        assignment
+    };
+    if (generatedVisitorId) result.cookie = {
+        name: options.cookieName ?? DEFAULT_VISITOR_COOKIE,
+        value: context.visitorId,
+        maxAge: options.cookieMaxAge ?? 31536000
+    };
+    return result;
+};
+export { DEFAULT_VISITOR_COOKIE, FORCED_VARIANT_PARAM, getPageWithExperiment, resolveVisitorContext };
+
+//# sourceMappingURL=render.js.map

package/experiments/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"experiments/render.js","sources":["../../src/experiments/render.ts"],"sourcesContent":["import { nanoid } from \"nanoid\";\nimport type { PublicPage } from \"~/types.js\";\nimport { getHeadersProvider } from \"~/headersProvider.js\";\nimport { assignVariant, forcedAssignment } from \"./bucketing.js\";\nimport { getAnalyticsProvider } from \"./analyticsProvider.js\";\nimport type {\n    ActiveExperiment,\n    DeviceType,\n    VariantAssignment,\n    VariantContent,\n    VisitorContext\n} from \"./types.js\";\n\n/** The cookie that persists the stable visitor id used for deterministic bucketing. */\nexport const DEFAULT_VISITOR_COOKIE = \"wb_ab_vid\";\n\n/** Default query parameter used to force a variant for QA/review. */\nexport const FORCED_VARIANT_PARAM = \"wb-variant\";\n\nconst DEFAULT_GEO_HEADERS = [\n    \"x-vercel-ip-country\",\n    \"cloudfront-viewer-country\",\n    \"cf-ipcountry\",\n    \"x-country-code\"\n];\n\n/** The minimal data surface the render helper needs. ContentSdk satisfies this. */\nexport interface ExperimentSdk {\n    getPage(path: string): Promise<PublicPage | null>;\n    getPageExperiment(path: string): Promise<ActiveExperiment | null>;\n    getVariantContent(variantId: string): Promise<VariantContent | null>;\n    /** Runtime kill-switch check. When omitted, the pause state is not consulted. */\n    getExperimentPaused?(experimentId: string): Promise<boolean>;\n}\n\nexport interface ExperimentCookie {\n    name: string;\n    value: string;\n    maxAge: number;\n}\n\nexport interface GetPageWithExperimentOptions {\n    /** Forced variant id (from the `?wb-variant=` query parameter). Overrides bucketing, never counted. */\n    forcedVariantId?: string;\n    /**\n     * Request query parameters. When provided, the forced variant is read from\n     * `searchParams[FORCED_VARIANT_PARAM]` unless `forcedVariantId` is set explicitly. Convenient\n     * for framework handlers that already have the parsed query (e.g. Next.js `searchParams`).\n     */\n    searchParams?: Record<string, string | string[] | undefined>;\n    /** Explicit visitor id. When omitted, it is read from the cookie or generated. */\n    visitorId?: string;\n    /** Explicit ISO country code. When omitted, it is read from common CDN geo headers. */\n    country?: string;\n    /** Explicit device type. When omitted, it is derived from the user agent. */\n    device?: DeviceType;\n    /** Header names to read the visitor country from, in priority order. */\n    geoHeaders?: string[];\n    /** Bucketing cookie name. Defaults to `wb_ab_vid`. */\n    cookieName?: string;\n    /** Bucketing cookie max age in seconds. Defaults to one year. */\n    cookieMaxAge?: number;\n    /** Set false to skip exposure emission (e.g. when consent has not been granted). */\n    emitExposure?: boolean;\n    /** Visitor id generator. Defaults to nanoid. */\n    generateVisitorId?: () => string;\n}\n\nexport interface ExperimentRenderResult {\n    /** The content to render server-side: the baseline (control) or a variant overlay. */\n    page: PublicPage | null;\n    /** The active experiment, or null when there is none for the path. */\n    experiment: ActiveExperiment | null;\n    /** The visitor's assignment, or null when no experiment applies. */\n    assignment: VariantAssignment | null;\n    /**\n     * Set when the caller should persist the bucketing cookie (i.e. a visitor id was generated\n     * this request). Persisting it in a Route Handler / middleware keeps bucketing stable.\n     */\n    cookie?: ExperimentCookie;\n}\n\nconst readCookie = (cookieHeader: string | null | undefined, name: string): string | undefined => {\n    if (!cookieHeader) {\n        return undefined;\n    }\n    for (const part of cookieHeader.split(\";\")) {\n        const index = part.indexOf(\"=\");\n        if (index === -1) {\n            continue;\n        }\n        const key = part.slice(0, index).trim();\n        if (key === name) {\n            return decodeURIComponent(part.slice(index + 1).trim());\n        }\n    }\n    return undefined;\n};\n\nconst detectDevice = (userAgent: string | null | undefined): DeviceType | undefined => {\n    if (!userAgent) {\n        return undefined;\n    }\n    if (/iPad|Tablet|PlayBook|Silk/i.test(userAgent)) {\n        return \"tablet\";\n    }\n    if (/Mobi|Android.+Mobile|iPhone|iPod|Windows Phone/i.test(userAgent)) {\n        return \"mobile\";\n    }\n    return \"desktop\";\n};\n\n/**\n * Resolve request-time visitor context from request headers/cookies. Never uses a logged-in\n * identity. Returns whether a visitor id was generated, so the caller can persist the cookie.\n */\nexport const resolveVisitorContext = async (\n    options: GetPageWithExperimentOptions = {}\n): Promise<{ context: VisitorContext; generatedVisitorId: boolean }> => {\n    const cookieName = options.cookieName ?? DEFAULT_VISITOR_COOKIE;\n    const generate = options.generateVisitorId ?? (() => nanoid());\n\n    let headers: Headers | undefined;\n    const provider = getHeadersProvider();\n    if (provider) {\n        try {\n            headers = await provider();\n        } catch {\n            headers = undefined;\n        }\n    }\n\n    let visitorId = options.visitorId;\n    let generatedVisitorId = false;\n    if (!visitorId) {\n        visitorId = readCookie(headers?.get(\"cookie\"), cookieName);\n    }\n    if (!visitorId) {\n        visitorId = generate();\n        generatedVisitorId = true;\n    }\n\n    let country = options.country;\n    if (!country && headers) {\n        for (const header of options.geoHeaders ?? DEFAULT_GEO_HEADERS) {\n            const value = headers.get(header);\n            if (value) {\n                country = value.toUpperCase();\n                break;\n            }\n        }\n    }\n\n    const device = options.device ?? detectDevice(headers?.get(\"user-agent\"));\n\n    return { context: { visitorId, country, device }, generatedVisitorId };\n};\n\n/** Forced variant id from an explicit option, falling back to the query parameter. */\nconst resolveForcedVariantId = (options: GetPageWithExperimentOptions): string | undefined => {\n    if (options.forcedVariantId) {\n        return options.forcedVariantId;\n    }\n    const raw = options.searchParams?.[FORCED_VARIANT_PARAM];\n    return Array.isArray(raw) ? raw[0] : raw;\n};\n\nconst overlayVariant = (baseline: PublicPage, variant: VariantContent): PublicPage => {\n    return {\n        ...baseline,\n        properties: variant.properties as PublicPage[\"properties\"],\n        bindings: variant.bindings as PublicPage[\"bindings\"],\n        elements: variant.elements as PublicPage[\"elements\"],\n        extensions: variant.extensions,\n        metadata: variant.metadata\n    };\n};\n\n/**\n * Resolve and render the right page for a visitor, server-side, with no client-side content\n * swap.\n *\n * Caching contract (important — handled here so projects do not reimplement it):\n *  - The baseline (control) is fetched via `getPage(path)` and caches per path.\n *  - The active experiment metadata is fetched via `getPageExperiment(path)` and caches per path.\n *  - A variant's content is fetched via `getVariantContent(variantId)` and caches per variant id.\n * Every request therefore resolves to one of a small, fixed set of cacheable objects keyed by\n * (path) or (variant id) — NEVER by the raw visitor id. Each active variant adds exactly one\n * cacheable object per URL.\n */\nexport const getPageWithExperiment = async (\n    sdk: ExperimentSdk,\n    path: string,\n    options: GetPageWithExperimentOptions = {}\n): Promise<ExperimentRenderResult> => {\n    // Baseline content + active experiment. Both cache per path.\n    const [controlPage, experiment] = await Promise.all([\n        sdk.getPage(path),\n        sdk.getPageExperiment(path)\n    ]);\n\n    if (!experiment || !controlPage) {\n        return { page: controlPage, experiment: experiment ?? null, assignment: null };\n    }\n\n    // Only a running experiment serves variants. `getPageExperiment` already returns the active\n    // one, but guard defensively.\n    if (experiment.status !== \"running\") {\n        return { page: controlPage, experiment, assignment: null };\n    }\n\n    // Kill-switch: a paused experiment instantly reverts to the control. Consulted uncached by the\n    // data provider so it takes effect immediately while page/variant content stays cached.\n    if (sdk.getExperimentPaused) {\n        const paused = await sdk.getExperimentPaused(experiment.experimentId).catch(() => false);\n        if (paused) {\n            return { page: controlPage, experiment, assignment: null };\n        }\n    }\n\n    const forcedVariantId = resolveForcedVariantId(options);\n\n    const { context, generatedVisitorId } = await resolveVisitorContext(options);\n\n    let assignment: VariantAssignment | null = null;\n    if (forcedVariantId) {\n        assignment = forcedAssignment(experiment, forcedVariantId);\n    }\n    if (!assignment) {\n        assignment = assignVariant(experiment, context);\n    }\n\n    let page = controlPage;\n    if (!assignment.isControl) {\n        const variant = await sdk.getVariantContent(assignment.variantId);\n        if (variant) {\n            page = overlayVariant(controlPage, variant);\n        } else {\n            // The variant disappeared (e.g. deleted) — fall back to the control safely.\n            assignment = {\n                variantId: experiment.controlVariantId,\n                isControl: true,\n                excluded: assignment.excluded,\n                forced: assignment.forced\n            };\n        }\n    }\n\n    // Emit a single canonical exposure event through the provider seam. Forced and excluded\n    // assignments are never reported. Analytics failures must never break rendering.\n    const shouldEmit = (options.emitExposure ?? true) && !assignment.excluded && !assignment.forced;\n    if (shouldEmit) {\n        const provider = getAnalyticsProvider(experiment.analytics.provider);\n        if (provider) {\n            const experimentKey =\n                typeof experiment.analytics.experimentKey === \"string\"\n                    ? experiment.analytics.experimentKey\n                    : undefined;\n            try {\n                await provider.emitExposure({\n                    experimentId: experiment.experimentId,\n                    experimentKey,\n                    variantId: assignment.variantId,\n                    revisionId: experiment.revisionId,\n                    tenantId: experiment.tenantId,\n                    visitorId: context.visitorId,\n                    pageId: experiment.pageEntryId,\n                    path: experiment.path,\n                    timestamp: new Date().toISOString()\n                });\n            } catch {\n                // Swallow — exposure measurement must never affect the rendered response.\n            }\n        }\n    }\n\n    const result: ExperimentRenderResult = { page, experiment, assignment };\n\n    if (generatedVisitorId) {\n        result.cookie = {\n            name: options.cookieName ?? DEFAULT_VISITOR_COOKIE,\n            value: context.visitorId,\n            maxAge: options.cookieMaxAge ?? 60 * 60 * 24 * 365\n        };\n    }\n\n    return result;\n};\n"],"names":["DEFAULT_VISITOR_COOKIE","FORCED_VARIANT_PARAM","DEFAULT_GEO_HEADERS","readCookie","cookieHeader","name","part","index","key","decodeURIComponent","detectDevice","userAgent","resolveVisitorContext","options","cookieName","generate","nanoid","headers","provider","getHeadersProvider","undefined","visitorId","generatedVisitorId","country","header","value","device","resolveForcedVariantId","raw","Array","overlayVariant","baseline","variant","getPageWithExperiment","sdk","path","controlPage","experiment","Promise","paused","forcedVariantId","context","assignment","forcedAssignment","assignVariant","page","shouldEmit","getAnalyticsProvider","experimentKey","Date","result"],"mappings":"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"}

package/experiments/types.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The reserved variant id for the control bucket. The control bucket renders the baseline
+ * revision content; it has no Variant object of its own.
+ */
+export declare const CONTROL_VARIANT_ID = "control";
+export type DeviceType = "desktop" | "mobile" | "tablet";
+export interface ExperimentTrafficSplit {
+    control: number;
+    variants: Record<string, number>;
+}
+export interface ExperimentTargeting {
+    trafficPercentage: number;
+    geo?: string[];
+    device?: DeviceType[];
+}
+/**
+ * Provider-agnostic analytics configuration carried by an experiment. Adapters read this and
+ * map it to their own shape. No provider-specific field name appears here.
+ */
+export interface ExperimentAnalyticsConfig {
+    provider: string;
+    [key: string]: unknown;
+}
+export interface ActiveExperimentVariant {
+    variantId: string;
+    name: string;
+}
+/**
+ * A variant's full content snapshot, shaped for rendering. Overlaid onto the baseline page so
+ * the result is a complete, renderable page.
+ */
+export interface VariantContent {
+    id: string;
+    properties: Record<string, any>;
+    bindings: Record<string, any>;
+    elements: Record<string, any>;
+    extensions: Record<string, any>;
+    metadata: Record<string, any>;
+}
+/**
+ * The active experiment for a path as returned by the Website Builder API. This is the only
+ * experiment shape the render path deals with — it is provider-agnostic.
+ */
+export interface ActiveExperiment {
+    experimentId: string;
+    revisionId: string;
+    pageEntryId: string;
+    path: string;
+    status: string;
+    tenantId: string;
+    controlVariantId: string;
+    trafficSplit: ExperimentTrafficSplit;
+    targeting: ExperimentTargeting;
+    analytics: ExperimentAnalyticsConfig;
+    variants: ActiveExperimentVariant[];
+}
+/**
+ * Request-time context used to bucket a visitor. Derived server-side from request headers /
+ * cookies — never from a logged-in identity.
+ */
+export interface VisitorContext {
+    /** A stable visitor id (from the bucketing cookie, or a generated id). */
+    visitorId: string;
+    /** ISO country code, if the CDN/edge provided one. */
+    country?: string;
+    /** Device type, derived from the user agent. */
+    device?: DeviceType;
+}
+export interface VariantAssignment {
+    /** The assigned variant id, or the control variant id. */
+    variantId: string;
+    /** True when the control bucket (baseline revision) was assigned. */
+    isControl: boolean;
+    /**
+     * True when the visitor was not entered into the experiment (targeting or traffic
+     * percentage). The control is served and no exposure is emitted.
+     */
+    excluded: boolean;
+    /** True when a forced-variant query parameter overrode bucketing (QA). Never reported. */
+    forced: boolean;
+}
+/**
+ * The single canonical exposure event. Each analytics provider adapter maps from this into its
+ * own event shape. No PostHog (or other provider) field names may appear here.
+ */
+export interface ExposureEvent {
+    experimentId: string;
+    /** Optional human-readable experiment key for provider mapping (from analytics config). */
+    experimentKey?: string;
+    /** The assigned variant id (the control variant id for the control bucket). */
+    variantId: string;
+    revisionId: string;
+    tenantId: string;
+    /** Stable distinct visitor id. */
+    visitorId: string;
+    pageId: string;
+    path: string;
+    timestamp: string;
+}
+/**
+ * The provider seam. A v2 GA4 adapter is a drop-in implementation of this interface — the data
+ * model, assignment logic, and render path never change.
+ */
+export interface AnalyticsProvider {
+    /** Provider id, matched against an experiment's analytics.provider. */
+    readonly name: string;
+    emitExposure(event: ExposureEvent): Promise<void>;
+}

package/experiments/types.js

@@ -0,0 +1,4 @@
+const CONTROL_VARIANT_ID = "control";
+export { CONTROL_VARIANT_ID };
+
+//# sourceMappingURL=types.js.map

package/experiments/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"experiments/types.js","sources":["../../src/experiments/types.ts"],"sourcesContent":["/**\n * The reserved variant id for the control bucket. The control bucket renders the baseline\n * revision content; it has no Variant object of its own.\n */\nexport const CONTROL_VARIANT_ID = \"control\";\n\nexport type DeviceType = \"desktop\" | \"mobile\" | \"tablet\";\n\nexport interface ExperimentTrafficSplit {\n    control: number;\n    variants: Record<string, number>;\n}\n\nexport interface ExperimentTargeting {\n    trafficPercentage: number;\n    geo?: string[];\n    device?: DeviceType[];\n}\n\n/**\n * Provider-agnostic analytics configuration carried by an experiment. Adapters read this and\n * map it to their own shape. No provider-specific field name appears here.\n */\nexport interface ExperimentAnalyticsConfig {\n    provider: string;\n    [key: string]: unknown;\n}\n\nexport interface ActiveExperimentVariant {\n    variantId: string;\n    name: string;\n}\n\n/**\n * A variant's full content snapshot, shaped for rendering. Overlaid onto the baseline page so\n * the result is a complete, renderable page.\n */\nexport interface VariantContent {\n    id: string;\n    properties: Record<string, any>;\n    bindings: Record<string, any>;\n    elements: Record<string, any>;\n    extensions: Record<string, any>;\n    metadata: Record<string, any>;\n}\n\n/**\n * The active experiment for a path as returned by the Website Builder API. This is the only\n * experiment shape the render path deals with — it is provider-agnostic.\n */\nexport interface ActiveExperiment {\n    experimentId: string;\n    revisionId: string;\n    pageEntryId: string;\n    path: string;\n    status: string;\n    tenantId: string;\n    controlVariantId: string;\n    trafficSplit: ExperimentTrafficSplit;\n    targeting: ExperimentTargeting;\n    analytics: ExperimentAnalyticsConfig;\n    variants: ActiveExperimentVariant[];\n}\n\n/**\n * Request-time context used to bucket a visitor. Derived server-side from request headers /\n * cookies — never from a logged-in identity.\n */\nexport interface VisitorContext {\n    /** A stable visitor id (from the bucketing cookie, or a generated id). */\n    visitorId: string;\n    /** ISO country code, if the CDN/edge provided one. */\n    country?: string;\n    /** Device type, derived from the user agent. */\n    device?: DeviceType;\n}\n\nexport interface VariantAssignment {\n    /** The assigned variant id, or the control variant id. */\n    variantId: string;\n    /** True when the control bucket (baseline revision) was assigned. */\n    isControl: boolean;\n    /**\n     * True when the visitor was not entered into the experiment (targeting or traffic\n     * percentage). The control is served and no exposure is emitted.\n     */\n    excluded: boolean;\n    /** True when a forced-variant query parameter overrode bucketing (QA). Never reported. */\n    forced: boolean;\n}\n\n/**\n * The single canonical exposure event. Each analytics provider adapter maps from this into its\n * own event shape. No PostHog (or other provider) field names may appear here.\n */\nexport interface ExposureEvent {\n    experimentId: string;\n    /** Optional human-readable experiment key for provider mapping (from analytics config). */\n    experimentKey?: string;\n    /** The assigned variant id (the control variant id for the control bucket). */\n    variantId: string;\n    revisionId: string;\n    tenantId: string;\n    /** Stable distinct visitor id. */\n    visitorId: string;\n    pageId: string;\n    path: string;\n    timestamp: string;\n}\n\n/**\n * The provider seam. A v2 GA4 adapter is a drop-in implementation of this interface — the data\n * model, assignment logic, and render path never change.\n */\nexport interface AnalyticsProvider {\n    /** Provider id, matched against an experiment's analytics.provider. */\n    readonly name: string;\n    emitExposure(event: ExposureEvent): Promise<void>;\n}\n"],"names":["CONTROL_VARIANT_ID"],"mappings":"AAIO,MAAMA,qBAAqB"}

package/findMatchingAstNode.js

@@ -1,17 +1,15 @@
-export function findMatchingAstNode(path, ast) {
-  // Remove all array indices, e.g. columns[0].children → columns.children
-  const cleanedPath = path.replace(/\[\d+\]/g, "");
-  const pathParts = cleanedPath.split(".");
-  let nodes = ast;
-  let currentNode;
-  for (const part of pathParts) {
-    currentNode = nodes.find(n => n.name === part);
-    if (!currentNode) {
-      return undefined;
+function findMatchingAstNode(path, ast) {
+    const cleanedPath = path.replace(/\[\d+\]/g, "");
+    const pathParts = cleanedPath.split(".");
+    let nodes = ast;
+    let currentNode;
+    for (const part of pathParts){
+        currentNode = nodes.find((n)=>n.name === part);
+        if (!currentNode) return;
+        nodes = currentNode.children;
     }
-    nodes = currentNode.children;
-  }
-  return currentNode;
+    return currentNode;
 }
+export { findMatchingAstNode };
 
 //# sourceMappingURL=findMatchingAstNode.js.map

package/findMatchingAstNode.js.map

@@ -1 +1 @@
-{"version":3,"names":["findMatchingAstNode","path","ast","cleanedPath","replace","pathParts","split","nodes","currentNode","part","find","n","name","undefined","children"],"sources":["findMatchingAstNode.ts"],"sourcesContent":["import type { InputAstNode } from \"~/ComponentManifestToAstConverter.js\";\n\nexport function findMatchingAstNode(path: string, ast: InputAstNode[]): InputAstNode | undefined {\n    // Remove all array indices, e.g. columns[0].children → columns.children\n    const cleanedPath = path.replace(/\\[\\d+\\]/g, \"\");\n    const pathParts = cleanedPath.split(\".\");\n\n    let nodes = ast;\n    let currentNode: InputAstNode | undefined;\n\n    for (const part of pathParts) {\n        currentNode = nodes.find(n => n.name === part);\n        if (!currentNode) {\n            return undefined;\n        }\n\n        nodes = currentNode.children;\n    }\n\n    return currentNode;\n}\n"],"mappings":"AAEA,OAAO,SAASA,mBAAmBA,CAACC,IAAY,EAAEC,GAAmB,EAA4B;EAC7F;EACA,MAAMC,WAAW,GAAGF,IAAI,CAACG,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;EAChD,MAAMC,SAAS,GAAGF,WAAW,CAACG,KAAK,CAAC,GAAG,CAAC;EAExC,IAAIC,KAAK,GAAGL,GAAG;EACf,IAAIM,WAAqC;EAEzC,KAAK,MAAMC,IAAI,IAAIJ,SAAS,EAAE;IAC1BG,WAAW,GAAGD,KAAK,CAACG,IAAI,CAACC,CAAC,IAAIA,CAAC,CAACC,IAAI,KAAKH,IAAI,CAAC;IAC9C,IAAI,CAACD,WAAW,EAAE;MACd,OAAOK,SAAS;IACpB;IAEAN,KAAK,GAAGC,WAAW,CAACM,QAAQ;EAChC;EAEA,OAAON,WAAW;AACtB","ignoreList":[]}
+{"version":3,"file":"findMatchingAstNode.js","sources":["../src/findMatchingAstNode.ts"],"sourcesContent":["import type { InputAstNode } from \"~/ComponentManifestToAstConverter.js\";\n\nexport function findMatchingAstNode(path: string, ast: InputAstNode[]): InputAstNode | undefined {\n    // Remove all array indices, e.g. columns[0].children → columns.children\n    const cleanedPath = path.replace(/\\[\\d+\\]/g, \"\");\n    const pathParts = cleanedPath.split(\".\");\n\n    let nodes = ast;\n    let currentNode: InputAstNode | undefined;\n\n    for (const part of pathParts) {\n        currentNode = nodes.find(n => n.name === part);\n        if (!currentNode) {\n            return undefined;\n        }\n\n        nodes = currentNode.children;\n    }\n\n    return currentNode;\n}\n"],"names":["findMatchingAstNode","path","ast","cleanedPath","pathParts","nodes","currentNode","part","n"],"mappings":"AAEO,SAASA,oBAAoBC,IAAY,EAAEC,GAAmB;IAEjE,MAAMC,cAAcF,KAAK,OAAO,CAAC,YAAY;IAC7C,MAAMG,YAAYD,YAAY,KAAK,CAAC;IAEpC,IAAIE,QAAQH;IACZ,IAAII;IAEJ,KAAK,MAAMC,QAAQH,UAAW;QAC1BE,cAAcD,MAAM,IAAI,CAACG,CAAAA,IAAKA,EAAE,IAAI,KAAKD;QACzC,IAAI,CAACD,aACD;QAGJD,QAAQC,YAAY,QAAQ;IAChC;IAEA,OAAOA;AACX"}

package/generateElementId.d.ts

@@ -1 +1 @@
-export declare const generateElementId: (size?: number | undefined) => string;
+export declare const generateElementId: (size?: number) => string;

package/generateElementId.js

@@ -1,7 +1,7 @@
 import { customAlphabet } from "nanoid";
-// @ts-expect-error
 import { lowercase, numbers } from "nanoid-dictionary";
 const DEFAULT_SIZE = 21;
-export const generateElementId = customAlphabet(`${lowercase}${numbers}`, DEFAULT_SIZE);
+const generateElementId = customAlphabet(`${lowercase}${numbers}`, DEFAULT_SIZE);
+export { generateElementId };
 
 //# sourceMappingURL=generateElementId.js.map

package/generateElementId.js.map

@@ -1 +1 @@
-{"version":3,"names":["customAlphabet","lowercase","numbers","DEFAULT_SIZE","generateElementId"],"sources":["generateElementId.ts"],"sourcesContent":["import { customAlphabet } from \"nanoid\";\n// @ts-expect-error\nimport { lowercase, numbers } from \"nanoid-dictionary\";\n\nconst DEFAULT_SIZE = 21;\n\nexport const generateElementId = customAlphabet(`${lowercase}${numbers}`, DEFAULT_SIZE);\n"],"mappings":"AAAA,SAASA,cAAc,QAAQ,QAAQ;AACvC;AACA,SAASC,SAAS,EAAEC,OAAO,QAAQ,mBAAmB;AAEtD,MAAMC,YAAY,GAAG,EAAE;AAEvB,OAAO,MAAMC,iBAAiB,GAAGJ,cAAc,CAAC,GAAGC,SAAS,GAAGC,OAAO,EAAE,EAAEC,YAAY,CAAC","ignoreList":[]}
+{"version":3,"file":"generateElementId.js","sources":["../src/generateElementId.ts"],"sourcesContent":["import { customAlphabet } from \"nanoid\";\nimport { lowercase, numbers } from \"nanoid-dictionary\";\n\nconst DEFAULT_SIZE = 21;\n\nexport const generateElementId = customAlphabet(`${lowercase}${numbers}`, DEFAULT_SIZE);\n"],"names":["DEFAULT_SIZE","generateElementId","customAlphabet","lowercase","numbers"],"mappings":";;AAGA,MAAMA,eAAe;AAEd,MAAMC,oBAAoBC,eAAe,GAAGC,YAAYC,SAAS,EAAEJ"}

package/headersProvider.js

@@ -1,7 +1,8 @@
 let headersProvider;
-export const setHeadersProvider = provider => {
-  headersProvider = provider;
+const setHeadersProvider = (provider)=>{
+    headersProvider = provider;
 };
-export const getHeadersProvider = () => headersProvider;
+const getHeadersProvider = ()=>headersProvider;
+export { getHeadersProvider, setHeadersProvider };
 
 //# sourceMappingURL=headersProvider.js.map

package/headersProvider.js.map

@@ -1 +1 @@
-{"version":3,"names":["headersProvider","setHeadersProvider","provider","getHeadersProvider"],"sources":["headersProvider.ts"],"sourcesContent":["type HeadersProvider = () => Promise<Headers>;\n\nlet headersProvider: HeadersProvider;\n\nexport const setHeadersProvider = (provider: HeadersProvider) => {\n    headersProvider = provider;\n};\n\nexport const getHeadersProvider = () => headersProvider;\n"],"mappings":"AAEA,IAAIA,eAAgC;AAEpC,OAAO,MAAMC,kBAAkB,GAAIC,QAAyB,IAAK;EAC7DF,eAAe,GAAGE,QAAQ;AAC9B,CAAC;AAED,OAAO,MAAMC,kBAAkB,GAAGA,CAAA,KAAMH,eAAe","ignoreList":[]}
+{"version":3,"file":"headersProvider.js","sources":["../src/headersProvider.ts"],"sourcesContent":["type HeadersProvider = () => Promise<Headers>;\n\nlet headersProvider: HeadersProvider;\n\nexport const setHeadersProvider = (provider: HeadersProvider) => {\n    headersProvider = provider;\n};\n\nexport const getHeadersProvider = () => headersProvider;\n"],"names":["headersProvider","setHeadersProvider","provider","getHeadersProvider"],"mappings":"AAEA,IAAIA;AAEG,MAAMC,qBAAqB,CAACC;IAC/BF,kBAAkBE;AACtB;AAEO,MAAMC,qBAAqB,IAAMH"}

package/image/geometry.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Pure geometry core for crop + focal point rendering.
+ *
+ * This module is the single source of truth shared by:
+ *  - the Admin editor previews (square / 4:3 / 16:9),
+ *  - the Next.js render helper (`getImageProps` / `<Image>`),
+ *  - and any future URL-transform loader (`?rect=…`).
+ *
+ * Keeping the math here guarantees that what an editor previews is exactly what
+ * a visitor sees. Everything is framework-agnostic and side-effect free.
+ */
+import type { AssetCrop, AssetImage } from "@webiny/sdk";
+import type { AspectRatioInput } from "./types.js";
+/** A rectangle in normalized (0..1) coordinates of the original image. */
+export interface NormalizedRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * CSS needed to render an image cropped to a target aspect ratio while honoring
+ * both the crop rectangle and the focal point — without any server-side processing.
+ *
+ * `objectPosition` is the simpler, focal-point-only path (apply to an `object-fit:
+ * cover` image). `container` + `image` is the accurate path that also honors the
+ * crop rectangle via an overflow-clipped wrapper.
+ */
+export interface ImageRenderData {
+    rect: NormalizedRect;
+    objectPosition: string;
+    container: {
+        position: "relative";
+        width: "100%";
+        aspectRatio: string;
+        overflow: "hidden";
+    };
+    image: {
+        position: "absolute";
+        width: string;
+        height: string;
+        left: string;
+        top: string;
+        maxWidth: "none";
+        objectFit: "cover";
+        objectPosition: string;
+    };
+    intrinsicWidth: number;
+    intrinsicHeight: number;
+}
+export declare function resolveAssetImage(override?: AssetImage | null, assetDefault?: AssetImage | null): AssetImage;
+export declare function getCropRect(crop?: AssetCrop | null): NormalizedRect;
+export declare function getVisibleRect(image: AssetImage, aspectRatio?: AspectRatioInput): NormalizedRect;
+export declare function getImageRenderData(image: AssetImage, aspectRatio?: AspectRatioInput): ImageRenderData;

package/image/geometry.js

@@ -0,0 +1,112 @@
+const clamp = (value, min = 0, max = 1)=>{
+    if (Number.isNaN(value)) return min;
+    return Math.min(max, Math.max(min, value));
+};
+const round = (n)=>Math.round(1000 * n) / 1000;
+const DEFAULT_CROP = {
+    top: 0,
+    left: 0,
+    bottom: 0,
+    right: 0
+};
+const DEFAULT_FOCAL_POINT = {
+    x: 0.5,
+    y: 0.5
+};
+function resolveAssetImage(override, assetDefault) {
+    return {
+        crop: override?.crop ?? assetDefault?.crop,
+        focalPoint: override?.focalPoint ?? assetDefault?.focalPoint,
+        alt: override?.alt ?? assetDefault?.alt,
+        caption: override?.caption ?? assetDefault?.caption
+    };
+}
+function getCropRect(crop) {
+    const top = clamp(crop?.top ?? DEFAULT_CROP.top);
+    const left = clamp(crop?.left ?? DEFAULT_CROP.left);
+    const bottom = clamp(crop?.bottom ?? DEFAULT_CROP.bottom);
+    const right = clamp(crop?.right ?? DEFAULT_CROP.right);
+    const width = Math.max(0, 1 - left - right);
+    const height = Math.max(0, 1 - top - bottom);
+    return {
+        x: left,
+        y: top,
+        width,
+        height
+    };
+}
+const resolveAspectRatio = (aspectRatio)=>{
+    if ("number" == typeof aspectRatio) return aspectRatio > 0 ? aspectRatio : 1;
+    const { width, height } = aspectRatio;
+    return width > 0 && height > 0 ? width / height : 1;
+};
+const getFocalCenter = (fp)=>({
+        x: clamp(fp?.x ?? DEFAULT_FOCAL_POINT.x),
+        y: clamp(fp?.y ?? DEFAULT_FOCAL_POINT.y)
+    });
+function getVisibleRect(image, aspectRatio) {
+    const cropRect = getCropRect(image.crop);
+    if (void 0 === aspectRatio || cropRect.width <= 0 || cropRect.height <= 0) return cropRect;
+    const iw = (image.width ?? 0) > 0 ? image.width : 1;
+    const ih = (image.height ?? 0) > 0 ? image.height : 1;
+    const targetAR = resolveAspectRatio(aspectRatio);
+    const cropWpx = cropRect.width * iw;
+    const cropHpx = cropRect.height * ih;
+    const cropAR = cropWpx / cropHpx;
+    let finalWpx;
+    let finalHpx;
+    if (targetAR > cropAR) {
+        finalWpx = cropWpx;
+        finalHpx = cropWpx / targetAR;
+    } else {
+        finalHpx = cropHpx;
+        finalWpx = cropHpx * targetAR;
+    }
+    const finalW = finalWpx / iw;
+    const finalH = finalHpx / ih;
+    const center = getFocalCenter(image.focalPoint);
+    const maxX = cropRect.x + cropRect.width - finalW;
+    const maxY = cropRect.y + cropRect.height - finalH;
+    const x = clamp(center.x - finalW / 2, cropRect.x, Math.max(cropRect.x, maxX));
+    const y = clamp(center.y - finalH / 2, cropRect.y, Math.max(cropRect.y, maxY));
+    return {
+        x,
+        y,
+        width: finalW,
+        height: finalH
+    };
+}
+function getImageRenderData(image, aspectRatio) {
+    const rect = getVisibleRect(image, aspectRatio);
+    const center = getFocalCenter(image.focalPoint);
+    const safeW = rect.width > 0 ? rect.width : 1;
+    const safeH = rect.height > 0 ? rect.height : 1;
+    const iw = image.width || 1;
+    const ih = image.height || 1;
+    const boxAspectRatio = void 0 !== aspectRatio ? resolveAspectRatio(aspectRatio) : rect.width * iw / (rect.height * ih);
+    return {
+        rect,
+        objectPosition: `${round(100 * center.x)}% ${round(100 * center.y)}%`,
+        container: {
+            position: "relative",
+            width: "100%",
+            aspectRatio: `${round(boxAspectRatio)}`,
+            overflow: "hidden"
+        },
+        image: {
+            position: "absolute",
+            width: `${round(100 / safeW)}%`,
+            height: `${round(100 / safeH)}%`,
+            left: `${round(100 * -(rect.x / safeW))}%`,
+            top: `${round(100 * -(rect.y / safeH))}%`,
+            maxWidth: "none",
+            objectFit: "cover",
+            objectPosition: `${round(100 * center.x)}% ${round(100 * center.y)}%`
+        },
+        intrinsicWidth: iw,
+        intrinsicHeight: ih
+    };
+}
+export { getCropRect, getImageRenderData, getVisibleRect, resolveAssetImage };
+
+//# sourceMappingURL=geometry.js.map

package/image/geometry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image/geometry.js","sources":["../../src/image/geometry.ts"],"sourcesContent":["/**\n * Pure geometry core for crop + focal point rendering.\n *\n * This module is the single source of truth shared by:\n *  - the Admin editor previews (square / 4:3 / 16:9),\n *  - the Next.js render helper (`getImageProps` / `<Image>`),\n *  - and any future URL-transform loader (`?rect=…`).\n *\n * Keeping the math here guarantees that what an editor previews is exactly what\n * a visitor sees. Everything is framework-agnostic and side-effect free.\n */\nimport type { AssetCrop, AssetFocalPoint, AssetImage } from \"@webiny/sdk\";\nimport type { AspectRatioInput } from \"./types.js\";\n\n/** A rectangle in normalized (0..1) coordinates of the original image. */\nexport interface NormalizedRect {\n    x: number;\n    y: number;\n    width: number;\n    height: number;\n}\n\n/**\n * CSS needed to render an image cropped to a target aspect ratio while honoring\n * both the crop rectangle and the focal point — without any server-side processing.\n *\n * `objectPosition` is the simpler, focal-point-only path (apply to an `object-fit:\n * cover` image). `container` + `image` is the accurate path that also honors the\n * crop rectangle via an overflow-clipped wrapper.\n */\nexport interface ImageRenderData {\n    rect: NormalizedRect;\n    objectPosition: string;\n    container: {\n        position: \"relative\";\n        width: \"100%\";\n        aspectRatio: string;\n        overflow: \"hidden\";\n    };\n    image: {\n        position: \"absolute\";\n        width: string;\n        height: string;\n        left: string;\n        top: string;\n        maxWidth: \"none\";\n        objectFit: \"cover\";\n        objectPosition: string;\n    };\n    intrinsicWidth: number;\n    intrinsicHeight: number;\n}\n\nconst clamp = (value: number, min = 0, max = 1): number => {\n    if (Number.isNaN(value)) {\n        return min;\n    }\n    return Math.min(max, Math.max(min, value));\n};\n\nconst round = (n: number): number => Math.round(n * 1000) / 1000;\n\nconst DEFAULT_CROP: AssetCrop = { top: 0, left: 0, bottom: 0, right: 0 };\nconst DEFAULT_FOCAL_POINT: AssetFocalPoint = { x: 0.5, y: 0.5 };\n\nexport function resolveAssetImage(\n    override?: AssetImage | null,\n    assetDefault?: AssetImage | null\n): AssetImage {\n    return {\n        crop: override?.crop ?? assetDefault?.crop,\n        focalPoint: override?.focalPoint ?? assetDefault?.focalPoint,\n        alt: override?.alt ?? assetDefault?.alt,\n        caption: override?.caption ?? assetDefault?.caption\n    };\n}\n\nexport function getCropRect(crop?: AssetCrop | null): NormalizedRect {\n    const top = clamp(crop?.top ?? DEFAULT_CROP.top);\n    const left = clamp(crop?.left ?? DEFAULT_CROP.left);\n    const bottom = clamp(crop?.bottom ?? DEFAULT_CROP.bottom);\n    const right = clamp(crop?.right ?? DEFAULT_CROP.right);\n\n    const width = Math.max(0, 1 - left - right);\n    const height = Math.max(0, 1 - top - bottom);\n\n    return { x: left, y: top, width, height };\n}\n\nconst resolveAspectRatio = (aspectRatio: AspectRatioInput): number => {\n    if (typeof aspectRatio === \"number\") {\n        return aspectRatio > 0 ? aspectRatio : 1;\n    }\n    const { width, height } = aspectRatio;\n    return width > 0 && height > 0 ? width / height : 1;\n};\n\nconst getFocalCenter = (fp?: AssetFocalPoint | null): { x: number; y: number } => ({\n    x: clamp(fp?.x ?? DEFAULT_FOCAL_POINT.x),\n    y: clamp(fp?.y ?? DEFAULT_FOCAL_POINT.y)\n});\n\nexport function getVisibleRect(image: AssetImage, aspectRatio?: AspectRatioInput): NormalizedRect {\n    const cropRect = getCropRect(image.crop);\n\n    if (aspectRatio === undefined || cropRect.width <= 0 || cropRect.height <= 0) {\n        return cropRect;\n    }\n\n    const iw = (image.width ?? 0) > 0 ? image.width! : 1;\n    const ih = (image.height ?? 0) > 0 ? image.height! : 1;\n    const targetAR = resolveAspectRatio(aspectRatio);\n\n    const cropWpx = cropRect.width * iw;\n    const cropHpx = cropRect.height * ih;\n    const cropAR = cropWpx / cropHpx;\n\n    let finalWpx: number;\n    let finalHpx: number;\n    if (targetAR > cropAR) {\n        finalWpx = cropWpx;\n        finalHpx = cropWpx / targetAR;\n    } else {\n        finalHpx = cropHpx;\n        finalWpx = cropHpx * targetAR;\n    }\n\n    const finalW = finalWpx / iw;\n    const finalH = finalHpx / ih;\n\n    const center = getFocalCenter(image.focalPoint);\n    const maxX = cropRect.x + cropRect.width - finalW;\n    const maxY = cropRect.y + cropRect.height - finalH;\n    const x = clamp(center.x - finalW / 2, cropRect.x, Math.max(cropRect.x, maxX));\n    const y = clamp(center.y - finalH / 2, cropRect.y, Math.max(cropRect.y, maxY));\n\n    return { x, y, width: finalW, height: finalH };\n}\n\nexport function getImageRenderData(\n    image: AssetImage,\n    aspectRatio?: AspectRatioInput\n): ImageRenderData {\n    const rect = getVisibleRect(image, aspectRatio);\n    const center = getFocalCenter(image.focalPoint);\n\n    const safeW = rect.width > 0 ? rect.width : 1;\n    const safeH = rect.height > 0 ? rect.height : 1;\n\n    const iw = image.width || 1;\n    const ih = image.height || 1;\n\n    const boxAspectRatio =\n        aspectRatio !== undefined\n            ? resolveAspectRatio(aspectRatio)\n            : (rect.width * iw) / (rect.height * ih);\n\n    return {\n        rect,\n        objectPosition: `${round(center.x * 100)}% ${round(center.y * 100)}%`,\n        container: {\n            position: \"relative\",\n            width: \"100%\",\n            aspectRatio: `${round(boxAspectRatio)}`,\n            overflow: \"hidden\"\n        },\n        image: {\n            position: \"absolute\",\n            width: `${round(100 / safeW)}%`,\n            height: `${round(100 / safeH)}%`,\n            left: `${round(-(rect.x / safeW) * 100)}%`,\n            top: `${round(-(rect.y / safeH) * 100)}%`,\n            maxWidth: \"none\",\n            objectFit: \"cover\",\n            objectPosition: `${round(center.x * 100)}% ${round(center.y * 100)}%`\n        },\n        intrinsicWidth: iw,\n        intrinsicHeight: ih\n    };\n}\n"],"names":["clamp","value","min","max","Number","Math","round","n","DEFAULT_CROP","DEFAULT_FOCAL_POINT","resolveAssetImage","override","assetDefault","getCropRect","crop","top","left","bottom","right","width","height","resolveAspectRatio","aspectRatio","getFocalCenter","fp","getVisibleRect","image","cropRect","undefined","iw","ih","targetAR","cropWpx","cropHpx","cropAR","finalWpx","finalHpx","finalW","finalH","center","maxX","maxY","x","y","getImageRenderData","rect","safeW","safeH","boxAspectRatio"],"mappings":"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"}

package/image/geometry.test.d.ts

@@ -0,0 +1 @@
+export {};