@webiny/website-builder-sdk 0.0.0-unstable.7be00a75a9 → 0.0.0-unstable.7c2def32a7

package/defaultBreakpoints.js

@@ -2,21 +2,41 @@ const defaultBreakpoints = {
     desktop: {
         title: "Desktop",
         description: "Desktop styles apply at all breakpoints, unless they're edited at a lower breakpoint. Start your styling here.",
-        icon: '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path d="M20 18c1.1 0 1.99-.9 1.99-2L22 5c0-1.1-.9-2-2-2H4c-1.1 0-2 .9-2 2v11c0 1.1.9 2 2 2H0c0 1.1.9 2 2 2h20c1.1 0 2-.9 2-2h-4zM4 5h16v11H4V5zm8 14c-.55 0-1-.45-1-1s.45-1 1-1 1 .45 1 1-.45 1-1 1z"/></svg>',
+        icon: `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16" fill="none">
+  <path d="M13.3333 12C14.0667 12 14.6667 11.4 14.6667 10.6666V3.99996C14.6667 3.26663 14.0667 2.66663 13.3333 2.66663H2.66667C1.93333 2.66663 1.33333 3.26663 1.33333 3.99996V10.6666C1.33333 11.4 1.93333 12 2.66667 12H0V13.3333H16V12H13.3333ZM2.66667 3.99996H13.3333V10.6666H2.66667V3.99996Z" fill="#59626D"/>
+</svg>`,
         minWidth: 0,
         maxWidth: 4000
     },
     tablet: {
         title: "Tablet",
         description: "Styles added here will apply at 991px and below, unless they're edited at a smaller breakpoint.",
-        icon: '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path d="M18.5 0h-14A2.5 2.5 0 0 0 2 2.5v19A2.5 2.5 0 0 0 4.5 24h14a2.5 2.5 0 0 0 2.5-2.5v-19A2.5 2.5 0 0 0 18.5 0zm-7 23c-.83 0-1.5-.67-1.5-1.5s.67-1.5 1.5-1.5 1.5.67 1.5 1.5-.67 1.5-1.5 1.5zm7.5-4H4V3h15v16z"/></svg>',
+        icon: `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16" fill="none">
+  <g clip-path="url(#clip0_6424_8826)">
+    <path d="M12.666 0H3.33268C2.41268 0 1.66602 0.746667 1.66602 1.66667V14.3333C1.66602 15.2533 2.41268 16 3.33268 16H12.666C13.586 16 14.3327 15.2533 14.3327 14.3333V1.66667C14.3327 0.746667 13.586 0 12.666 0ZM7.99935 15.3333C7.44602 15.3333 6.99935 14.8867 6.99935 14.3333C6.99935 13.78 7.44602 13.3333 7.99935 13.3333C8.55268 13.3333 8.99935 13.78 8.99935 14.3333C8.99935 14.8867 8.55268 15.3333 7.99935 15.3333ZM12.9993 12.6667H2.99935V2H12.9993V12.6667Z" fill="#9DA4B0"/>
+  </g>
+  <defs>
+    <clipPath id="clip0_6424_8826">
+      <rect width="16" height="16" fill="white"/>
+    </clipPath>
+  </defs>
+</svg>`,
         minWidth: 0,
         maxWidth: 991
     },
     mobile: {
         title: "Mobile",
         description: "Styles added here will apply at 430px and below.",
-        icon: '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path d="M15.5 1h-8A2.5 2.5 0 0 0 5 3.5v17A2.5 2.5 0 0 0 7.5 23h8a2.5 2.5 0 0 0 2.5-2.5v-17A2.5 2.5 0 0 0 15.5 1zm-4 21c-.83 0-1.5-.67-1.5-1.5s.67-1.5 1.5-1.5 1.5.67 1.5 1.5-.67 1.5-1.5 1.5zm4.5-4H7V4h9v14z"/></svg>',
+        icon: `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16" fill="none">
+  <g clip-path="url(#clip0_6405_34405)">
+    <path d="M11.333 0.673293L4.66634 0.666626C3.93301 0.666626 3.33301 1.26663 3.33301 1.99996V14C3.33301 14.7333 3.93301 15.3333 4.66634 15.3333H11.333C12.0663 15.3333 12.6663 14.7333 12.6663 14V1.99996C12.6663 1.26663 12.0663 0.673293 11.333 0.673293ZM11.333 12.6666H4.66634V3.33329H11.333V12.6666Z" fill="#9DA4B0"/>
+  </g>
+  <defs>
+    <clipPath id="clip0_6405_34405">
+      <rect width="16" height="16" fill="white"/>
+    </clipPath>
+  </defs>
+</svg>`,
         minWidth: 0,
         maxWidth: 430
     }

package/defaultBreakpoints.js.map

@@ -1 +1 @@
-{"version":3,"file":"defaultBreakpoints.js","sources":["../src/defaultBreakpoints.ts"],"sourcesContent":["import type { WebsiteBuilderThemeInput } from \"~/types/WebsiteBuilderTheme.js\";\n\nexport const defaultBreakpoints: NonNullable<WebsiteBuilderThemeInput[\"breakpoints\"]> = {\n    desktop: {\n        title: \"Desktop\",\n        description: `Desktop styles apply at all breakpoints, unless they're edited at a lower breakpoint. Start your styling here.`,\n        icon: `<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"24\" height=\"24\" viewBox=\"0 0 24 24\"><path d=\"M20 18c1.1 0 1.99-.9 1.99-2L22 5c0-1.1-.9-2-2-2H4c-1.1 0-2 .9-2 2v11c0 1.1.9 2 2 2H0c0 1.1.9 2 2 2h20c1.1 0 2-.9 2-2h-4zM4 5h16v11H4V5zm8 14c-.55 0-1-.45-1-1s.45-1 1-1 1 .45 1 1-.45 1-1 1z\"/></svg>`,\n        minWidth: 0,\n        maxWidth: 4000\n    },\n    tablet: {\n        title: \"Tablet\",\n        description: `Styles added here will apply at 991px and below, unless they're edited at a smaller breakpoint.`,\n        icon: `<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"24\" height=\"24\" viewBox=\"0 0 24 24\"><path d=\"M18.5 0h-14A2.5 2.5 0 0 0 2 2.5v19A2.5 2.5 0 0 0 4.5 24h14a2.5 2.5 0 0 0 2.5-2.5v-19A2.5 2.5 0 0 0 18.5 0zm-7 23c-.83 0-1.5-.67-1.5-1.5s.67-1.5 1.5-1.5 1.5.67 1.5 1.5-.67 1.5-1.5 1.5zm7.5-4H4V3h15v16z\"/></svg>`,\n        minWidth: 0,\n        maxWidth: 991\n    },\n    mobile: {\n        title: \"Mobile\",\n        description: `Styles added here will apply at 430px and below.`,\n        icon: `<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"24\" height=\"24\" viewBox=\"0 0 24 24\"><path d=\"M15.5 1h-8A2.5 2.5 0 0 0 5 3.5v17A2.5 2.5 0 0 0 7.5 23h8a2.5 2.5 0 0 0 2.5-2.5v-17A2.5 2.5 0 0 0 15.5 1zm-4 21c-.83 0-1.5-.67-1.5-1.5s.67-1.5 1.5-1.5 1.5.67 1.5 1.5-.67 1.5-1.5 1.5zm4.5-4H7V4h9v14z\"/></svg>`,\n        minWidth: 0,\n        maxWidth: 430\n    }\n};\n"],"names":["defaultBreakpoints"],"mappings":"AAEO,MAAMA,qBAA2E;IACpF,SAAS;QACL,OAAO;QACP,aAAa;QACb,MAAM;QACN,UAAU;QACV,UAAU;IACd;IACA,QAAQ;QACJ,OAAO;QACP,aAAa;QACb,MAAM;QACN,UAAU;QACV,UAAU;IACd;IACA,QAAQ;QACJ,OAAO;QACP,aAAa;QACb,MAAM;QACN,UAAU;QACV,UAAU;IACd;AACJ"}
+{"version":3,"file":"defaultBreakpoints.js","sources":["../src/defaultBreakpoints.ts"],"sourcesContent":["import type { WebsiteBuilderThemeInput } from \"~/types/WebsiteBuilderTheme.js\";\n\nexport const defaultBreakpoints: NonNullable<WebsiteBuilderThemeInput[\"breakpoints\"]> = {\n    desktop: {\n        title: \"Desktop\",\n        description: `Desktop styles apply at all breakpoints, unless they're edited at a lower breakpoint. Start your styling here.`,\n        icon: `<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"16\" height=\"16\" viewBox=\"0 0 16 16\" fill=\"none\">\n  <path d=\"M13.3333 12C14.0667 12 14.6667 11.4 14.6667 10.6666V3.99996C14.6667 3.26663 14.0667 2.66663 13.3333 2.66663H2.66667C1.93333 2.66663 1.33333 3.26663 1.33333 3.99996V10.6666C1.33333 11.4 1.93333 12 2.66667 12H0V13.3333H16V12H13.3333ZM2.66667 3.99996H13.3333V10.6666H2.66667V3.99996Z\" fill=\"#59626D\"/>\n</svg>`,\n        minWidth: 0,\n        maxWidth: 4000\n    },\n    tablet: {\n        title: \"Tablet\",\n        description: `Styles added here will apply at 991px and below, unless they're edited at a smaller breakpoint.`,\n        icon: `<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"16\" height=\"16\" viewBox=\"0 0 16 16\" fill=\"none\">\n  <g clip-path=\"url(#clip0_6424_8826)\">\n    <path d=\"M12.666 0H3.33268C2.41268 0 1.66602 0.746667 1.66602 1.66667V14.3333C1.66602 15.2533 2.41268 16 3.33268 16H12.666C13.586 16 14.3327 15.2533 14.3327 14.3333V1.66667C14.3327 0.746667 13.586 0 12.666 0ZM7.99935 15.3333C7.44602 15.3333 6.99935 14.8867 6.99935 14.3333C6.99935 13.78 7.44602 13.3333 7.99935 13.3333C8.55268 13.3333 8.99935 13.78 8.99935 14.3333C8.99935 14.8867 8.55268 15.3333 7.99935 15.3333ZM12.9993 12.6667H2.99935V2H12.9993V12.6667Z\" fill=\"#9DA4B0\"/>\n  </g>\n  <defs>\n    <clipPath id=\"clip0_6424_8826\">\n      <rect width=\"16\" height=\"16\" fill=\"white\"/>\n    </clipPath>\n  </defs>\n</svg>`,\n        minWidth: 0,\n        maxWidth: 991\n    },\n    mobile: {\n        title: \"Mobile\",\n        description: `Styles added here will apply at 430px and below.`,\n        icon: `<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"16\" height=\"16\" viewBox=\"0 0 16 16\" fill=\"none\">\n  <g clip-path=\"url(#clip0_6405_34405)\">\n    <path d=\"M11.333 0.673293L4.66634 0.666626C3.93301 0.666626 3.33301 1.26663 3.33301 1.99996V14C3.33301 14.7333 3.93301 15.3333 4.66634 15.3333H11.333C12.0663 15.3333 12.6663 14.7333 12.6663 14V1.99996C12.6663 1.26663 12.0663 0.673293 11.333 0.673293ZM11.333 12.6666H4.66634V3.33329H11.333V12.6666Z\" fill=\"#9DA4B0\"/>\n  </g>\n  <defs>\n    <clipPath id=\"clip0_6405_34405\">\n      <rect width=\"16\" height=\"16\" fill=\"white\"/>\n    </clipPath>\n  </defs>\n</svg>`,\n        minWidth: 0,\n        maxWidth: 430\n    }\n};\n"],"names":["defaultBreakpoints"],"mappings":"AAEO,MAAMA,qBAA2E;IACpF,SAAS;QACL,OAAO;QACP,aAAa;QACb,MAAM,CAAC;;MAET,CAAC;QACC,UAAU;QACV,UAAU;IACd;IACA,QAAQ;QACJ,OAAO;QACP,aAAa;QACb,MAAM,CAAC;;;;;;;;;MAST,CAAC;QACC,UAAU;QACV,UAAU;IACd;IACA,QAAQ;QACJ,OAAO;QACP,aAAa;QACb,MAAM,CAAC;;;;;;;;;MAST,CAAC;QACC,UAAU;QACV,UAAU;IACd;AACJ"}

package/experiments/PostHogAnalyticsProvider.d.ts

@@ -0,0 +1,31 @@
+import type { AnalyticsProvider, ExposureEvent } from "./types.js";
+/**
+ * The minimal shape of a PostHog client (server-side `posthog-node` or browser `posthog-js`).
+ * The project supplies its own client so this package stays dependency-free and framework
+ * agnostic — no PostHog package is bundled into the SDK.
+ */
+export interface PostHogClientLike {
+    capture(params: {
+        distinctId: string;
+        event: string;
+        properties?: Record<string, any>;
+    }): void | Promise<void>;
+}
+export interface PostHogAnalyticsProviderOptions {
+    /** Event name to emit. Defaults to "$experiment_exposure". */
+    exposureEventName?: string;
+}
+/**
+ * Maps the canonical {@link ExposureEvent} onto a PostHog capture call. PostHog attributes
+ * experiment results from the `$feature/<experimentKey>` property carried on the exposure
+ * event (and, project-side, on subsequent metric events) — no native PostHog feature flag is
+ * required. This is the ONLY place PostHog-specific field names exist; they never reach the
+ * data model, the assignment logic, or the render path.
+ */
+export declare class PostHogAnalyticsProvider implements AnalyticsProvider {
+    private client;
+    private options;
+    readonly name = "posthog";
+    constructor(client: PostHogClientLike, options?: PostHogAnalyticsProviderOptions);
+    emitExposure(event: ExposureEvent): Promise<void>;
+}

package/experiments/PostHogAnalyticsProvider.js

@@ -0,0 +1,28 @@
+class PostHogAnalyticsProvider {
+    constructor(client, options = {}){
+        this.client = client;
+        this.options = options;
+        this.name = "posthog";
+    }
+    async emitExposure(event) {
+        const featureKey = event.experimentKey ?? event.experimentId;
+        await this.client.capture({
+            distinctId: event.visitorId,
+            event: this.options.exposureEventName ?? "$experiment_exposure",
+            properties: {
+                [`$feature/${featureKey}`]: event.variantId,
+                experiment_id: event.experimentId,
+                variant_id: event.variantId,
+                revision_id: event.revisionId,
+                tenant_id: event.tenantId,
+                page_id: event.pageId,
+                path: event.path,
+                $current_url: event.path,
+                timestamp: event.timestamp
+            }
+        });
+    }
+}
+export { PostHogAnalyticsProvider };
+
+//# sourceMappingURL=PostHogAnalyticsProvider.js.map

package/experiments/PostHogAnalyticsProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"experiments/PostHogAnalyticsProvider.js","sources":["../../src/experiments/PostHogAnalyticsProvider.ts"],"sourcesContent":["import type { AnalyticsProvider, ExposureEvent } from \"./types.js\";\n\n/**\n * The minimal shape of a PostHog client (server-side `posthog-node` or browser `posthog-js`).\n * The project supplies its own client so this package stays dependency-free and framework\n * agnostic — no PostHog package is bundled into the SDK.\n */\nexport interface PostHogClientLike {\n    capture(params: {\n        distinctId: string;\n        event: string;\n        properties?: Record<string, any>;\n    }): void | Promise<void>;\n}\n\nexport interface PostHogAnalyticsProviderOptions {\n    /** Event name to emit. Defaults to \"$experiment_exposure\". */\n    exposureEventName?: string;\n}\n\n/**\n * Maps the canonical {@link ExposureEvent} onto a PostHog capture call. PostHog attributes\n * experiment results from the `$feature/<experimentKey>` property carried on the exposure\n * event (and, project-side, on subsequent metric events) — no native PostHog feature flag is\n * required. This is the ONLY place PostHog-specific field names exist; they never reach the\n * data model, the assignment logic, or the render path.\n */\nexport class PostHogAnalyticsProvider implements AnalyticsProvider {\n    public readonly name = \"posthog\";\n\n    constructor(\n        private client: PostHogClientLike,\n        private options: PostHogAnalyticsProviderOptions = {}\n    ) {}\n\n    async emitExposure(event: ExposureEvent): Promise<void> {\n        const featureKey = event.experimentKey ?? event.experimentId;\n\n        await this.client.capture({\n            distinctId: event.visitorId,\n            event: this.options.exposureEventName ?? \"$experiment_exposure\",\n            properties: {\n                // PostHog reads this property to attribute exposures and metrics to a variant.\n                [`$feature/${featureKey}`]: event.variantId,\n                experiment_id: event.experimentId,\n                variant_id: event.variantId,\n                revision_id: event.revisionId,\n                tenant_id: event.tenantId,\n                page_id: event.pageId,\n                path: event.path,\n                $current_url: event.path,\n                timestamp: event.timestamp\n            }\n        });\n    }\n}\n"],"names":["PostHogAnalyticsProvider","client","options","event","featureKey"],"mappings":"AA2BO,MAAMA;IAGT,YACYC,MAAyB,EACzBC,UAA2C,CAAC,CAAC,CACvD;aAFUD,MAAM,GAANA;aACAC,OAAO,GAAPA;aAJI,IAAI,GAAG;IAKpB;IAEH,MAAM,aAAaC,KAAoB,EAAiB;QACpD,MAAMC,aAAaD,MAAM,aAAa,IAAIA,MAAM,YAAY;QAE5D,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;YACtB,YAAYA,MAAM,SAAS;YAC3B,OAAO,IAAI,CAAC,OAAO,CAAC,iBAAiB,IAAI;YACzC,YAAY;gBAER,CAAC,CAAC,SAAS,EAAEC,YAAY,CAAC,EAAED,MAAM,SAAS;gBAC3C,eAAeA,MAAM,YAAY;gBACjC,YAAYA,MAAM,SAAS;gBAC3B,aAAaA,MAAM,UAAU;gBAC7B,WAAWA,MAAM,QAAQ;gBACzB,SAASA,MAAM,MAAM;gBACrB,MAAMA,MAAM,IAAI;gBAChB,cAAcA,MAAM,IAAI;gBACxB,WAAWA,MAAM,SAAS;YAC9B;QACJ;IACJ;AACJ"}

