next-evolve 0.0.0-stage → 0.1.0

package/dist/db/writer.js

@@ -0,0 +1,182 @@
+import { logRateLimited } from "../core/log.js";
+import { isServerless } from "./client.js";
+// src/db/writer.ts
+const CHUNK = 1e3;
+const MAX_BACKOFF_MS = 3e4;
+function createWriter(opts) {
+	const mode = opts.mode ?? (isServerless() ? "serverless" : "node");
+	const flushMs = opts.flushMs ?? 1e3;
+	const flushRows = opts.flushRows ?? 100;
+	const maxBuffer = opts.maxBuffer ?? 1e4;
+	let exposures = [];
+	let events = [];
+	let identities = [];
+	let usage = /* @__PURE__ */ new Map();
+	let timer;
+	let backoffMs = 0;
+	let running = Promise.resolve();
+	const pending = () => exposures.length + events.length + identities.length + usage.size;
+	function schedule(delay) {
+		if (mode !== "node" || timer) return;
+		timer = setTimeout(() => {
+			timer = void 0;
+			flush();
+		}, delay);
+		timer.unref?.();
+	}
+	function added() {
+		if (mode !== "node") return;
+		trim();
+		if (pending() >= flushRows && backoffMs === 0) flush();
+		else schedule(backoffMs || flushMs);
+	}
+	/** Keeps the buffer bounded while the DB is down: the oldest rows go first. */
+	function trim() {
+		let over = pending() - maxBuffer;
+		if (over <= 0) return;
+		logRateLimited("writer:drop", `customer DB unavailable; dropping ${over} buffered rows`);
+		for (const list of [
+			events,
+			exposures,
+			identities
+		]) {
+			const n = Math.min(over, list.length);
+			list.splice(0, n);
+			over -= n;
+		}
+	}
+	async function write(sql, batch) {
+		for (const rows of chunks(batch.exposures)) await sql`insert into evolve.exposures ${sql(rows, "experiment_id", "anon_id", "variant_id", "path")}
+        on conflict do nothing`;
+		for (const rows of chunks(batch.events)) await sql`insert into evolve.events ${sql(rows.map((r) => ({
+			...r,
+			goal_values: r.goal_values && sql.json(r.goal_values),
+			props: r.props && sql.json(r.props)
+		})), EVENT_COLS)}
+        on conflict (dedupe_key) where dedupe_key is not null do nothing`;
+		for (const rows of chunks(batch.identities)) await sql`insert into evolve.identities ${sql(rows, "anon_id", "user_id")} on conflict do nothing`;
+		const days = [...batch.usage].map(([day, n]) => ({
+			day,
+			tested_pageviews: n
+		}));
+		if (days.length) await sql`insert into evolve.usage_daily ${sql(days, "day", "tested_pageviews")}
+        on conflict (day) do update
+        set tested_pageviews = evolve.usage_daily.tested_pageviews + excluded.tested_pageviews`;
+	}
+	function take() {
+		const b = {
+			exposures,
+			events,
+			identities,
+			usage
+		};
+		exposures = [];
+		events = [];
+		identities = [];
+		usage = /* @__PURE__ */ new Map();
+		return b;
+	}
+	function restore(b) {
+		exposures = [...b.exposures, ...exposures];
+		events = [...b.events, ...events];
+		identities = [...b.identities, ...identities];
+		for (const [d, n] of b.usage) usage.set(d, (usage.get(d) ?? 0) + n);
+	}
+	async function flushOnce() {
+		if (pending() === 0) return;
+		const sql = opts.sql();
+		if (!sql) {
+			logRateLimited("writer:nodb", "EVOLVE_DATABASE_URL is not set; events are not stored");
+			take();
+			return;
+		}
+		const batch = take();
+		try {
+			await write(sql, batch);
+			backoffMs = 0;
+		} catch (e) {
+			if (mode === "serverless") try {
+				await write(sql, batch);
+				return;
+			} catch (e2) {
+				logRateLimited("writer:dropped", "customer DB write failed; batch dropped", e2);
+				return;
+			}
+			logRateLimited("writer:retry", "customer DB write failed; will retry", e);
+			restore(batch);
+			trim();
+			backoffMs = Math.min(MAX_BACKOFF_MS, backoffMs ? backoffMs * 2 : flushMs);
+			schedule(backoffMs);
+		}
+	}
+	function flush() {
+		if (timer) {
+			clearTimeout(timer);
+			timer = void 0;
+		}
+		running = running.then(flushOnce, flushOnce);
+		return running;
+	}
+	return {
+		mode,
+		exposures(rows) {
+			if (!rows.length) return;
+			exposures.push(...rows);
+			added();
+		},
+		events(rows) {
+			if (!rows.length) return;
+			events.push(...rows);
+			added();
+		},
+		identities(rows) {
+			if (!rows.length) return;
+			identities.push(...rows);
+			added();
+		},
+		usage(day, n) {
+			if (n <= 0) return;
+			usage.set(day, (usage.get(day) ?? 0) + n);
+			added();
+		},
+		pending,
+		flush
+	};
+}
+const EVENT_COLS = [
+	"ts",
+	"name",
+	"anon_id",
+	"user_id",
+	"value",
+	"goal_values",
+	"props",
+	"source",
+	"path",
+	"dedupe_key"
+];
+function* chunks(rows) {
+	for (let i = 0; i < rows.length; i += CHUNK) yield rows.slice(i, i + CHUNK);
+}
+const WRITERS = Symbol.for("next-evolve.writers");
+/**
+* The process-wide writer for a DB URL variable. On long-running Node it also
+* flushes on SIGTERM so a graceful shutdown doesn't lose buffered rows.
+*/
+function getWriter(sql, key = "EVOLVE_DATABASE_URL") {
+	const g = globalThis;
+	g[WRITERS] ??= /* @__PURE__ */ new Map();
+	let w = g[WRITERS].get(key);
+	if (!w) {
+		const writer = createWriter({ sql });
+		w = writer;
+		g[WRITERS].set(key, writer);
+		if (!isServerless() && typeof process !== "undefined" && process.once) process.once("SIGTERM", () => {
+			writer.flush().finally(() => {
+				if (process.listenerCount("SIGTERM") === 0) process.exit(0);
+			});
+		});
+	}
+	return w;
+}
+export { createWriter, getWriter };

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { OptimizableComponent, OptimizableMeta, getOptimizableMeta, optimizable } from "./react/optimizable.js";
+import { Optimizable, OptimizableProps } from "./react/region.js";
+import { EvolvePageProps, evolveMetadata, evolveStaticParams, withEvolve } from "./react/with-evolve.js";
+import "server-only";
+export { type EvolvePageProps, Optimizable, type OptimizableComponent, type OptimizableMeta, type OptimizableProps, evolveMetadata, evolveStaticParams, getOptimizableMeta, optimizable, withEvolve };

