next-evolve 0.1.0 → 0.3.1

package/dist/proxy/index.d.ts

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

package/dist/proxy/index.js

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

package/dist/proxy/proxy.d.ts

@@ -15,4 +15,10 @@ export declare const PREVIEW_PARAM = "evolve_preview";
  */
 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;
+export declare function createEvolveProxy(config: EvolveConfig, opts?: EvolveProxyOptions): (req: NextRequest, event: NextFetchEvent) => NextResponse | Promise<NextResponse>;
+/**
+ * With Global Config, an instance's first request waits ≤ 20 ms for one read
+ * (spec §7.8). Returns null when there's nothing to wait for. With an existing
+ * proxy: `await evolveReady(config)` before `applyEvolve(...)`.
+ */
+export declare function evolveReady(config: EvolveConfig, opts?: RuntimeOptions): Promise<void> | null;

package/dist/proxy/proxy.js

@@ -1,10 +1,10 @@
 import { normalizePath, resolveConfig } from "../config/config.js";
-import { assign } from "../core/assign.js";
+import { assign, visitorDraw } 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 { coldStart, 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
@@ -55,10 +55,12 @@ function applyEvolve(config, req, event, opts = {}) {
 			]);
 		} 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);
+			const known = req.cookies.get(ANON_COOKIE)?.value;
+			const anon = known || newAnonId();
+			const a = assign(bundle, path, cookie, opts.random ?? visitorDraw(anon));
 			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 (!known) setCookies.push([ANON_COOKIE, anon]);
 				if (a.changed) setCookies.push([ASSIGN_COOKIE, serializeAssignments(a.assigned)]);
 			}
 		}
@@ -97,7 +99,22 @@ function passThrough(req, code, path) {
 function createEvolveProxy(config, opts = {}) {
 	resolveConfig(config);
 	return function proxy(req, event) {
-		return applyEvolve(config, req, event, opts) ?? NextResponse.next();
+		const ready = evolveReady(config, opts);
+		const run = () => applyEvolve(config, req, event, opts) ?? NextResponse.next();
+		return ready ? ready.then(run) : run();
 	};
 }
-export { PREVIEW_PARAM, applyEvolve, createEvolveProxy };
+/**
+* With Global Config, an instance's first request waits ≤ 20 ms for one read
+* (spec §7.8). Returns null when there's nothing to wait for. With an existing
+* proxy: `await evolveReady(config)` before `applyEvolve(...)`.
+*/
+function evolveReady(config, opts = {}) {
+	try {
+		const store = getBundleStore(resolveConfig(config), opts);
+		return store ? coldStart(store) : null;
+	} catch {
+		return null;
+	}
+}
+export { PREVIEW_PARAM, applyEvolve, createEvolveProxy, evolveReady };

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

@@ -1,9 +1,15 @@
 import { BundlePayload } from "@next-evolve/protocol";
+type Env = Record<string, string | undefined>;
 /**
- * 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.
+ * Bundle for rendering (spec §7.7). Warm: the process-wide store (shared with
+ * the proxy where they run in one process). Cold (empty store, e.g. a fresh
+ * serverless render function): `GET /v1/bundle` through Next's data cache,
+ * tagged `evolve-bundle`, so instances share it and the sync route's
+ * `revalidateTag` drops it. `fresh` pulls uncached, for a variant code the
+ * cached bundle doesn't know yet (a new or preview-only variant).
  */
 export declare function getRenderBundle(opts?: {
   fresh?: boolean;
-}): Promise<BundlePayload | null>;
+  env?: Env;
+}): Promise<BundlePayload | null>;
+export {};

package/dist/react/render-bundle.js

@@ -1,14 +1,43 @@
+import { BUNDLE_TAG } from "../server/sync-route.js";
 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.
