next-evolve 0.0.0-stage → 0.3.1

package/dist/client/evolve-script.js

@@ -0,0 +1,60 @@
+"use client";
+import { flush, push } from "./beacon.js";
+import { useEffect } from "react";
+import { usePathname } from "next/navigation";
+// src/client/evolve-script.tsx
+/**
+* Evolve beacon. Place once in the root layout. Not needed to show a variant.
+* Queues a page view and one exposure per counted region on every route, and
+* clicks/submits on `[data-evolve-goal]`; flushes every 2 s and on page hide.
+*/
+function EvolveScript() {
+	const path = usePathname();
+	useEffect(() => {
+		document.documentElement.dataset.evolve = "ready";
+		const onGoal = (ev) => {
+			const el = ev.target?.closest?.("[data-evolve-goal]");
+			const n = el?.getAttribute("data-evolve-goal");
+			if (!n || ev.type === "submit" !== (el?.tagName === "FORM")) return;
+			push({
+				t: "ev",
+				n,
+				p: location.pathname
+			});
+		};
+		const onHide = () => document.visibilityState === "hidden" && flush();
+		document.addEventListener("click", onGoal, true);
+		document.addEventListener("submit", onGoal, true);
+		document.addEventListener("visibilitychange", onHide);
+		addEventListener("pagehide", flush);
+		return () => {
+			document.removeEventListener("click", onGoal, true);
+			document.removeEventListener("submit", onGoal, true);
+			document.removeEventListener("visibilitychange", onHide);
+			removeEventListener("pagehide", flush);
+		};
+	}, []);
+	useEffect(() => {
+		const p = location.pathname;
+		push({
+			t: "pv",
+			p
+		});
+		const seen = /* @__PURE__ */ new Set();
+		for (const el of document.querySelectorAll("[data-evolve-e]:not([data-evolve-x])")) {
+			const e = el.getAttribute("data-evolve-e");
+			const v = el.getAttribute("data-evolve-v");
+			if (e && v && !seen.has(e)) {
+				seen.add(e);
+				push({
+					t: "exp",
+					e,
+					v,
+					p
+				});
+			}
+		}
+	}, [path]);
+	return null;
+}
+export { EvolveScript };

package/dist/client/index.d.ts

@@ -0,0 +1,3 @@
+import { identify, track } from "./beacon.js";
+import { EvolveScript } from "./evolve-script.js";
+export { EvolveScript, identify, track };

package/dist/client/index.js

@@ -0,0 +1,3 @@
+import { identify, track } from "./beacon.js";
+import { EvolveScript } from "./evolve-script.js";
+export { EvolveScript, identify, track };

package/dist/cloud/manifest.d.ts

@@ -0,0 +1,14 @@
+import { EvolveConfig } from "../config/config.js";
+import { Goals } from "../config/goals.js";
+import { Manifest } from "@next-evolve/protocol";
+/** This package's version (`0.0.0` if unknown). */
+export declare function sdkVersion(): string;
+/** The manifest this app sends to the cloud (spec §8.4). Configuration only. */
+export declare function buildManifest(config: EvolveConfig, goals: Goals | undefined, opts?: {
+  appUrl?: string | null;
+}): Manifest;
+/**
+ * The app's public base URL: EVOLVE_APP_URL, else Vercel's production URL.
+ * Null when unknown (the dashboard asks for it).
+ */
+export declare function detectAppUrl(env?: Record<string, string | undefined>): string | null;

package/dist/cloud/manifest.js