package/dist/index.js

@@ -0,0 +1,5 @@
+import { getOptimizableMeta, optimizable } from "./react/optimizable.js";
+import { Optimizable } from "./react/region.js";
+import { evolveMetadata, evolveStaticParams, withEvolve } from "./react/with-evolve.js";
+import "server-only";
+export { Optimizable, evolveMetadata, evolveStaticParams, getOptimizableMeta, optimizable, withEvolve };

package/dist/instrumentation/index.d.ts

@@ -0,0 +1,23 @@
+import { EvolveConfig } from "../config/config.js";
+import { Goals } from "../config/goals.js";
+export type RegisterEvolveOptions = {
+  config: EvolveConfig;
+  goals?: Goals;
+};
+/**
+ * Call from `instrumentation.ts` `register()`:
+ *
+ *   export async function register() {
+ *     if (process.env.NEXT_RUNTIME === "nodejs") {
+ *       const { registerEvolve } = await import("next-evolve/instrumentation");
+ *       await registerEvolve({ config, goals });
+ *     }
+ *   }
+ *
+ * Registers the goals for this process and pushes the manifest to the cloud
+ * (goals, routes, versions, app URL; spec §8.4), once per process. Never
+ * throws. Background polling and the disk cache arrive with T7.4.
+ */
+export declare function registerEvolve(opts: RegisterEvolveOptions): Promise<void>;
+/** Test helper. */
+export declare function resetRegisterEvolve(): void;