+* Bundle for rendering (spec §7.7). Warm: the process-wide store (shared with
+* the proxy where they run in one process). Cold (empty store, e.g. a fresh
+* serverless render function): `GET /v1/bundle` through Next's data cache,
+* tagged `evolve-bundle`, so instances share it and the sync route's
+* `revalidateTag` drops it. `fresh` pulls uncached, for a variant code the
+* cached bundle doesn't know yet (a new or preview-only variant).
 */
 async function getRenderBundle(opts = {}) {
-	const store = getBundleStore({});
+	const env = opts.env ?? process.env;
+	const store = getBundleStore({}, { env });
 	if (!store) return null;
-	if (opts.fresh) await store.refresh();
+	if (opts.fresh) {
+		await store.refresh({ force: true });
+		return store.peek();
+	}
+	const warm = store.peek();
+	if (warm) return warm;
+	const token = await taggedFetch(env);
+	if (token) store.load(token);
 	return store.peek();
 }
+async function taggedFetch(env) {
+	const cloudUrl = env.EVOLVE_CLOUD_URL ?? "https://api.evolveab.com";
+	const key = env.EVOLVE_SECRET_KEY;
+	if (!cloudUrl || !key) return null;
+	try {
+		const res = await fetch(new URL("/v1/bundle", cloudUrl), {
+			headers: { authorization: `Bearer ${key}` },
+			cache: "force-cache",
+			next: { tags: [BUNDLE_TAG] },
+			signal: AbortSignal.timeout(5e3)
+		});
+		if (!res.ok) return null;
+		return (await res.text()).trim() || null;
+	} catch {
+		return null;
+	}
+}
 export { getRenderBundle };

package/dist/server/aggregate-route.d.ts

@@ -0,0 +1,16 @@
+import { ResolvedConfig } from "../config/config.js";
+import { Sql } from "../db/client.js";
+import { ReplayGuard } from "@next-evolve/protocol";
+type Env = Record<string, string | undefined>;
+export type AggregateRouteDeps = {
+  config: ResolvedConfig;
+  env: Env;
+  sql: () => Sql | null;
+  sdkVersion: string;
+  replay?: ReplayGuard;
+  now?: () => number;
+};
+/** Delivery ids seen in the last 10 minutes, shared by every signed cloud → app route. */
+export declare function sharedReplayGuard(): ReplayGuard;
+export declare function handleAggregate(req: Request, deps: AggregateRouteDeps): Promise<Response>;
+export {};

package/dist/server/aggregate-route.js

@@ -0,0 +1,68 @@
+import { runAggregate } from "../aggregate/run.js";
+import { DELIVERY_HEADER, SIGNATURE_HEADER, aggregateRequestSchema, createReplayGuard, isSupportedProtocol, parseSecretKey, signBody, unsupportedProtocolBody, verifyBody } from "@next-evolve/protocol";
+// src/server/aggregate-route.ts
+const MAX_BODY_BYTES = 262144;
+const KEY = Symbol.for("next-evolve.replay");
+/** Delivery ids seen in the last 10 minutes, shared by every signed cloud → app route. */
+function sharedReplayGuard() {
+	const g = globalThis;
+	g[KEY] ??= createReplayGuard();
+	return g[KEY];
+}
+const json = (status, body, headers = {}) => Response.json(body, {
+	status,
+	headers
+});
+async function handleAggregate(req, deps) {
+	const secret = deps.env.EVOLVE_WEBHOOK_SECRET;
+	const site = parseSecretKey(deps.env.EVOLVE_SECRET_KEY ?? "")?.siteId;
+	if (!secret || !site) return json(503, { error: "not_configured" });
+	const body = await req.text();
+	if (Buffer.byteLength(body) > MAX_BODY_BYTES) return json(413, { error: "too_large" });
+	const now = deps.now ?? Date.now;
+	const sig = verifyBody(req.headers.get(SIGNATURE_HEADER), body, secret, { now: Math.floor(now() / 1e3) });
+	if (!sig.ok) return json(401, {
+		error: "invalid_signature",
+		reason: sig.reason
+	});
+	const delivery = req.headers.get(DELIVERY_HEADER) ?? "";
+	if (!(deps.replay ?? sharedReplayGuard()).check(delivery)) return json(409, { error: "replayed" });
+	let parsed;
+	try {
+		parsed = JSON.parse(body);
+	} catch {
+		return json(400, { error: "invalid_json" });
+	}
+	if (!isSupportedProtocol(parsed?.pv)) return json(400, unsupportedProtocolBody());
+	const r = aggregateRequestSchema.safeParse(parsed);
+	if (!r.success) return json(400, { error: "invalid" });
+	if (r.data.site !== site) return json(403, { error: "site_mismatch" });
+	const sql = deps.sql();
+	if (!sql) return json(503, { error: "no_database" });
+	let result;
+	try {
+		result = await runAggregate(sql, r.data, {
+			maxMs: deps.config.aggregate.maxMs,
+			statementTimeoutMs: deps.config.aggregate.statementTimeoutMs,
+			sdkVersion: deps.sdkVersion,
+			now
+		});
+	} catch (e) {
+		console.error("[evolve] aggregate failed", e);
+		return json(503, { error: "database_error" });
+	}
+	if (result.kind === "busy") return json(429, {
+		busy: true,
+		retryAfter: result.retryAfter
+	}, { "retry-after": String(result.retryAfter) });
+	const out = JSON.stringify(result.response);
+	return new Response(out, {
+		status: 200,
+		headers: {
+			"content-type": "application/json",
+			"cache-control": "no-store",
+			[SIGNATURE_HEADER]: signBody(secret, out, Math.floor(now() / 1e3))
+		}
+	});
+}
+export { handleAggregate, sharedReplayGuard };