@@ -0,0 +1,46 @@
+import { resolveConfig } from "../config/config.js";
+import { serializeGoals } from "../config/goals.js";
+import { PROTOCOL_VERSION, SUPPORTED_PROTOCOLS, computeManifestHash } from "@next-evolve/protocol";
+import { createRequire } from "node:module";
+// src/cloud/manifest.ts
+const require = createRequire(import.meta.url);
+const versionOf = (load) => {
+	try {
+		return load().version;
+	} catch {
+		return null;
+	}
+};
+/** This package's version (`0.0.0` if unknown). */
+function sdkVersion() {
+	return versionOf(() => require("next-evolve/package.json")) ?? "0.0.0";
+}
+/** The manifest this app sends to the cloud (spec §8.4). Configuration only. */
+function buildManifest(config, goals, opts = {}) {
+	const routes = {};
+	for (const [path, r] of resolveConfig(config).routes) routes[path] = { mode: r.mode };
+	const serialized = goals ? serializeGoals(goals) : {};
+	return {
+		pv: PROTOCOL_VERSION,
+		sdkVersion: sdkVersion(),
+		protocol: { supported: [...SUPPORTED_PROTOCOLS] },
+		nextVersion: versionOf(() => require("next/package.json")),
+		routes,
+		goals: serialized,
+		hash: computeManifestHash({
+			routes,
+			goals: serialized
+		}),
+		appUrl: opts.appUrl ?? null
+	};
+}
+/**
+* The app's public base URL: EVOLVE_APP_URL, else Vercel's production URL.
+* Null when unknown (the dashboard asks for it).
+*/
+function detectAppUrl(env = process.env) {
+	if (env.EVOLVE_APP_URL) return env.EVOLVE_APP_URL.replace(/\/$/, "");
+	if (env.VERCEL_ENV === "production" && env.VERCEL_PROJECT_PRODUCTION_URL) return `https://${env.VERCEL_PROJECT_PRODUCTION_URL}`;
+	return null;
+}
+export { buildManifest, detectAppUrl, sdkVersion };

package/dist/cloud/push.d.ts

@@ -0,0 +1,21 @@
+type Env = Record<string, string | undefined>;
+export type PushResult = {
+  ok: true;
+} | {
+  ok: false;
+  status: number | "network" | "no_key";
+};
+/**
+ * POSTs configuration (manifest, regions) to the cloud with the site's secret
+ * key. Never throws and never blocks a request: callers run it in `after()`
+ * or at startup. Without a secret key it's a no-op.
+ *
+ * Uses node:http, not `fetch`: Next patches `fetch` during prerender, and an
+ * uncached fetch there counts as dynamic usage (the push would fail at build,
+ * where static-mode regions are rendered).
+ */
+export declare function pushToCloud(path: "/v1/manifest" | "/v1/regions", body: unknown, opts?: {
+  env?: Env;
+  timeoutMs?: number;
+}): Promise<PushResult>;
+export {};

package/dist/cloud/push.js

@@ -0,0 +1,56 @@
+import "../store/runtime.js";
+import { request } from "node:http";
+import { request as request$1 } from "node:https";
+// src/cloud/push.ts
+/**
+* POSTs configuration (manifest, regions) to the cloud with the site's secret
+* key. Never throws and never blocks a request: callers run it in `after()`
+* or at startup. Without a secret key it's a no-op.
+*
+* Uses node:http, not `fetch`: Next patches `fetch` during prerender, and an
+* uncached fetch there counts as dynamic usage (the push would fail at build,
+* where static-mode regions are rendered).
+*/
+function pushToCloud(path, body, opts = {}) {
+	const env = opts.env ?? process.env;
+	const key = env.EVOLVE_SECRET_KEY;
+	const cloud = env.EVOLVE_CLOUD_URL ?? "https://api.evolveab.com";
+	if (!key || !cloud) return Promise.resolve({
+		ok: false,
+		status: "no_key"
+	});
+	return new Promise((resolve) => {
+		try {
+			const url = new URL(path, cloud);
+			const data = Buffer.from(JSON.stringify(body));
+			const req = (url.protocol === "https:" ? request$1 : request)(url, {
+				method: "POST",
+				headers: {
+					authorization: `Bearer ${key}`,
+					"content-type": "application/json",
+					"content-length": data.length
+				},
+				timeout: opts.timeoutMs ?? 3e3
+			}, (res) => {
+				res.resume();
+				const status = res.statusCode ?? 0;
+				resolve(status >= 200 && status < 300 ? { ok: true } : {
+					ok: false,
+					status
+				});
+			});
+			req.on("timeout", () => req.destroy(/* @__PURE__ */ new Error("timeout")));
+			req.on("error", () => resolve({
+				ok: false,
+				status: "network"
+			}));
+			req.end(data);
+		} catch {
+			resolve({
+				ok: false,
+				status: "network"
+			});
+		}
+	});
+}
+export { pushToCloud };