package/dist/instrumentation/index.js

@@ -0,0 +1,39 @@
+import { buildManifest, detectAppUrl } from "../cloud/manifest.js";
+import { pushToCloud } from "../cloud/push.js";
+import { setRuntime } from "../server/runtime.js";
+// src/instrumentation/index.ts
+let registered = false;
+/**
+* Call from `instrumentation.ts` `register()`:
+*
+*   export async function register() {
+*     if (process.env.NEXT_RUNTIME === "nodejs") {
+*       const { registerEvolve } = await import("next-evolve/instrumentation");
+*       await registerEvolve({ config, goals });
+*     }
+*   }
+*
+* Registers the goals for this process and pushes the manifest to the cloud
+* (goals, routes, versions, app URL; spec §8.4), once per process. Never
+* throws. Background polling and the disk cache arrive with T7.4.
+*/
+async function registerEvolve(opts) {
+	if (registered) return;
+	registered = true;
+	try {
+		setRuntime({
+			config: opts.config,
+			goals: opts.goals
+		});
+		const manifest = buildManifest(opts.config, opts.goals, { appUrl: detectAppUrl() });
+		const res = await pushToCloud("/v1/manifest", manifest);
+		if (!res.ok && res.status !== "no_key") console.error(`[evolve] manifest push failed (${res.status})`);
+	} catch (e) {
+		console.error("[evolve] registerEvolve failed", e);
+	}
+}
+/** Test helper. */
+function resetRegisterEvolve() {
+	registered = false;
+}
+export { registerEvolve, resetRegisterEvolve };

package/dist/proxy/index.d.ts

@@ -0,0 +1,2 @@
+import { EvolveProxyOptions, applyEvolve, createEvolveProxy } from "./proxy.js";
+export { type EvolveProxyOptions, applyEvolve, createEvolveProxy };

package/dist/proxy/index.js

@@ -0,0 +1 @@
+export { applyEvolve, createEvolveProxy } from "./proxy.js";

package/dist/proxy/proxy.d.ts

@@ -0,0 +1,18 @@
+import { EvolveConfig } from "../config/config.js";
+import { RuntimeOptions } from "../store/runtime.js";
+import { NextFetchEvent, NextRequest, NextResponse } from "next/server";
+export type EvolveProxyOptions = RuntimeOptions & {
+  /** Random source in [0, 1) (tests). */
+  random?: () => number;
+};
+/** Query parameter carrying a preview token from the dashboard. */
+export declare const PREVIEW_PARAM = "evolve_preview";
+/**
+ * Runs Evolve for one request. Returns a response for Evolve routes and
+ * `/ev_*` paths, or null for everything else (so it composes with an existing
+ * proxy: `return applyEvolve(config, req, event) ?? NextResponse.next()`).
+ * Never throws and never makes a network call on the request path.
+ */
+export declare function applyEvolve(config: EvolveConfig, req: NextRequest, event?: Pick<NextFetchEvent, "waitUntil">, opts?: EvolveProxyOptions): NextResponse | null;
+/** Builds the `proxy` export for `proxy.ts` (Next 16) or `middleware.ts` (Next 15.5, Node runtime). */
+export declare function createEvolveProxy(config: EvolveConfig, opts?: EvolveProxyOptions): (req: NextRequest, event: NextFetchEvent) => NextResponse;

package/dist/proxy/proxy.js