package/experiments/analyticsProvider.d.ts

@@ -0,0 +1,4 @@
+import type { AnalyticsProvider } from "./types.js";
+export declare const registerAnalyticsProvider: (provider: AnalyticsProvider) => void;
+export declare const getAnalyticsProvider: (name: string) => AnalyticsProvider | undefined;
+export declare const clearAnalyticsProviders: () => void;

package/experiments/analyticsProvider.js

@@ -0,0 +1,11 @@
+const providers = new Map();
+const registerAnalyticsProvider = (provider)=>{
+    providers.set(provider.name, provider);
+};
+const getAnalyticsProvider = (name)=>providers.get(name);
+const clearAnalyticsProviders = ()=>{
+    providers.clear();
+};
+export { clearAnalyticsProviders, getAnalyticsProvider, registerAnalyticsProvider };
+
+//# sourceMappingURL=analyticsProvider.js.map

package/experiments/analyticsProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"experiments/analyticsProvider.js","sources":["../../src/experiments/analyticsProvider.ts"],"sourcesContent":["import type { AnalyticsProvider } from \"./types.js\";\n\n/**\n * A small registry mapping a provider id (e.g. \"posthog\") to its adapter. The render path\n * looks the provider up by the experiment's analytics.provider value, so adding a GA4 adapter\n * later requires no change to assignment or the render path.\n */\nconst providers = new Map<string, AnalyticsProvider>();\n\nexport const registerAnalyticsProvider = (provider: AnalyticsProvider): void => {\n    providers.set(provider.name, provider);\n};\n\nexport const getAnalyticsProvider = (name: string): AnalyticsProvider | undefined => {\n    return providers.get(name);\n};\n\nexport const clearAnalyticsProviders = (): void => {\n    providers.clear();\n};\n"],"names":["providers","Map","registerAnalyticsProvider","provider","getAnalyticsProvider","name","clearAnalyticsProviders"],"mappings":"AAOA,MAAMA,YAAY,IAAIC;AAEf,MAAMC,4BAA4B,CAACC;IACtCH,UAAU,GAAG,CAACG,SAAS,IAAI,EAAEA;AACjC;AAEO,MAAMC,uBAAuB,CAACC,OAC1BL,UAAU,GAAG,CAACK;AAGlB,MAAMC,0BAA0B;IACnCN,UAAU,KAAK;AACnB"}