package/dist/server/collect.d.ts

@@ -32,10 +32,26 @@ export type CollectDeps = {
   config: ResolvedConfig;
   goals: Goals | undefined;
   bundle: () => BundlePayload | null;
+  /**
+   * Fetches the bundle now (see {@link createBundleRefresher}). Called when a
+   * beacon names an experiment/variant the current bundle doesn't know, so a
+   * cold or stale instance doesn't drop an exposure the proxy just assigned.
+   */
+  refreshBundle?: () => Promise<void>;
   isBot: (ua: string | null) => boolean;
   writer: Writer;
   now?: () => Date;
 };
+/**
+ * Wraps a store refresh for collect: at most one fetch per `minIntervalMs` per
+ * instance (forged beacons with made-up ids can't turn into a cloud fetch each),
+ * and never waits longer than `capMs`.
+ */
+export declare function createBundleRefresher(refresh: () => Promise<void>, opts?: {
+  minIntervalMs?: number;
+  capMs?: number;
+  now?: () => number;
+}): () => Promise<void>;
 /** Same-origin check: `Origin` must match the host; without it, `Sec-Fetch-Site` must say so. */
 export declare function isSameOrigin(req: Request): boolean;
 /**

package/dist/server/collect.js

@@ -35,6 +35,26 @@ const collectSchema = z.object({
 	v: z.literal(1),
 	events: z.array(z.unknown()).max(50)
 });
+/**
+* Wraps a store refresh for collect: at most one fetch per `minIntervalMs` per
+* instance (forged beacons with made-up ids can't turn into a cloud fetch each),
+* and never waits longer than `capMs`.
+*/
+function createBundleRefresher(refresh, opts = {}) {
+	const minIntervalMs = opts.minIntervalMs ?? 5e3;
+	const capMs = opts.capMs ?? 2e3;
+	const now = opts.now ?? Date.now;
+	let last = -Infinity;
+	return async () => {
+		if (now() - last < minIntervalMs) return;
+		last = now();
+		let timer;
+		await Promise.race([refresh().catch(() => {}), new Promise((r) => {
+			timer = setTimeout(r, capMs);
+		})]);
+		clearTimeout(timer);
+	};
+}
 /** Same-origin check: `Origin` must match the host; without it, `Sec-Fetch-Site` must say so. */
 function isSameOrigin(req) {
 	const host = req.headers.get("x-forwarded-host") ?? req.headers.get("host");
@@ -81,22 +101,28 @@ async function handleCollect(req, deps) {
 		return r.success ? [r.data] : [];
 	});
 	const now = deps.now?.() ?? /* @__PURE__ */ new Date();