@@ -0,0 +1,103 @@
+import { normalizePath, resolveConfig } from "../config/config.js";
+import { assign } from "../core/assign.js";
+import { createBotDetector } from "../core/bots.js";
+import { HEADER_CODE, HEADER_PATH } from "../core/constants.js";
+import { ANON_COOKIE, ASSIGN_COOKIE, PREVIEW_COOKIE, parseAssignments, serializeAssignments } from "../core/cookies.js";
+import { logRateLimited } from "../core/log.js";
+import { getBundleStore, getSiteIdentity } from "../store/runtime.js";
+import { CONTROL_CODE, encodeCode, newAnonId, verifyPreview } from "@next-evolve/protocol";
+import { NextResponse } from "next/server";
+// src/proxy/proxy.ts
+/** Query parameter carrying a preview token from the dashboard. */
+const PREVIEW_PARAM = "evolve_preview";
+const detectors = /* @__PURE__ */ new WeakMap();
+/**
+* Runs Evolve for one request. Returns a response for Evolve routes and
+* `/ev_*` paths, or null for everything else (so it composes with an existing
+* proxy: `return applyEvolve(config, req, event) ?? NextResponse.next()`).
+* Never throws and never makes a network call on the request path.
+*/
+function applyEvolve(config, req, event, opts = {}) {
+	const t0 = performance.now();
+	const pathname = req.nextUrl.pathname;
+	if (pathname.split("/")[1]?.startsWith("ev_")) return new NextResponse(null, { status: 404 });
+	let cfg;
+	try {
+		cfg = resolveConfig(config);
+	} catch (e) {
+		logRateLimited("config", "invalid evolve config", e);
+		return null;
+	}
+	const path = normalizePath(pathname);
+	const route = cfg.routes.get(path);
+	if (!route) return null;
+	const isStatic = route.mode === "static";
+	let res;
+	try {
+		let isBot = detectors.get(config);
+		if (!isBot) {
+			isBot = createBotDetector(cfg.botPatterns);
+			detectors.set(config, isBot);
+		}
+		const bundle = getBundleStore(cfg, opts)?.peek(event ? (p) => event.waitUntil(p) : void 0) ?? null;
+		let code = CONTROL_CODE;
+		const setCookies = [];
+		const fromQuery = req.nextUrl.searchParams.get(PREVIEW_PARAM);
+		const previewToken = fromQuery ?? req.cookies.get("evolve_pv")?.value;
+		const identity = previewToken ? getSiteIdentity(opts) : null;
+		const preview = previewToken && identity ? verifyPreview(previewToken, identity) : null;
+		if (preview) {
+			code = preview.code;
+			if (fromQuery) setCookies.push([
+				PREVIEW_COOKIE,
+				fromQuery,
+				true
+			]);
+		} else if (bundle && !isBot(req.headers.get("user-agent")) && cfg.consent?.(req) !== false) {
+			const cookie = parseAssignments(req.cookies.get(ASSIGN_COOKIE)?.value);
+			const a = assign(bundle, path, cookie, opts.random ?? Math.random);
+			code = encodeCode(a.pairs);
+			if ((bundle.routing.routes[path] ?? []).some((e) => bundle.routing.experiments[e]?.status === "running")) {
+				if (!req.cookies.get("evolve_id")?.value) setCookies.push([ANON_COOKIE, newAnonId()]);
+				if (a.changed) setCookies.push([ASSIGN_COOKIE, serializeAssignments(a.assigned)]);
+			}
+		}
+		res = isStatic ? rewrite(req, code, path) : passThrough(req, code, path);
+		if (setCookies.length) {
+			const secure = (req.headers.get("x-forwarded-proto") ?? req.nextUrl.protocol.replace(":", "")) === "https";
+			const maxAge = cfg.cookies.maxAgeDays * 86400;
+			for (const [name, value, session] of setCookies) res.cookies.set(name, value, {
+				path: "/",
+				...session ? {} : { maxAge },
+				sameSite: "lax",
+				httpOnly: true,
+				secure,
+				...cfg.cookies.domain ? { domain: cfg.cookies.domain } : {}
+			});
+		}
+	} catch (e) {
+		logRateLimited("proxy", "proxy error; serving control", e);
+		res = isStatic ? rewrite(req, CONTROL_CODE, path) : passThrough(req, CONTROL_CODE, path);
+	}
+	if ((opts.env ?? process.env).VERCEL !== "1") res.headers.set("cache-control", "private, no-store");
+	res.headers.set("server-timing", `evolve;dur=${(performance.now() - t0).toFixed(3)}`);
+	return res;
+}
+function rewrite(req, code, path) {
+	const target = path === "/" ? `/${code}` : `/${code}${path}`;
+	return NextResponse.rewrite(new URL(target + req.nextUrl.search, req.url));
+}
+function passThrough(req, code, path) {
+	const headers = new Headers(req.headers);
+	headers.set(HEADER_CODE, code);
+	headers.set(HEADER_PATH, path);
+	return NextResponse.next({ request: { headers } });
+}
+/** Builds the `proxy` export for `proxy.ts` (Next 16) or `middleware.ts` (Next 15.5, Node runtime). */
+function createEvolveProxy(config, opts = {}) {
+	resolveConfig(config);
+	return function proxy(req, event) {
+		return applyEvolve(config, req, event, opts) ?? NextResponse.next();
+	};
+}
+export { PREVIEW_PARAM, applyEvolve, createEvolveProxy };