package/dist/cloud/regions.d.ts

@@ -0,0 +1,8 @@
+import { RegionRegistration } from "@next-evolve/protocol";
+/**
+ * Registers a region with the cloud (spec §5.2), once per process per
+ * (id, schema, path). Errors are swallowed; a failed push is retried on a later render.
+ */
+export declare function registerRegion(r: Omit<RegionRegistration, "pv">): Promise<void>;
+/** Test helper. */
+export declare function resetRegionRegistry(): void;

package/dist/cloud/regions.js

@@ -0,0 +1,25 @@
+import { pushToCloud } from "./push.js";
+import { PROTOCOL_VERSION } from "@next-evolve/protocol";
+// src/cloud/regions.ts
+const sent = /* @__PURE__ */ new Set();
+const MAX_SENT = 1e3;
+/**
+* Registers a region with the cloud (spec §5.2), once per process per
+* (id, schema, path). Errors are swallowed; a failed push is retried on a later render.
+*/
+async function registerRegion(r) {
+	const key = `${r.id}|${r.schemaHash}|${r.path}`;
+	if (sent.has(key)) return;
+	sent.add(key);
+	if (sent.size > MAX_SENT) sent.delete(sent.values().next().value);
+	const res = await pushToCloud("/v1/regions", {
+		pv: PROTOCOL_VERSION,
+		...r
+	});
+	if (!res.ok && res.status !== "no_key") sent.delete(key);
+}
+/** Test helper. */
+function resetRegionRegistry() {
+	sent.clear();
+}
+export { registerRegion, resetRegionRegistry };

package/dist/config/config.d.ts

@@ -0,0 +1,51 @@
+export type RouteConfig = {
+  /** static (default): ISR per variant under `app/[evolve]/`. dynamic: page reads `x-evolve-a`. */
+  mode: "static" | "dynamic";
+};
+export type EvolveConfig = {
+  /** Routes Evolve may test, keyed by exact pathname (e.g. "/", "/pricing"). */
+  routes: Record<string, RouteConfig>;
+  store?: "auto" | "memory" | "global-config";
+  sync?: {
+    pollSeconds?: number;
+  };
+  database?: {
+    urlEnv?: string;
+  };
+  aggregate?: {
+    maxMs?: number;
+    statementTimeoutMs?: number;
+  };
+  cookies?: {
+    maxAgeDays?: number;
+    domain?: string;
+  };
+  /** Return false to serve control and set no cookies (e.g. before consent). */
+  consent?: (req: Request) => boolean;
+  bots?: {
+    extraPatterns?: string[];
+  };
+  debug?: boolean;
+};
+export type ResolvedConfig = {
+  routes: ReadonlyMap<string, RouteConfig>;
+  store: "auto" | "memory" | "global-config";
+  pollSeconds: number;
+  databaseUrlEnv: string;
+  aggregate: {
+    maxMs: number;
+    statementTimeoutMs: number;
+  };
+  cookies: {
+    maxAgeDays: number;
+    domain: string | undefined;
+  };
+  consent: ((req: Request) => boolean) | undefined;
+  botPatterns: readonly string[];
+  debug: boolean;
+};
+/** Normalizes a pathname: no trailing slash (except "/"), no empty segments. */
+export declare function normalizePath(p: string): string;
+/** Identity helper for `evolve.config.ts` with types and validation. */
+export declare function defineConfig<const C extends EvolveConfig>(config: C): C;
+export declare function resolveConfig(config: EvolveConfig): ResolvedConfig;