package/experiments/bucketing.d.ts

@@ -0,0 +1,27 @@
+import type { ActiveExperiment, ExperimentTargeting, VariantAssignment, VisitorContext } from "./types.js";
+/**
+ * cyrb53 — a fast, well-distributed non-cryptographic string hash. Deterministic across
+ * runtimes, which is what makes server-side bucketing stable for a given visitor + experiment.
+ */
+export declare const cyrb53: (str: string, seed?: number) => number;
+/** Hash a seed to a stable number in the half-open interval [0, 1). */
+export declare const hashToUnit: (seed: string) => number;
+/**
+ * Whether a visitor matches the experiment's geo/device targeting. Tenant scoping is implicit:
+ * the experiment id is unique within a tenant, so a visitor's bucket never crosses tenants.
+ */
+export declare const matchesTargeting: (targeting: ExperimentTargeting, ctx: VisitorContext) => boolean;
+/**
+ * Deterministically assign a visitor to the control bucket or a variant.
+ *
+ * 1. If geo/device targeting excludes the visitor → control, excluded (no exposure).
+ * 2. If the visitor falls outside the traffic percentage → control, excluded (no exposure).
+ * 3. Otherwise bucket among the control + variants by their weights, seeded by
+ *    visitorId + experimentId so the result is stable and tenant-isolated.
+ */
+export declare const assignVariant: (experiment: ActiveExperiment, ctx: VisitorContext) => VariantAssignment;
+/**
+ * A forced assignment for QA/review. Overrides bucketing and is never counted in results.
+ * Returns null when the forced id does not match the control or any ready variant.
+ */
+export declare const forcedAssignment: (experiment: ActiveExperiment, forcedVariantId: string) => VariantAssignment | null;