package/dist/react/context.d.ts

@@ -0,0 +1,6 @@
+export type EvolveRequestContext = {
+  code: string | null;
+  path: string | null;
+};
+/** Per-request store (React `cache()`), filled by `withEvolve` before the page body renders. */
+export declare const requestContext: () => EvolveRequestContext;

package/dist/react/context.js

@@ -0,0 +1,8 @@
+import { cache } from "react";
+// src/react/context.ts
+/** Per-request store (React `cache()`), filled by `withEvolve` before the page body renders. */
+const requestContext = cache(() => ({
+	code: null,
+	path: null
+}));
+export { requestContext };

package/dist/react/optimizable.d.ts

@@ -0,0 +1,37 @@
+import { ComponentType } from "react";
+import { z } from "zod";
+declare const META: unique symbol;
+export type OptimizableMeta<S extends z.ZodObject = z.ZodObject> = {
+  schema: S;
+  /** JSON Schema of the editable props (dashboard forms; later the AI). Includes `.meta()`. */
+  jsonSchema: Record<string, unknown>;
+  /** sha256 of the canonical JSON Schema; changes when the schema changes. */
+  schemaHash: string;
+  keys: readonly string[];
+};
+export type OptimizableComponent<P extends object, S extends z.ZodObject = z.ZodObject> = ComponentType<P> & {
+  readonly [META]: OptimizableMeta<S>;
+};
+/**
+ * Compile-time check that the schema fits the component: every schema key is a
+ * prop the component accepts, with a compatible type.
+ */
+type SchemaFits<P, O> = [Exclude<keyof O, keyof P>] extends [never] ? O extends Pick<P, keyof O & keyof P> ? unknown : {
+  "schema error": "schema prop types don't match the component's props";
+} : {
+  "schema error": "schema has props the component doesn't accept";
+  keys: Exclude<keyof O, keyof P>;
+};
+/**
+ * Marks a component as optimizable with a Zod schema for the props Evolve may
+ * change. A schema that doesn't fit the component's props fails to compile.
+ * Server-only (the component renders inside `<Optimizable>`).
+ *
+ * ```ts
+ * export default optimizable(Hero, heroSchema);
+ * ```
+ */
+export declare function optimizable<P extends object, S extends z.ZodObject>(component: ComponentType<P>, schema: S & SchemaFits<P, z.output<S>>): OptimizableComponent<P, S>;
+export declare function getOptimizableMeta(c: unknown): OptimizableMeta | null;
+export declare function isRegionId(id: string): boolean;
+export {};

package/dist/react/optimizable.js