-	const bundle = deps.bundle();
+	let bundle = deps.bundle();
+	const known = (e, v) => {
+		const exp = bundle?.routing.experiments[e];
+		return bundle?.variants[v]?.exp === e && Boolean(exp?.variants.some((x) => x.id === v));
+	};
+	if (deps.refreshBundle && events.some((e) => e.t === "exp" && !known(e.e, e.v))) {
+		await deps.refreshBundle();
+		bundle = deps.bundle();
+	}
 	const exposures = [];
 	const rows = [];
 	let testedPageviews = 0;
 	for (const e of events) switch (e.t) {
-		case "exp": {
-			const v = bundle?.variants[e.v];
-			const exp = bundle?.routing.experiments[e.e];
-			if (v && exp && v.exp === e.e && exp.variants.some((x) => x.id === e.v)) exposures.push({
+		case "exp":
+			if (known(e.e, e.v)) exposures.push({
 				experiment_id: e.e,
 				anon_id: anon,
 				variant_id: e.v,
-				path: normalizePath(e.p)
+				path: normalizePath(e.p),
+				first_at: now
 			});
 			break;
-		}
 		case "pv": {
 			const p = normalizePath(e.p);
 			if ((bundle?.routing.routes[p] ?? []).some((id) => bundle?.routing.experiments[id]?.status === "running") && deps.config.routes.has(p)) testedPageviews++;
@@ -128,4 +154,4 @@ async function handleCollect(req, deps) {
 	deps.writer.usage(utcDay(now), testedPageviews);
 	return 204;
 }
-export { MAX_BATCH_BYTES, MAX_BATCH_EVENTS, collectSchema, handleCollect, isSameOrigin };
+export { MAX_BATCH_BYTES, MAX_BATCH_EVENTS, collectSchema, createBundleRefresher, handleCollect, isSameOrigin };

package/dist/server/handler.d.ts

@@ -7,8 +7,9 @@ export type EvolveHandlerOptions = {
 };
 /**
  * Route handlers for `app/api/evolve/[...evolve]/route.ts`:
- * `POST collect` (beacon), `POST track` (bearer webhook), `GET health`.
- * Sync and aggregate arrive with M3/M4.
+ * `POST collect` (beacon), `POST track` (bearer webhook), `POST aggregate`
+ * (signed cloud request), `POST sync` (signed cloud webhook → pull the
+ * bundle), `GET health`.
  */
 export declare function createEvolveHandler(opts: EvolveHandlerOptions): {
   GET: (req: Request) => Promise<Response>;

package/dist/server/handler.js

@@ -1,18 +1,34 @@
+import { sdkVersion } from "../cloud/manifest.js";
 import { resolveConfig } from "../config/config.js";
 import { serializeGoals } from "../config/goals.js";
 import { createBotDetector } from "../core/bots.js";
 import { logRateLimited } from "../core/log.js";
+import { getSql } from "../db/client.js";
+import { globalConfigSettings, writeGlobalConfig } from "../store/global-config.js";
 import { getBundleStore } from "../store/runtime.js";
-import { handleCollect } from "./collect.js";
+import { handleAggregate } from "./aggregate-route.js";
+import { createBundleRefresher, handleCollect } from "./collect.js";
 import { runtimeWriter, scheduleFlush, setRuntime } from "./runtime.js";
+import { handleSync, revalidateBundle } from "./sync-route.js";
 import { handleTrack } from "./track-route.js";
-import { SUPPORTED_PROTOCOLS } from "@next-evolve/protocol";
+import { SUPPORTED_PROTOCOLS, parseSecretKey } from "@next-evolve/protocol";
 // src/server/handler.ts
+const refreshers = /* @__PURE__ */ new WeakMap();
+/** One rate-limited refresher per store (collect, unknown exposures). */
+function collectRefresher(store) {
+	let r = refreshers.get(store);
+	if (!r) {
+		r = createBundleRefresher(() => store.refresh());
+		refreshers.set(store, r);
+	}
+	return r;
+}
 const notFound = () => Response.json({ error: "not_found" }, { status: 404 });
 /**
 * Route handlers for `app/api/evolve/[...evolve]/route.ts`:
-* `POST collect` (beacon), `POST track` (bearer webhook), `GET health`.
-* Sync and aggregate arrive with M3/M4.
+* `POST collect` (beacon), `POST track` (bearer webhook), `POST aggregate`
+* (signed cloud request), `POST sync` (signed cloud webhook → pull the
+* bundle), `GET health`.
 */
 function createEvolveHandler(opts) {
 	const cfg = resolveConfig(opts.config);
@@ -38,6 +54,7 @@ function createEvolveHandler(opts) {
 						config: cfg,
 						goals: opts.goals,
 						bundle: () => store?.peek() ?? null,
+						...store ? { refreshBundle: collectRefresher(store) } : {},
 						isBot,
 						writer
 					});
@@ -49,6 +66,22 @@ function createEvolveHandler(opts) {
 					goals: opts.goals,
 					writer: runtimeWriter()
 				});
+				case "sync": return await handleSync(req, {
+					env: env(),
+					store: () => getBundleStore(cfg, { env: env() }),
+					onSynced: async (token) => {
+						const gc = globalConfigSettings(cfg.store, env());
+						const site = parseSecretKey(env().EVOLVE_SECRET_KEY ?? "")?.siteId;
+						if (gc && site) await writeGlobalConfig(gc, site, token);
+						await revalidateBundle();
+					}
+				});
+				case "aggregate": return await handleAggregate(req, {
+					config: cfg,
+					env: env(),
+					sql: () => getSql(cfg.databaseUrlEnv, env()),
+					sdkVersion: sdkVersion()
+				});
 				default: return notFound();
 			}
 		} catch (e) {

package/dist/server/sync-route.d.ts

@@ -0,0 +1,28 @@
+import { BundleStore } from "../store/memory.js";
+import { ReplayGuard } from "@next-evolve/protocol";
+type Env = Record<string, string | undefined>;
+/** Cache tag on the render-side bundle fetch (spec §7.7). */
+export declare const BUNDLE_TAG = "evolve-bundle";
+/** At most one refresh per window. */
+export declare const SYNC_MIN_INTERVAL_MS = 5000;
+export type SyncThrottle = {
+  last: number;
+  waiting: Promise<void> | null;
+};
+export declare const createSyncThrottle: () => SyncThrottle;
+export type SyncDeps = {
+  env: Env;
+  store: () => BundleStore | null;
+  /** Runs after the response (`after()` by default). */
+  defer?: (task: () => Promise<void>) => void;
+  /** Called with the new token once a refresh installed one (persist + revalidate). */
+  onSynced?: (token: string) => Promise<void>;
+  replay?: ReplayGuard;
+  throttle?: SyncThrottle;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+};
+export declare function handleSync(req: Request, deps: SyncDeps): Promise<Response>;
+/** Drops cached render-side bundle fetches (and pages that used them). */
+export declare function revalidateBundle(): Promise<void>;
+export {};

package/dist/server/sync-route.js

@@ -0,0 +1,100 @@
+import { logRateLimited } from "../core/log.js";
+import { sharedReplayGuard } from "./aggregate-route.js";
+import { DELIVERY_HEADER, SIGNATURE_HEADER, SUPPORTED_PROTOCOLS, isSupportedProtocol, parseSecretKey, syncWebhookSchema, unsupportedProtocolBody, verifyBody } from "@next-evolve/protocol";
+// src/server/sync-route.ts
+/** Cache tag on the render-side bundle fetch (spec §7.7). */
+const BUNDLE_TAG = "evolve-bundle";
+/** At most one refresh per window. */
+const SYNC_MIN_INTERVAL_MS = 5e3;
+const MAX_BODY_BYTES = 16384;
+const createSyncThrottle = () => ({
+	last: -Infinity,
+	waiting: null
+});
+const THROTTLE = Symbol.for("next-evolve.sync-throttle");
+function sharedThrottle() {
+	const g = globalThis;
+	g[THROTTLE] ??= createSyncThrottle();
+	return g[THROTTLE];
+}
+const json = (status, body) => Response.json(body, { status });
+async function handleSync(req, deps) {
+	const secret = deps.env.EVOLVE_WEBHOOK_SECRET;
+	const site = parseSecretKey(deps.env.EVOLVE_SECRET_KEY ?? "")?.siteId;
+	const store = deps.store();
+	if (!secret || !site || !store) return json(503, { error: "not_configured" });
+	const body = await req.text();
+	if (Buffer.byteLength(body) > MAX_BODY_BYTES) return json(413, { error: "too_large" });
+	const now = deps.now ?? Date.now;
+	const sig = verifyBody(req.headers.get(SIGNATURE_HEADER), body, secret, { now: Math.floor(now() / 1e3) });
+	if (!sig.ok) return json(401, {
+		error: "invalid_signature",
+		reason: sig.reason
+	});
+	if (!(deps.replay ?? sharedReplayGuard()).check(req.headers.get(DELIVERY_HEADER) ?? "")) return json(409, { error: "replayed" });
+	let parsed;
+	try {
+		parsed = JSON.parse(body);
+	} catch {
+		return json(400, { error: "invalid_json" });
+	}
+	if (!isSupportedProtocol(parsed?.pv)) return json(400, unsupportedProtocolBody());
+	const r = syncWebhookSchema.safeParse(parsed);
+	if (!r.success) return json(400, { error: "invalid" });
+	const current = store.current();
+	if (r.data.type === "ping") return json(202, {
+		ok: true,
+		ver: current?.ver ?? null,
+		protocol: { supported: SUPPORTED_PROTOCOLS }
+	});
+	if (r.data.site !== site) return json(403, { error: "site_mismatch" });
+	if (!(!current || r.data.ver > current.ver || r.data.ver === current.ver && r.data.iat > current.iat)) return json(202, {
+		accepted: false,
+		reason: "current"
+	});
+	const work = () => throttledRefresh(store, deps);
+	(deps.defer ?? deferAfter)(work);
+	return json(202, { accepted: true });
+}
+/**
+* Refreshes at most once per {@link SYNC_MIN_INTERVAL_MS}. A call inside the
+* window waits for its end (calls that arrive meanwhile share that refresh),
+* so the last change is always pulled.
+*/
+function throttledRefresh(store, deps) {
+	const t = deps.throttle ?? sharedThrottle();
+	if (t.waiting) return t.waiting;
+	const now = deps.now ?? Date.now;
+	const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+	const wait = Math.max(0, t.last + SYNC_MIN_INTERVAL_MS - now());
+	const run = async () => {
+		if (wait > 0) await sleep(wait);
+		t.waiting = null;
+		t.last = now();
+		const before = store.token();
+		await store.refresh({ force: true });
+		const after = store.token();
+		if (after && after !== before) await (deps.onSynced ?? revalidateBundle)(after);
+	};
+	const p = run().catch((e) => logRateLimited("sync", "sync refresh failed", e));
+	t.waiting = wait > 0 ? p : null;
+	return p;
+}
+async function deferAfter(task) {
+	try {
+		const { after } = await import("next/server");
+		after(task);
+	} catch {
+		task();
+	}
+}
+/** Drops cached render-side bundle fetches (and pages that used them). */
+async function revalidateBundle() {
+	try {
+		const { revalidateTag } = await import("next/cache");
+		revalidateTag(BUNDLE_TAG, { expire: 0 });
+	} catch (e) {
+		logRateLimited("sync:revalidate", "revalidateTag failed", e);
+	}
+}
+export { BUNDLE_TAG, SYNC_MIN_INTERVAL_MS, createSyncThrottle, handleSync, revalidateBundle };

package/dist/store/disk.d.ts

@@ -0,0 +1,6 @@
+export declare const defaultDiskDir: () => string;
+export declare const diskPath: (dir: string, site: string) => string;
+/** The cached token, or null (missing or unreadable). */
+export declare function readDisk(path: string): string | null;
+/** Atomic write (temp file + rename). Never throws. */
+export declare function writeDisk(path: string, token: string): void;

package/dist/store/disk.js

@@ -0,0 +1,23 @@
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+// src/store/disk.ts
+const defaultDiskDir = () => tmpdir();
+const diskPath = (dir, site) => join(dir, `evolve-${site}.jws`);
+/** The cached token, or null (missing or unreadable). */
+function readDisk(path) {
+	try {
+		return readFileSync(path, "utf8").trim() || null;
+	} catch {
+		return null;
+	}
+}
+/** Atomic write (temp file + rename). Never throws. */
+function writeDisk(path, token) {
+	const tmp = `${path}.${process.pid}.tmp`;
+	try {
+		writeFileSync(tmp, token, { mode: 384 });
+		renameSync(tmp, path);
+	} catch {}
+}
+export { defaultDiskDir, diskPath, readDisk, writeDisk };

package/dist/store/fetch.d.ts

@@ -12,6 +12,10 @@ export type FetchBundleResult = {
 /**
  * `GET {cloud}/v1/bundle` with the secret key and `If-None-Match` (spec §7.5).
  * Never throws. Verification is the caller's job.
+ *
+ * Uses node:http(s) unless a `fetch` is injected (tests): the render path
+ * refreshes through this too, and inside a static (ISR) render Next's patched
+ * `fetch` turns an uncached call into "dynamic usage" and fails the page.
  */
 export declare function fetchBundle(opts: {
   cloudUrl: string;

package/dist/store/fetch.js

@@ -1,10 +1,16 @@
+import { request } from "node:http";
+import { request as request$1 } from "node:https";
 // src/store/fetch.ts
 /**
 * `GET {cloud}/v1/bundle` with the secret key and `If-None-Match` (spec §7.5).
 * Never throws. Verification is the caller's job.
+*
+* Uses node:http(s) unless a `fetch` is injected (tests): the render path
+* refreshes through this too, and inside a static (ISR) render Next's patched
+* `fetch` turns an uncached call into "dynamic usage" and fails the page.
 */
 async function fetchBundle(opts) {
-	const f = opts.fetch ?? fetch;
+	const f = opts.fetch ?? httpFetch;
 	try {
 		const res = await f(new URL("/v1/bundle", opts.cloudUrl), {
 			headers: {
@@ -36,4 +42,33 @@ async function fetchBundle(opts) {
 		};
 	}
 }
+/** A tiny GET over node:http(s) with fetch's shape (the parts fetchBundle uses). */
+function httpFetch(url, init) {
+	return new Promise((resolve, reject) => {
+		const req = (url.protocol === "https:" ? request$1 : request)(url, {
+			method: "GET",
+			headers: init.headers,
+			signal: init.signal
+		}, (res) => {
+			const chunks = [];
+			res.on("data", (c) => chunks.push(c));
+			res.on("error", reject);
+			res.on("end", () => {
+				const status = res.statusCode ?? 0;
+				const body = Buffer.concat(chunks).toString("utf8");
+				resolve({
+					status,
+					ok: status >= 200 && status < 300,
+					text: async () => body,
+					headers: { get: (n) => {
+						const v = res.headers[n.toLowerCase()];
+						return Array.isArray(v) ? v[0] ?? null : v ?? null;
+					} }
+				});
+			});
+		});
+		req.on("error", reject);
+		req.end();
+	});
+}
 export { fetchBundle };