package/experiments/bucketing.js

@@ -0,0 +1,91 @@
+const cyrb53 = (str, seed = 0)=>{
+    let h1 = 0xdeadbeef ^ seed;
+    let h2 = 0x41c6ce57 ^ seed;
+    for(let i = 0; i < str.length; i++){
+        const ch = str.charCodeAt(i);
+        h1 = Math.imul(h1 ^ ch, 2654435761);
+        h2 = Math.imul(h2 ^ ch, 1597334677);
+    }
+    h1 = Math.imul(h1 ^ h1 >>> 16, 2246822507);
+    h1 ^= Math.imul(h2 ^ h2 >>> 13, 3266489909);
+    h2 = Math.imul(h2 ^ h2 >>> 16, 2246822507);
+    h2 ^= Math.imul(h1 ^ h1 >>> 13, 3266489909);
+    return 4294967296 * (2097151 & h2) + (h1 >>> 0);
+};
+const hashToUnit = (seed)=>cyrb53(seed) / 9007199254740992;
+const matchesTargeting = (targeting, ctx)=>{
+    if (targeting.geo && targeting.geo.length > 0) {
+        if (!ctx.country || !targeting.geo.includes(ctx.country)) return false;
+    }
+    if (targeting.device && targeting.device.length > 0) {
+        if (!ctx.device || !targeting.device.includes(ctx.device)) return false;
+    }
+    return true;
+};
+const assignVariant = (experiment, ctx)=>{
+    const controlVariantId = experiment.controlVariantId;
+    const control = {
+        variantId: controlVariantId,
+        isControl: true,
+        excluded: true,
+        forced: false
+    };
+    if (!matchesTargeting(experiment.targeting, ctx)) return control;
+    const trafficPercentage = experiment.targeting.trafficPercentage ?? 100;
+    const inclusion = hashToUnit(`${ctx.visitorId}:${experiment.experimentId}:inclusion`);
+    if (inclusion >= trafficPercentage / 100) return control;
+    const readyVariantIds = new Set(experiment.variants.map((variant)=>variant.variantId));
+    const buckets = [
+        {
+            id: controlVariantId,
+            weight: Math.max(0, experiment.trafficSplit.control)
+        }
+    ];
+    for (const [variantId, weight] of Object.entries(experiment.trafficSplit.variants))if (readyVariantIds.has(variantId) && weight > 0) buckets.push({
+        id: variantId,
+        weight
+    });
+    const totalWeight = buckets.reduce((sum, bucket)=>sum + bucket.weight, 0);
+    if (totalWeight <= 0) return {
+        variantId: controlVariantId,
+        isControl: true,
+        excluded: false,
+        forced: false
+    };
+    let roll = hashToUnit(`${ctx.visitorId}:${experiment.experimentId}`) * totalWeight;
+    for (const bucket of buckets){
+        roll -= bucket.weight;
+        if (roll < 0) return {
+            variantId: bucket.id,
+            isControl: bucket.id === controlVariantId,
+            excluded: false,
+            forced: false
+        };
+    }
+    const last = buckets[buckets.length - 1];
+    return {
+        variantId: last.id,
+        isControl: last.id === controlVariantId,
+        excluded: false,
+        forced: false
+    };
+};
+const forcedAssignment = (experiment, forcedVariantId)=>{
+    if (forcedVariantId === experiment.controlVariantId) return {
+        variantId: forcedVariantId,
+        isControl: true,
+        excluded: false,
+        forced: true
+    };
+    const isReady = experiment.variants.some((variant)=>variant.variantId === forcedVariantId);
+    if (!isReady) return null;
+    return {
+        variantId: forcedVariantId,
+        isControl: false,
+        excluded: false,
+        forced: true
+    };
+};
+export { assignVariant, cyrb53, forcedAssignment, hashToUnit, matchesTargeting };
+
+//# sourceMappingURL=bucketing.js.map