@@ -0,0 +1,38 @@
+import { REGION_ID_RE, canonicalJson, sha256Hex } from "@next-evolve/protocol";
+import { createElement } from "react";
+import { z } from "zod";
+// src/react/optimizable.ts
+const META = Symbol.for("next-evolve.optimizable");
+/**
+* Marks a component as optimizable with a Zod schema for the props Evolve may
+* change. A schema that doesn't fit the component's props fails to compile.
+* Server-only (the component renders inside `<Optimizable>`).
+*
+* ```ts
+* export default optimizable(Hero, heroSchema);
+* ```
+*/
+function optimizable(component, schema) {
+	const jsonSchema = z.toJSONSchema(schema, {
+		io: "input",
+		unrepresentable: "any"
+	});
+	const meta = {
+		schema,
+		jsonSchema,
+		schemaHash: sha256Hex(canonicalJson(jsonSchema)),
+		keys: Object.keys(schema.shape)
+	};
+	const Wrapped = ((props) => createElement(component, props));
+	Object.defineProperty(Wrapped, META, { value: meta });
+	Object.defineProperty(Wrapped, "displayName", { value: `Optimizable(${component.displayName ?? component.name ?? "Component"})` });
+	Object.defineProperty(Wrapped, "inner", { value: component });
+	return Wrapped;
+}
+function getOptimizableMeta(c) {
+	return c?.[META] ?? null;
+}
+function isRegionId(id) {
+	return REGION_ID_RE.test(id);
+}
+export { getOptimizableMeta, isRegionId, optimizable };

package/dist/react/region.d.ts

@@ -0,0 +1,17 @@
+import { OptimizableComponent } from "./optimizable.js";
+import { ReactElement } from "react";
+import { z } from "zod";
+/** Control props: the schema's input type (defaults optional) plus the component's other props. */
+export type ControlProps<P extends object, S extends z.ZodObject> = Omit<P, keyof z.output<S>> & z.input<S>;
+export type OptimizableProps<P extends object, S extends z.ZodObject> = {
+  /** Region id, unique per site: /^[a-z0-9][a-z0-9-]{0,39}$/. */
+  id: string;
+  component: OptimizableComponent<P, S>;
+  /** Control props. Variant props are merged over these; schema defaults apply. */
+  props: ControlProps<P, S>;
+};
+/**
+ * Renders the variant of a region chosen by the proxy, or control. Never throws
+ * because of Evolve: any problem renders control. Server component.
+ */
+export declare function Optimizable<P extends object, S extends z.ZodObject>({ id, component, props }: OptimizableProps<P, S>): Promise<ReactElement>;

package/dist/react/region.js