package/dist/config/config.js

@@ -0,0 +1,47 @@
+// src/config/config.ts
+/** Normalizes a pathname: no trailing slash (except "/"), no empty segments. */
+function normalizePath(p) {
+	if (p === "/" || p === "") return "/";
+	const s = p.replace(/\/{2,}/g, "/");
+	return s.endsWith("/") ? s.slice(0, -1) : s;
+}
+/** Identity helper for `evolve.config.ts` with types and validation. */
+function defineConfig(config) {
+	resolveConfig(config);
+	return config;
+}
+const resolved = /* @__PURE__ */ new WeakMap();
+function resolveConfig(config) {
+	const hit = resolved.get(config);
+	if (hit) return hit;
+	const routes = /* @__PURE__ */ new Map();
+	for (const [raw, route] of Object.entries(config.routes)) {
+		if (!raw.startsWith("/")) throw new Error(`[evolve] route "${raw}" must start with "/"`);
+		const path = normalizePath(raw);
+		if (path.split("/")[1]?.startsWith("ev_")) throw new Error(`[evolve] route "${raw}" can't start with ev_`);
+		if (/[[\]*?#]/.test(path)) throw new Error(`[evolve] route "${raw}" must be a concrete path`);
+		if (route.mode !== "static" && route.mode !== "dynamic") throw new Error(`[evolve] route "${raw}": mode must be "static" or "dynamic"`);
+		routes.set(path, route);
+	}
+	const dev = process.env.NODE_ENV !== "production";
+	const r = {
+		routes,
+		store: config.store ?? "auto",
+		pollSeconds: config.sync?.pollSeconds ?? (dev ? 5 : 60),
+		databaseUrlEnv: config.database?.urlEnv ?? "EVOLVE_DATABASE_URL",
+		aggregate: {
+			maxMs: config.aggregate?.maxMs ?? 25e3,
+			statementTimeoutMs: config.aggregate?.statementTimeoutMs ?? 2e4
+		},
+		cookies: {
+			maxAgeDays: config.cookies?.maxAgeDays ?? 365,
+			domain: config.cookies?.domain
+		},
+		consent: config.consent,
+		botPatterns: config.bots?.extraPatterns ?? [],
+		debug: config.debug ?? dev
+	};
+	resolved.set(config, r);
+	return r;
+}
+export { defineConfig, normalizePath, resolveConfig };

package/dist/config/goals.d.ts

@@ -0,0 +1,50 @@
+import { SerializedGoal } from "@next-evolve/protocol";
+/** `<n>m`, `<n>h` or `<n>d`, at most 365 days. */
+export type GoalWindow = `${number}${"m" | "h" | "d"}`;
+type Common = {
+  /** Attribution window after first exposure. Default `7d`. */
+  window?: GoalWindow;
+  /** Count per visitor (default) or per identified user. */
+  unit?: "visitor" | "user";
+  /** Whether higher is better. Default `increase`. */
+  direction?: "increase" | "decrease";
+};
+/** An event as a goal's `value` function sees it (at write time, in your app). */
+export type GoalEvent = {
+  name: string;
+  props: Record<string, unknown>;
+  value: number | null;
+  source: string;
+  userId: string | null;
+  anonId: string | null;
+};
+export type EventGoal = Common & {
+  event: string;
+  /** Only events from this source (e.g. `stripe`). */
+  source?: string;
+  /** Only events whose props equal these values. */
+  where?: Record<string, string | number | boolean>;
+  /** A numeric prop path (`"amount"`, `"order.total"`) or a function run locally at write time. */
+  value?: string | ((e: GoalEvent) => number | null | undefined);
+};
+export type PageviewGoal = Common & {
+  /** Exact path, or a prefix ending in `*` (e.g. `/docs/*`). */
+  pageview: string;
+};
+export type GoalDefinition = EventGoal | PageviewGoal;
+export type Goals = Record<string, GoalDefinition>;
+/** Identity helper for `evolve.goals.ts`: types plus validation (throws on mistakes). */
+export declare function defineGoals<const G extends Goals>(goals: G): G;
+/**
+ * Goal definitions as sent to the cloud. Function values become
+ * `{ kind: "local-fn" }`; the function itself never leaves the app.
+ */
+export declare function serializeGoals(goals: Goals): Record<string, SerializedGoal>;
+/** True if a stored `$pageview` at `path` would count for some pageview goal. */
+export declare function matchesPageviewGoal(goals: Goals | undefined, path: string): boolean;
+/**
+ * Runs the `value` functions of matching event goals. Returns `{ goalKey: n }`
+ * or null. A function that throws or returns a non-finite number is skipped.
+ */
+export declare function computeGoalValues(goals: Goals | undefined, e: GoalEvent): Record<string, number> | null;
+export {};

package/dist/config/goals.js

@@ -0,0 +1,85 @@
+import { logRateLimited } from "../core/log.js";
+import { GOAL_KEY_RE, serializedGoalSchema } from "@next-evolve/protocol";
+// src/config/goals.ts
+/** Identity helper for `evolve.goals.ts`: types plus validation (throws on mistakes). */
+function defineGoals(goals) {
+	serializeGoals(goals);
+	return goals;
+}
+/**
+* Goal definitions as sent to the cloud. Function values become
+* `{ kind: "local-fn" }`; the function itself never leaves the app.
+*/
+function serializeGoals(goals) {
+	const out = {};
+	for (const [key, def] of Object.entries(goals)) {
+		if (!GOAL_KEY_RE.test(key)) throw new Error(`[evolve] goal key "${key}" must match ${GOAL_KEY_RE}`);
+		if ("sql" in def) throw new Error(`[evolve] goal "${key}": SQL goals aren't supported yet`);
+		const common = {
+			window: def.window ?? "7d",
+			unit: def.unit ?? "visitor",
+			direction: def.direction ?? "increase"
+		};
+		let wire;
+		if ("event" in def && "pageview" in def) throw new Error(`[evolve] goal "${key}": use either event or pageview, not both`);
+		else if ("event" in def) wire = {
+			kind: "event",
+			event: def.event,
+			source: def.source ?? null,
+			where: def.where ?? null,
+			value: typeof def.value === "function" ? { kind: "local-fn" } : typeof def.value === "string" ? {
+				kind: "prop",
+				path: def.value
+			} : null,
+			...common
+		};
+		else if ("pageview" in def) wire = {
+			kind: "pageview",
+			path: def.pageview,
+			value: null,
+			...common
+		};
+		else throw new Error(`[evolve] goal "${key}" needs event or pageview`);
+		const r = serializedGoalSchema.safeParse(wire);
+		if (!r.success) {
+			const what = r.error.issues.map((i) => `${i.path.join(".") || "goal"}: ${i.message}`);
+			throw new Error(`[evolve] goal "${key}" is invalid (${what.join("; ")})`);
+		}
+		out[key] = r.data;
+	}
+	return out;
+}
+/** True if a stored `$pageview` at `path` would count for some pageview goal. */
+function matchesPageviewGoal(goals, path) {
+	if (!goals) return false;
+	for (const def of Object.values(goals)) {
+		if (!("pageview" in def)) continue;
+		const p = def.pageview;
+		if (p.endsWith("*") ? path.startsWith(p.slice(0, -1)) : path === p) return true;
+	}
+	return false;
+}
+/**
+* Runs the `value` functions of matching event goals. Returns `{ goalKey: n }`
+* or null. A function that throws or returns a non-finite number is skipped.
+*/
+function computeGoalValues(goals, e) {
+	if (!goals) return null;
+	let out = null;
+	for (const [key, def] of Object.entries(goals)) {
+		if (!("event" in def) || typeof def.value !== "function" || def.event !== e.name) continue;
+		if (def.source !== void 0 && def.source !== e.source) continue;
+		if (def.where && !Object.entries(def.where).every(([k, v]) => e.props[k] === v)) continue;
+		try {
+			const v = def.value(e);
+			if (typeof v === "number" && Number.isFinite(v)) {
+				out ??= {};
+				out[key] = v;
+			}
+		} catch (err) {
+			logRateLimited(`goal:${key}`, `goal "${key}": value function threw`, err);
+		}
+	}
+	return out;
+}
+export { computeGoalValues, defineGoals, matchesPageviewGoal, serializeGoals };

package/dist/config/index.d.ts

@@ -0,0 +1,3 @@
+import { EvolveConfig, ResolvedConfig, RouteConfig, defineConfig, resolveConfig } from "./config.js";
+import { EventGoal, GoalDefinition, GoalEvent, GoalWindow, Goals, PageviewGoal, defineGoals, serializeGoals } from "./goals.js";
+export { type EventGoal, type EvolveConfig, type GoalDefinition, type GoalEvent, type GoalWindow, type Goals, type PageviewGoal, type ResolvedConfig, type RouteConfig, defineConfig, defineGoals, resolveConfig, serializeGoals };

package/dist/config/index.js

@@ -0,0 +1,3 @@
+import { defineConfig, resolveConfig } from "./config.js";
+import { defineGoals, serializeGoals } from "./goals.js";
+export { defineConfig, defineGoals, resolveConfig, serializeGoals };

package/dist/core/assign.d.ts

@@ -0,0 +1,35 @@
+import { BundlePayload, CodePair } from "@next-evolve/protocol";
+type Variant = {
+  id: string;
+  w: number;
+};
+/** Picks a variant id for r ∈ [0, 1) proportionally to weight (w > 0 only). */
+export declare function weightedPick(variants: readonly Variant[], r: number): string;
+/**
+ * A draw in [0, 1) for a key, e.g. `<exp>:t` (traffic) and `<exp>:v` (variant).
+ * `Math.random` fits too (it ignores the key).
+ */
+export type Draw = (key: string) => number;
+/**
+ * Deterministic draws for one visitor: the same `evolve_id` and experiment give
+ * the same assignment on every request, so concurrent first requests (a link
+ * prefetch and the click that follows) can't assign different variants.
+ * FNV-1a with a murmur3 finalizer; uniform enough for traffic splits, not crypto.
+ */
+export declare function visitorDraw(anonId: string): Draw;
+export type Assignment = {
+  /** Pairs for the variant code (unsorted; `encodeCode` sorts). */
+  pairs: CodePair[];
+  /** Assignments to write back to `evolve_a`. */
+  assigned: Map<string, string>;
+  /** Whether `assigned` differs from the cookie that came in. */
+  changed: boolean;
+};
+/**
+ * Assigns a visitor to the experiments on `path` (spec §6.3). Pure: no I/O.
+ * Sticky: an active assignment is kept. Completed experiments render their
+ * winner and aren't counted. Cookie entries for experiments no longer in the
+ * bundle are pruned.
+ */
+export declare function assign(bundle: BundlePayload, path: string, cookie: ReadonlyMap<string, string>, rand: Draw): Assignment;
+export {};

package/dist/core/assign.js

@@ -0,0 +1,104 @@
+import "./cookies.js";
+// src/core/assign.ts
+/** Picks a variant id for r ∈ [0, 1) proportionally to weight (w > 0 only). */
+function weightedPick(variants, r) {
+	let total = 0;
+	for (const v of variants) if (v.w > 0) total += v.w;
+	let acc = 0;
+	let last = variants[0].id;
+	for (const v of variants) {
+		if (v.w <= 0) continue;
+		acc += v.w / total;
+		last = v.id;
+		if (r < acc) return v.id;
+	}
+	return last;
+}
+/**
+* Deterministic draws for one visitor: the same `evolve_id` and experiment give
+* the same assignment on every request, so concurrent first requests (a link
+* prefetch and the click that follows) can't assign different variants.
+* FNV-1a with a murmur3 finalizer; uniform enough for traffic splits, not crypto.
+*/
+function visitorDraw(anonId) {
+	return (key) => {
+		let h = 2166136261;
+		const s = `${anonId}|${key}`;
+		for (let i = 0; i < s.length; i++) {
+			h ^= s.charCodeAt(i);
+			h = Math.imul(h, 16777619);
+		}
+		h ^= h >>> 16;
+		h = Math.imul(h, 2246822507);
+		h ^= h >>> 13;
+		h = Math.imul(h, 3266489909);
+		h ^= h >>> 16;
+		return (h >>> 0) / 4294967296;
+	};
+}
+/**
+* Assigns a visitor to the experiments on `path` (spec §6.3). Pure: no I/O.
+* Sticky: an active assignment is kept. Completed experiments render their
+* winner and aren't counted. Cookie entries for experiments no longer in the
+* bundle are pruned.
+*/
+function assign(bundle, path, cookie, rand) {
+	const { experiments, routes } = bundle.routing;
+	const assigned = /* @__PURE__ */ new Map();
+	let changed = false;
+	for (const [exp, v] of cookie) if (experiments[exp]) assigned.set(exp, v);
+	else changed = true;
+	const pairs = [];
+	for (const exp of routes[path] ?? []) {
+		const e = experiments[exp];
+		if (!e) continue;
+		if (e.status === "completed") {
+			pairs.push({
+				exp,
+				var: e.winner,
+				counted: false
+			});
+			continue;
+		}
+		const a = assigned.get(exp);
+		if (a === "x") {
+			pairs.push({
+				exp,
+				var: e.control,
+				counted: false
+			});
+			continue;
+		}
+		if (a !== void 0 && e.variants.some((v) => v.id === a && v.w > 0)) {
+			pairs.push({
+				exp,
+				var: a,
+				counted: true
+			});
+			continue;
+		}
+		changed = true;
+		if (rand(`${exp}:t`) >= e.traffic) {
+			assigned.set(exp, "x");
+			pairs.push({
+				exp,
+				var: e.control,
+				counted: false
+			});
+			continue;
+		}
+		const v = weightedPick(e.variants, rand(`${exp}:v`));
+		assigned.set(exp, v);
+		pairs.push({
+			exp,
+			var: v,
+			counted: true
+		});
+	}
+	return {
+		pairs,
+		assigned,
+		changed
+	};
+}
+export { assign, visitorDraw, weightedPick };

package/dist/core/bots.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Returns a detector: `isbot` + empty user agent + configured `extraPatterns`
+ * (regex sources, case-insensitive). Bots get `ev_0` and no cookies.
+ */
+export declare function createBotDetector(extraPatterns?: readonly string[]): (ua: string | null | undefined) => boolean;

package/dist/core/bots.js

@@ -0,0 +1,25 @@
+import { isbot } from "isbot";
+// src/core/bots.ts
+/** Unfurlers and tools `isbot` may not flag; all served control and never counted. */
+const EXTRA = [
+	/whatsapp/i,
+	/telegrambot/i,
+	/chrome-lighthouse/i,
+	/headlesschrome/i,
+	/vercelbot/i,
+	/claude-user/i
+];
+/**
+* Returns a detector: `isbot` + empty user agent + configured `extraPatterns`
+* (regex sources, case-insensitive). Bots get `ev_0` and no cookies.
+*/
+function createBotDetector(extraPatterns = []) {
+	const extra = [...EXTRA, ...extraPatterns.map((p) => new RegExp(p, "i"))];
+	return (ua) => {
+		if (!ua?.trim()) return true;
+		if (isbot(ua)) return true;
+		for (const re of extra) if (re.test(ua)) return true;
+		return false;
+	};
+}
+export { createBotDetector };

package/dist/core/constants.d.ts

@@ -0,0 +1,3 @@
+/** Request headers the proxy sets for dynamic-mode routes. */
+export declare const HEADER_CODE = "x-evolve-a";
+export declare const HEADER_PATH = "x-evolve-path";