package/experiments/bucketing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"experiments/bucketing.js","sources":["../../src/experiments/bucketing.ts"],"sourcesContent":["import type {\n    ActiveExperiment,\n    ExperimentTargeting,\n    VariantAssignment,\n    VisitorContext\n} from \"./types.js\";\n\n/**\n * cyrb53 — a fast, well-distributed non-cryptographic string hash. Deterministic across\n * runtimes, which is what makes server-side bucketing stable for a given visitor + experiment.\n */\nexport const cyrb53 = (str: string, seed = 0): number => {\n    let h1 = 0xdeadbeef ^ seed;\n    let h2 = 0x41c6ce57 ^ seed;\n    for (let i = 0; i < str.length; i++) {\n        const ch = str.charCodeAt(i);\n        h1 = Math.imul(h1 ^ ch, 2654435761);\n        h2 = Math.imul(h2 ^ ch, 1597334677);\n    }\n    h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507);\n    h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909);\n    h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507);\n    h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909);\n    return 4294967296 * (2097151 & h2) + (h1 >>> 0);\n};\n\n/** Hash a seed to a stable number in the half-open interval [0, 1). */\nexport const hashToUnit = (seed: string): number => {\n    return cyrb53(seed) / 9007199254740992;\n};\n\n/**\n * Whether a visitor matches the experiment's geo/device targeting. Tenant scoping is implicit:\n * the experiment id is unique within a tenant, so a visitor's bucket never crosses tenants.\n */\nexport const matchesTargeting = (targeting: ExperimentTargeting, ctx: VisitorContext): boolean => {\n    if (targeting.geo && targeting.geo.length > 0) {\n        if (!ctx.country || !targeting.geo.includes(ctx.country)) {\n            return false;\n        }\n    }\n    if (targeting.device && targeting.device.length > 0) {\n        if (!ctx.device || !targeting.device.includes(ctx.device)) {\n            return false;\n        }\n    }\n    return true;\n};\n\n/**\n * Deterministically assign a visitor to the control bucket or a variant.\n *\n * 1. If geo/device targeting excludes the visitor → control, excluded (no exposure).\n * 2. If the visitor falls outside the traffic percentage → control, excluded (no exposure).\n * 3. Otherwise bucket among the control + variants by their weights, seeded by\n *    visitorId + experimentId so the result is stable and tenant-isolated.\n */\nexport const assignVariant = (\n    experiment: ActiveExperiment,\n    ctx: VisitorContext\n): VariantAssignment => {\n    const controlVariantId = experiment.controlVariantId;\n    const control: VariantAssignment = {\n        variantId: controlVariantId,\n        isControl: true,\n        excluded: true,\n        forced: false\n    };\n\n    if (!matchesTargeting(experiment.targeting, ctx)) {\n        return control;\n    }\n\n    const trafficPercentage = experiment.targeting.trafficPercentage ?? 100;\n    const inclusion = hashToUnit(`${ctx.visitorId}:${experiment.experimentId}:inclusion`);\n    if (inclusion >= trafficPercentage / 100) {\n        return control;\n    }\n\n    // Build the bucket list: control first, then every variant that is both ready (present in\n    // experiment.variants) and assigned a weight in the traffic split.\n    const readyVariantIds = new Set(experiment.variants.map(variant => variant.variantId));\n    const buckets: Array<{ id: string; weight: number }> = [\n        { id: controlVariantId, weight: Math.max(0, experiment.trafficSplit.control) }\n    ];\n    for (const [variantId, weight] of Object.entries(experiment.trafficSplit.variants)) {\n        if (readyVariantIds.has(variantId) && weight > 0) {\n            buckets.push({ id: variantId, weight });\n        }\n    }\n\n    const totalWeight = buckets.reduce((sum, bucket) => sum + bucket.weight, 0);\n    if (totalWeight <= 0) {\n        return { variantId: controlVariantId, isControl: true, excluded: false, forced: false };\n    }\n\n    let roll = hashToUnit(`${ctx.visitorId}:${experiment.experimentId}`) * totalWeight;\n    for (const bucket of buckets) {\n        roll -= bucket.weight;\n        if (roll < 0) {\n            return {\n                variantId: bucket.id,\n                isControl: bucket.id === controlVariantId,\n                excluded: false,\n                forced: false\n            };\n        }\n    }\n\n    // Floating-point edge: fall back to the last bucket.\n    const last = buckets[buckets.length - 1];\n    return {\n        variantId: last.id,\n        isControl: last.id === controlVariantId,\n        excluded: false,\n        forced: false\n    };\n};\n\n/**\n * A forced assignment for QA/review. Overrides bucketing and is never counted in results.\n * Returns null when the forced id does not match the control or any ready variant.\n */\nexport const forcedAssignment = (\n    experiment: ActiveExperiment,\n    forcedVariantId: string\n): VariantAssignment | null => {\n    if (forcedVariantId === experiment.controlVariantId) {\n        return { variantId: forcedVariantId, isControl: true, excluded: false, forced: true };\n    }\n    const isReady = experiment.variants.some(variant => variant.variantId === forcedVariantId);\n    if (!isReady) {\n        return null;\n    }\n    return { variantId: forcedVariantId, isControl: false, excluded: false, forced: true };\n};\n"],"names":["cyrb53","str","seed","h1","h2","i","ch","Math","hashToUnit","matchesTargeting","targeting","ctx","assignVariant","experiment","controlVariantId","control","trafficPercentage","inclusion","readyVariantIds","Set","variant","buckets","variantId","weight","Object","totalWeight","sum","bucket","roll","last","forcedAssignment","forcedVariantId","isReady"],"mappings":"AAWO,MAAMA,SAAS,CAACC,KAAaC,OAAO,CAAC;IACxC,IAAIC,KAAK,aAAaD;IACtB,IAAIE,KAAK,aAAaF;IACtB,IAAK,IAAIG,IAAI,GAAGA,IAAIJ,IAAI,MAAM,EAAEI,IAAK;QACjC,MAAMC,KAAKL,IAAI,UAAU,CAACI;QAC1BF,KAAKI,KAAK,IAAI,CAACJ,KAAKG,IAAI;QACxBF,KAAKG,KAAK,IAAI,CAACH,KAAKE,IAAI;IAC5B;IACAH,KAAKI,KAAK,IAAI,CAACJ,KAAMA,OAAO,IAAK;IACjCA,MAAMI,KAAK,IAAI,CAACH,KAAMA,OAAO,IAAK;IAClCA,KAAKG,KAAK,IAAI,CAACH,KAAMA,OAAO,IAAK;IACjCA,MAAMG,KAAK,IAAI,CAACJ,KAAMA,OAAO,IAAK;IAClC,OAAO,aAAc,WAAUC,EAAC,IAAMD,CAAAA,OAAO;AACjD;AAGO,MAAMK,aAAa,CAACN,OAChBF,OAAOE,QAAQ;AAOnB,MAAMO,mBAAmB,CAACC,WAAgCC;IAC7D,IAAID,UAAU,GAAG,IAAIA,UAAU,GAAG,CAAC,MAAM,GAAG,GACxC;QAAA,IAAI,CAACC,IAAI,OAAO,IAAI,CAACD,UAAU,GAAG,CAAC,QAAQ,CAACC,IAAI,OAAO,GACnD,OAAO;IACX;IAEJ,IAAID,UAAU,MAAM,IAAIA,UAAU,MAAM,CAAC,MAAM,GAAG,GAC9C;QAAA,IAAI,CAACC,IAAI,MAAM,IAAI,CAACD,UAAU,MAAM,CAAC,QAAQ,CAACC,IAAI,MAAM,GACpD,OAAO;IACX;IAEJ,OAAO;AACX;AAUO,MAAMC,gBAAgB,CACzBC,YACAF;IAEA,MAAMG,mBAAmBD,WAAW,gBAAgB;IACpD,MAAME,UAA6B;QAC/B,WAAWD;QACX,WAAW;QACX,UAAU;QACV,QAAQ;IACZ;IAEA,IAAI,CAACL,iBAAiBI,WAAW,SAAS,EAAEF,MACxC,OAAOI;IAGX,MAAMC,oBAAoBH,WAAW,SAAS,CAAC,iBAAiB,IAAI;IACpE,MAAMI,YAAYT,WAAW,GAAGG,IAAI,SAAS,CAAC,CAAC,EAAEE,WAAW,YAAY,CAAC,UAAU,CAAC;IACpF,IAAII,aAAaD,oBAAoB,KACjC,OAAOD;IAKX,MAAMG,kBAAkB,IAAIC,IAAIN,WAAW,QAAQ,CAAC,GAAG,CAACO,CAAAA,UAAWA,QAAQ,SAAS;IACpF,MAAMC,UAAiD;QACnD;YAAE,IAAIP;YAAkB,QAAQP,KAAK,GAAG,CAAC,GAAGM,WAAW,YAAY,CAAC,OAAO;QAAE;KAChF;IACD,KAAK,MAAM,CAACS,WAAWC,OAAO,IAAIC,OAAO,OAAO,CAACX,WAAW,YAAY,CAAC,QAAQ,EAC7E,IAAIK,gBAAgB,GAAG,CAACI,cAAcC,SAAS,GAC3CF,QAAQ,IAAI,CAAC;QAAE,IAAIC;QAAWC;IAAO;IAI7C,MAAME,cAAcJ,QAAQ,MAAM,CAAC,CAACK,KAAKC,SAAWD,MAAMC,OAAO,MAAM,EAAE;IACzE,IAAIF,eAAe,GACf,OAAO;QAAE,WAAWX;QAAkB,WAAW;QAAM,UAAU;QAAO,QAAQ;IAAM;IAG1F,IAAIc,OAAOpB,WAAW,GAAGG,IAAI,SAAS,CAAC,CAAC,EAAEE,WAAW,YAAY,EAAE,IAAIY;IACvE,KAAK,MAAME,UAAUN,QAAS;QAC1BO,QAAQD,OAAO,MAAM;QACrB,IAAIC,OAAO,GACP,OAAO;YACH,WAAWD,OAAO,EAAE;YACpB,WAAWA,OAAO,EAAE,KAAKb;YACzB,UAAU;YACV,QAAQ;QACZ;IAER;IAGA,MAAMe,OAAOR,OAAO,CAACA,QAAQ,MAAM,GAAG,EAAE;IACxC,OAAO;QACH,WAAWQ,KAAK,EAAE;QAClB,WAAWA,KAAK,EAAE,KAAKf;QACvB,UAAU;QACV,QAAQ;IACZ;AACJ;AAMO,MAAMgB,mBAAmB,CAC5BjB,YACAkB;IAEA,IAAIA,oBAAoBlB,WAAW,gBAAgB,EAC/C,OAAO;QAAE,WAAWkB;QAAiB,WAAW;QAAM,UAAU;QAAO,QAAQ;IAAK;IAExF,MAAMC,UAAUnB,WAAW,QAAQ,CAAC,IAAI,CAACO,CAAAA,UAAWA,QAAQ,SAAS,KAAKW;IAC1E,IAAI,CAACC,SACD,OAAO;IAEX,OAAO;QAAE,WAAWD;QAAiB,WAAW;QAAO,UAAU;QAAO,QAAQ;IAAK;AACzF"}