@@ -0,0 +1,127 @@
+import { registerRegion } from "../cloud/regions.js";
+import { HEADER_CODE, HEADER_PATH } from "../core/constants.js";
+import { logRateLimited } from "../core/log.js";
+import { requestContext } from "./context.js";
+import { getOptimizableMeta } from "./optimizable.js";
+import { getRenderBundle } from "./render-bundle.js";
+import { CONTROL_CODE, decodeCode } from "@next-evolve/protocol";
+import { createElement } from "react";
+import { headers } from "next/headers";
+import { unstable_rethrow } from "next/navigation";
+import { after } from "next/server";
+// src/react/region.tsx
+let warnedNoContext = false;
+async function currentCode() {
+	const ctx = requestContext();
+	if (ctx.code) return ctx.code;
+	try {
+		return (await headers()).get(HEADER_CODE);
+	} catch (e) {
+		unstable_rethrow(e);
+		return null;
+	}
+}
+/** The page path this region renders on (static: withEvolve; dynamic: the proxy header). */
+async function currentPath() {
+	const ctx = requestContext();
+	if (ctx.path) return ctx.path;
+	try {
+		return (await headers()).get(HEADER_PATH);
+	} catch (e) {
+		unstable_rethrow(e);
+		return null;
+	}
+}
+/** Region registration (spec §5.2): after the response, deduped per process, errors swallowed. */
+function scheduleRegistration(id, meta, controlProps, path) {
+	if (!path) return;
+	try {
+		after(() => registerRegion({
+			id,
+			jsonSchema: meta.jsonSchema,
+			schemaHash: meta.schemaHash,
+			controlProps,
+			path
+		}));
+	} catch {}
+}
+function findPair(bundle, pairs, region) {
+	for (const p of pairs) {
+		const v = bundle?.variants[p.var];
+		if (v && v.exp === p.exp && v.region === region) return {
+			pair: p,
+			variant: v
+		};
+	}
+	return null;
+}
+/**
+* Renders the variant of a region chosen by the proxy, or control. Never throws
+* because of Evolve: any problem renders control. Server component.
+*/
+async function Optimizable({ id, component, props }) {
+	const meta = getOptimizableMeta(component);
+	if (!meta) {
+		logRateLimited(`optimizable:${id}`, `<Optimizable id="${id}">: component isn't wrapped with optimizable()`);
+		return createElement(component, props);
+	}
+	const editableOf = (o) => {
+		const out = {};
+		for (const k of meta.keys) if (k in o) out[k] = o[k];
+		return out;
+	};
+	const parsedControl = meta.schema.safeParse(editableOf(props));
+	const controlProps = {
+		...props,
+		...parsedControl.success ? parsedControl.data : {}
+	};
+	const control = () => createElement(component, controlProps);
+	const code = await currentCode();
+	scheduleRegistration(id, meta, parsedControl.success ? parsedControl.data : editableOf(props), await currentPath());
+	if (!code) {
+		if (!warnedNoContext && process.env.NODE_ENV !== "production") {
+			warnedNoContext = true;
+			console.warn(`[evolve] <Optimizable id="${id}"> rendered without Evolve context; serving control. Wrap the page with withEvolve() under app/[evolve]/, or use a dynamic route.`);
+		}
+		return control();
+	}
+	if (code === CONTROL_CODE) return control();
+	const pairs = decodeCode(code);
+	if (!pairs || pairs.length === 0) return control();
+	let bundle = await getRenderBundle();
+	let hit = findPair(bundle, pairs, id);
+	const unknown = () => pairs.some((p) => !bundle?.variants[p.var]);
+	if (!hit && unknown()) {
+		bundle = await getRenderBundle({ fresh: true });
+		hit = findPair(bundle, pairs, id);
+	}
+	const marker = (attrs, child) => createElement("div", {
+		style: { display: "contents" },
+		"data-evolve-r": id,
+		...attrs
+	}, child);
+	if (!hit) return unknown() ? marker({ "data-evolve-x": "" }, control()) : control();
+	const { pair, variant } = hit;
+	const attrs = {
+		"data-evolve-e": pair.exp,
+		"data-evolve-v": pair.var
+	};
+	if (!pair.counted) attrs["data-evolve-x"] = "";
+	if (variant.ctrl || Object.keys(variant.props).length === 0) return marker(attrs, control());
+	const parsed = meta.schema.safeParse(editableOf({
+		...props,
+		...variant.props
+	}));
+	if (!parsed.success) {
+		logRateLimited(`variant:${pair.var}`, `variant ${pair.var} of region "${id}" failed its schema; serving control`, parsed.error.issues);
+		return marker({
+			...attrs,
+			"data-evolve-x": ""
+		}, control());
+	}
+	return marker(attrs, createElement(component, {
+		...props,
+		...parsed.data
+	}));
+}
+export { Optimizable };

package/dist/react/render-bundle.d.ts

@@ -0,0 +1,9 @@
+import { BundlePayload } from "@next-evolve/protocol";
+/**
+ * Bundle for rendering. Phase 1 (M1): the process-wide store shared with the
+ * proxy; `fresh` awaits a refetch first. T7.6 adds the tagged fetch for hosts
+ * where render and proxy run in different processes.
+ */
+export declare function getRenderBundle(opts?: {
+  fresh?: boolean;
+}): Promise<BundlePayload | null>;

package/dist/react/render-bundle.js

@@ -0,0 +1,14 @@
+import { getBundleStore } from "../store/runtime.js";
+// src/react/render-bundle.ts
+/**
+* Bundle for rendering. Phase 1 (M1): the process-wide store shared with the
+* proxy; `fresh` awaits a refetch first. T7.6 adds the tagged fetch for hosts
+* where render and proxy run in different processes.
+*/
+async function getRenderBundle(opts = {}) {
+	const store = getBundleStore({});
+	if (!store) return null;
+	if (opts.fresh) await store.refresh();
+	return store.peek();
+}
+export { getRenderBundle };