package/experiments/bucketing.test.d.ts

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

package/experiments/bucketing.test.js

@@ -0,0 +1,183 @@
+import { describe, expect, it } from "vitest";
+import { assignVariant, forcedAssignment, hashToUnit, matchesTargeting } from "./bucketing.js";
+import { CONTROL_VARIANT_ID } from "./types.js";
+const experiment = (overrides = {})=>({
+        experimentId: "exp-1",
+        revisionId: "page-1#0001",
+        pageEntryId: "page-1",
+        path: "/pricing",
+        status: "running",
+        tenantId: "root",
+        controlVariantId: CONTROL_VARIANT_ID,
+        trafficSplit: {
+            control: 50,
+            variants: {
+                "variant-a": 50
+            }
+        },
+        targeting: {
+            trafficPercentage: 100
+        },
+        analytics: {
+            provider: "posthog"
+        },
+        variants: [
+            {
+                variantId: "variant-a",
+                name: "Variant A"
+            }
+        ],
+        ...overrides
+    });
+const visitor = (overrides = {})=>({
+        visitorId: "visitor-1",
+        ...overrides
+    });
+describe("hashToUnit", ()=>{
+    it("is deterministic and within [0, 1)", ()=>{
+        const a = hashToUnit("visitor-1:exp-1");
+        const b = hashToUnit("visitor-1:exp-1");
+        expect(a).toBe(b);
+        expect(a).toBeGreaterThanOrEqual(0);
+        expect(a).toBeLessThan(1);
+    });
+    it("differs across seeds", ()=>{
+        expect(hashToUnit("visitor-1:exp-1")).not.toBe(hashToUnit("visitor-2:exp-1"));
+    });
+});
+describe("assignVariant", ()=>{
+    it("assigns the same visitor to the same bucket every time", ()=>{
+        const first = assignVariant(experiment(), visitor());
+        const second = assignVariant(experiment(), visitor());
+        expect(second).toEqual(first);
+    });
+    it("buckets the same visitor differently across experiments", ()=>{
+        const a = assignVariant(experiment({
+            experimentId: "exp-1"
+        }), visitor());
+        const b = assignVariant(experiment({
+            experimentId: "exp-2"
+        }), visitor());
+        expect(hashToUnit("visitor-1:exp-1")).not.toBe(hashToUnit("visitor-1:exp-2"));
+        expect([
+            a.variantId,
+            b.variantId
+        ].every(Boolean)).toBe(true);
+    });
+    it("respects the traffic split distribution", ()=>{
+        const exp = experiment({
+            trafficSplit: {
+                control: 80,
+                variants: {
+                    "variant-a": 20
+                }
+            }
+        });
+        let control = 0;
+        let variant = 0;
+        for(let i = 0; i < 5000; i++){
+            const assignment = assignVariant(exp, visitor({
+                visitorId: `v-${i}`
+            }));
+            if (assignment.isControl) control++;
+            else variant++;
+        }
+        const variantShare = variant / (control + variant);
+        expect(variantShare).toBeGreaterThan(0.15);
+        expect(variantShare).toBeLessThan(0.25);
+    });
+    it("excludes visitors outside the traffic percentage and serves control", ()=>{
+        const exp = experiment({
+            targeting: {
+                trafficPercentage: 0
+            }
+        });
+        const assignment = assignVariant(exp, visitor());
+        expect(assignment.isControl).toBe(true);
+        expect(assignment.excluded).toBe(true);
+    });
+    it("excludes visitors who do not match geo targeting", ()=>{
+        const exp = experiment({
+            targeting: {
+                trafficPercentage: 100,
+                geo: [
+                    "GB"
+                ]
+            }
+        });
+        const assignment = assignVariant(exp, visitor({
+            country: "US"
+        }));
+        expect(assignment.excluded).toBe(true);
+        expect(assignment.isControl).toBe(true);
+    });
+    it("ignores variants that are not ready", ()=>{
+        const exp = experiment({
+            trafficSplit: {
+                control: 0,
+                variants: {
+                    "variant-a": 50,
+                    "variant-ghost": 50
+                }
+            },
+            variants: [
+                {
+                    variantId: "variant-a",
+                    name: "Variant A"
+                }
+            ]
+        });
+        for(let i = 0; i < 200; i++){
+            const assignment = assignVariant(exp, visitor({
+                visitorId: `v-${i}`
+            }));
+            expect(assignment.variantId).not.toBe("variant-ghost");
+        }
+    });
+});
+describe("matchesTargeting", ()=>{
+    it("matches when no geo/device restriction is set", ()=>{
+        expect(matchesTargeting({
+            trafficPercentage: 100
+        }, visitor())).toBe(true);
+    });
+    it("matches device targeting", ()=>{
+        expect(matchesTargeting({
+            trafficPercentage: 100,
+            device: [
+                "mobile"
+            ]
+        }, visitor({
+            device: "mobile"
+        }))).toBe(true);
+        expect(matchesTargeting({
+            trafficPercentage: 100,
+            device: [
+                "mobile"
+            ]
+        }, visitor({
+            device: "desktop"
+        }))).toBe(false);
+    });
+});
+describe("forcedAssignment", ()=>{
+    it("forces a ready variant and marks it as not counted", ()=>{
+        const assignment = forcedAssignment(experiment(), "variant-a");
+        expect(assignment).toEqual({
+            variantId: "variant-a",
+            isControl: false,
+            excluded: false,
+            forced: true
+        });
+    });
+    it("forces the control bucket", ()=>{
+        const assignment = forcedAssignment(experiment(), CONTROL_VARIANT_ID);
+        expect(assignment?.isControl).toBe(true);
+        expect(assignment?.forced).toBe(true);
+    });
+    it("returns null for an unknown variant", ()=>{
+        expect(forcedAssignment(experiment(), "nope")).toBeNull();
+    });
+});
+
+//# sourceMappingURL=bucketing.test.js.map

package/experiments/bucketing.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"experiments/bucketing.test.js","sources":["../../src/experiments/bucketing.test.ts"],"sourcesContent":["import { describe, it, expect } from \"vitest\";\nimport { assignVariant, forcedAssignment, hashToUnit, matchesTargeting } from \"./bucketing.js\";\nimport { CONTROL_VARIANT_ID, type ActiveExperiment, type VisitorContext } from \"./types.js\";\n\nconst experiment = (overrides: Partial<ActiveExperiment> = {}): ActiveExperiment => ({\n    experimentId: \"exp-1\",\n    revisionId: \"page-1#0001\",\n    pageEntryId: \"page-1\",\n    path: \"/pricing\",\n    status: \"running\",\n    tenantId: \"root\",\n    controlVariantId: CONTROL_VARIANT_ID,\n    trafficSplit: { control: 50, variants: { \"variant-a\": 50 } },\n    targeting: { trafficPercentage: 100 },\n    analytics: { provider: \"posthog\" },\n    variants: [{ variantId: \"variant-a\", name: \"Variant A\" }],\n    ...overrides\n});\n\nconst visitor = (overrides: Partial<VisitorContext> = {}): VisitorContext => ({\n    visitorId: \"visitor-1\",\n    ...overrides\n});\n\ndescribe(\"hashToUnit\", () => {\n    it(\"is deterministic and within [0, 1)\", () => {\n        const a = hashToUnit(\"visitor-1:exp-1\");\n        const b = hashToUnit(\"visitor-1:exp-1\");\n        expect(a).toBe(b);\n        expect(a).toBeGreaterThanOrEqual(0);\n        expect(a).toBeLessThan(1);\n    });\n\n    it(\"differs across seeds\", () => {\n        expect(hashToUnit(\"visitor-1:exp-1\")).not.toBe(hashToUnit(\"visitor-2:exp-1\"));\n    });\n});\n\ndescribe(\"assignVariant\", () => {\n    it(\"assigns the same visitor to the same bucket every time\", () => {\n        const first = assignVariant(experiment(), visitor());\n        const second = assignVariant(experiment(), visitor());\n        expect(second).toEqual(first);\n    });\n\n    it(\"buckets the same visitor differently across experiments\", () => {\n        const a = assignVariant(experiment({ experimentId: \"exp-1\" }), visitor());\n        const b = assignVariant(experiment({ experimentId: \"exp-2\" }), visitor());\n        // Not guaranteed to differ, but the seed differs; assert the seeds are independent.\n        expect(hashToUnit(\"visitor-1:exp-1\")).not.toBe(hashToUnit(\"visitor-1:exp-2\"));\n        expect([a.variantId, b.variantId].every(Boolean)).toBe(true);\n    });\n\n    it(\"respects the traffic split distribution\", () => {\n        const exp = experiment({\n            trafficSplit: { control: 80, variants: { \"variant-a\": 20 } }\n        });\n        let control = 0;\n        let variant = 0;\n        for (let i = 0; i < 5000; i++) {\n            const assignment = assignVariant(exp, visitor({ visitorId: `v-${i}` }));\n            if (assignment.isControl) {\n                control++;\n            } else {\n                variant++;\n            }\n        }\n        const variantShare = variant / (control + variant);\n        // Expect ~20% in the variant, allow a generous tolerance.\n        expect(variantShare).toBeGreaterThan(0.15);\n        expect(variantShare).toBeLessThan(0.25);\n    });\n\n    it(\"excludes visitors outside the traffic percentage and serves control\", () => {\n        const exp = experiment({ targeting: { trafficPercentage: 0 } });\n        const assignment = assignVariant(exp, visitor());\n        expect(assignment.isControl).toBe(true);\n        expect(assignment.excluded).toBe(true);\n    });\n\n    it(\"excludes visitors who do not match geo targeting\", () => {\n        const exp = experiment({ targeting: { trafficPercentage: 100, geo: [\"GB\"] } });\n        const assignment = assignVariant(exp, visitor({ country: \"US\" }));\n        expect(assignment.excluded).toBe(true);\n        expect(assignment.isControl).toBe(true);\n    });\n\n    it(\"ignores variants that are not ready\", () => {\n        const exp = experiment({\n            trafficSplit: { control: 0, variants: { \"variant-a\": 50, \"variant-ghost\": 50 } },\n            variants: [{ variantId: \"variant-a\", name: \"Variant A\" }]\n        });\n        for (let i = 0; i < 200; i++) {\n            const assignment = assignVariant(exp, visitor({ visitorId: `v-${i}` }));\n            expect(assignment.variantId).not.toBe(\"variant-ghost\");\n        }\n    });\n});\n\ndescribe(\"matchesTargeting\", () => {\n    it(\"matches when no geo/device restriction is set\", () => {\n        expect(matchesTargeting({ trafficPercentage: 100 }, visitor())).toBe(true);\n    });\n\n    it(\"matches device targeting\", () => {\n        expect(\n            matchesTargeting(\n                { trafficPercentage: 100, device: [\"mobile\"] },\n                visitor({ device: \"mobile\" })\n            )\n        ).toBe(true);\n        expect(\n            matchesTargeting(\n                { trafficPercentage: 100, device: [\"mobile\"] },\n                visitor({ device: \"desktop\" })\n            )\n        ).toBe(false);\n    });\n});\n\ndescribe(\"forcedAssignment\", () => {\n    it(\"forces a ready variant and marks it as not counted\", () => {\n        const assignment = forcedAssignment(experiment(), \"variant-a\");\n        expect(assignment).toEqual({\n            variantId: \"variant-a\",\n            isControl: false,\n            excluded: false,\n            forced: true\n        });\n    });\n\n    it(\"forces the control bucket\", () => {\n        const assignment = forcedAssignment(experiment(), CONTROL_VARIANT_ID);\n        expect(assignment?.isControl).toBe(true);\n        expect(assignment?.forced).toBe(true);\n    });\n\n    it(\"returns null for an unknown variant\", () => {\n        expect(forcedAssignment(experiment(), \"nope\")).toBeNull();\n    });\n});\n"],"names":["experiment","overrides","CONTROL_VARIANT_ID","visitor","describe","it","a","hashToUnit","b","expect","first","assignVariant","second","Boolean","exp","control","variant","i","assignment","variantShare","matchesTargeting","forcedAssignment"],"mappings":"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"}

package/experiments/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./bucketing.js";
+export * from "./analyticsProvider.js";
+export * from "./PostHogAnalyticsProvider.js";
+export * from "./render.js";

package/experiments/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./bucketing.js";
+export * from "./analyticsProvider.js";
+export * from "./PostHogAnalyticsProvider.js";
+export * from "./render.js";

package/experiments/render.d.ts

@@ -0,0 +1,82 @@
+import type { PublicPage } from "../types.js";
+import type { HeadersProvider } from "../headersProvider.js";
+import type { ActiveExperiment, DeviceType, VariantAssignment, VariantContent, VisitorContext } from "./types.js";
+/** The cookie that persists the stable visitor id used for deterministic bucketing. */
+export declare const DEFAULT_VISITOR_COOKIE = "wb_ab_vid";
+/** Default query parameter used to force a variant for QA/review. */
+export declare const FORCED_VARIANT_PARAM = "wb-variant";
+/** The minimal data surface the render helper needs. ContentSdk satisfies this. */
+export interface ExperimentSdk {
+    getPage(path: string): Promise<PublicPage | null>;
+    getPageExperiment(path: string): Promise<ActiveExperiment | null>;
+    getVariantContent(variantId: string): Promise<VariantContent | null>;
+    /** Runtime kill-switch check. When omitted, the pause state is not consulted. */
+    getExperimentPaused?(experimentId: string): Promise<boolean>;
+}
+export interface ExperimentCookie {
+    name: string;
+    value: string;
+    maxAge: number;
+}
+export interface GetPageWithExperimentOptions {
+    /** Forced variant id (from the `?wb-variant=` query parameter). Overrides bucketing, never counted. */
+    forcedVariantId?: string;
+    /**
+     * Request query parameters. When provided, the forced variant is read from
+     * `searchParams[FORCED_VARIANT_PARAM]` unless `forcedVariantId` is set explicitly. Convenient
+     * for framework handlers that already have the parsed query (e.g. Next.js `searchParams`).
+     */
+    searchParams?: Record<string, string | string[] | undefined>;
+    /** Explicit visitor id. When omitted, it is read from the cookie or generated. */
+    visitorId?: string;
+    /** Explicit ISO country code. When omitted, it is read from common CDN geo headers. */
+    country?: string;
+    /** Explicit device type. When omitted, it is derived from the user agent. */
+    device?: DeviceType;
+    /** Header names to read the visitor country from, in priority order. */
+    geoHeaders?: string[];
+    /** Bucketing cookie name. Defaults to `wb_ab_vid`. */
+    cookieName?: string;
+    /** Bucketing cookie max age in seconds. Defaults to one year. */
+    cookieMaxAge?: number;
+    /** Set false to skip exposure emission (e.g. when consent has not been granted). */
+    emitExposure?: boolean;
+    /** Visitor id generator. Defaults to nanoid. */
+    generateVisitorId?: () => string;
+    /** Request headers to read cookies, geo and user agent from. Defaults to the global provider. */
+    headersProvider?: HeadersProvider;
+}
+export interface ExperimentRenderResult {
+    /** The content to render server-side: the baseline (control) or a variant overlay. */
+    page: PublicPage | null;
+    /** The active experiment, or null when there is none for the path. */
+    experiment: ActiveExperiment | null;
+    /** The visitor's assignment, or null when no experiment applies. */
+    assignment: VariantAssignment | null;
+    /**
+     * Set when the caller should persist the bucketing cookie (i.e. a visitor id was generated
+     * this request). Persisting it in a Route Handler / middleware keeps bucketing stable.
+     */
+    cookie?: ExperimentCookie;
+}
+/**
+ * Resolve request-time visitor context from request headers/cookies. Never uses a logged-in
+ * identity. Returns whether a visitor id was generated, so the caller can persist the cookie.
+ */
+export declare const resolveVisitorContext: (options?: GetPageWithExperimentOptions) => Promise<{
+    context: VisitorContext;
+    generatedVisitorId: boolean;
+}>;
+/**
+ * Resolve and render the right page for a visitor, server-side, with no client-side content
+ * swap.
+ *
+ * Caching contract (important — handled here so projects do not reimplement it):
+ *  - The baseline (control) is fetched via `getPage(path)` and caches per path.
+ *  - The active experiment metadata is fetched via `getPageExperiment(path)` and caches per path.
+ *  - A variant's content is fetched via `getVariantContent(variantId)` and caches per variant id.
+ * Every request therefore resolves to one of a small, fixed set of cacheable objects keyed by
+ * (path) or (variant id) — NEVER by the raw visitor id. Each active variant adds exactly one
+ * cacheable object per URL.
+ */
+export declare const getPageWithExperiment: (sdk: ExperimentSdk, path: string, options?: GetPageWithExperimentOptions) => Promise<ExperimentRenderResult>;