next-evolve 0.3.3 → 0.3.4

package/docs/api.md

@@ -0,0 +1,238 @@
+# API reference
+
+The package has six entry points. Server-only ones import `server-only`, so importing them from a client component fails the build.
+
+| Import                        | Where it runs                                             |
+| ----------------------------- | --------------------------------------------------------- |
+| `next-evolve`                 | Server components: regions and static-mode pages          |
+| `next-evolve/config`          | Anywhere: `defineConfig`, `defineGoals`                   |
+| `next-evolve/server`          | Server: route handlers, `evolve.track`, `evolve.identify` |
+| `next-evolve/client`          | Browser: `<EvolveScript />`, `track`, `identify`          |
+| `next-evolve/proxy`           | `proxy.ts` / `middleware.ts` (Node runtime)               |
+| `next-evolve/instrumentation` | `instrumentation.ts`                                      |
+
+## `next-evolve`
+
+### `optimizable(Component, schema)`
+
+```ts
+function optimizable<P, S extends z.ZodObject>(
+  component: ComponentType<P>,
+  schema: S,
+): OptimizableComponent<P, S>;
+```
+
+Marks a component as optimizable. `schema` is a Zod 4 object listing the props Evolve may change. Every schema key must be a prop the component accepts, with a compatible type, or it fails to compile. Constraints (`min`, `max`, `enum`, `url()`…) become the dashboard's form validation. `.meta({ label: "Headline" })` labels a field. Returns a thin wrapper; your component isn't modified.
+
+### `<Optimizable id component props />`
+
+```tsx
+<Optimizable id="hero" component={Hero} props={{ title: "Ship faster", cta: "Start free" }} />;
+```
+
+| Prop        |                                                                                                         |
+| ----------- | ------------------------------------------------------------------------------------------------------- |
+| `id`        | Region id, unique per site: `/^[a-z0-9][a-z0-9-]{0,39}$/`                                               |
+| `component` | A component returned by `optimizable()`                                                                 |
+| `props`     | Control props. Fields with schema defaults are optional; non-schema props pass through to every variant |
+
+A server component (async). It renders the variant the proxy chose, or control. It never throws because of Evolve: a missing bundle, an unknown variant or props that fail the schema all render control. In development it warns once when it renders without Evolve context (the page isn't under `app/[evolve]/` and the route isn't a dynamic-mode route in `evolve.config.ts`).
+
+On a page's first render in a process it registers the region (id, JSON Schema of the props, control props, path) with the cloud, in the background.
+
+With `cacheComponents: true`, wrap it in `<Suspense>`.
+
+### `withEvolve(Page, { path })`
+
+Wraps a static-mode page under `app/[evolve]/<route>/page.tsx`. Reads the variant code from the `[evolve]` segment (a malformed code is a 404) and makes it available to every `<Optimizable>` on the page. `path` is the public path (`"/"`, `"/pricing"`). `init` writes this for you.
+
+### `evolveStaticParams()`
+
+`generateStaticParams` for static-mode pages. Prerenders control only (`ev_0`), so builds need no network. Variants render on first request and are then cached.
+
+### `evolveMetadata(path, base?)`
+
+`generateMetadata` for static-mode pages. `base` is your metadata object or function. Sets `alternates.canonical` to `path` and `robots: { index: false, follow: true }` on variant renders.
+
+A static-mode page as `init` writes it:
+
+```tsx
+export const dynamicParams = true;
+export const generateStaticParams = evolveStaticParams;
+export const revalidate = 3600;
+export const generateMetadata = evolveMetadata("/", { title: "Acme" });
+export default withEvolve(Home, { path: "/" });
+```
+
+### `getOptimizableMeta(component)`
+
+Returns `{ schema, jsonSchema, schemaHash, keys }` for an optimizable component, or `null`. For tooling and tests.
+
+## `next-evolve/config`
+
+### `defineConfig(config)`
+
+```ts
+import { defineConfig } from "next-evolve/config";
+
+export default defineConfig({
+  routes: { "/": { mode: "static" }, "/pricing": { mode: "dynamic" } },
+});
+```
+
+Validates and returns the config; throws on mistakes. All options are in [configuration.md](configuration.md).
+
+### `defineGoals(goals)`
+
+Validates and returns the goals. See [goals-and-attribution.md](goals-and-attribution.md).
+
+## `next-evolve/server`
+
+### `createEvolveHandler({ config, goals })`
+
+```ts
+// app/api/evolve/[...evolve]/route.ts
+import { createEvolveHandler } from "next-evolve/server";
+import evolveConfig from "@/evolve.config";
+import goals from "@/evolve.goals";
+
+export const { GET, POST } = createEvolveHandler({ config: evolveConfig, goals });
+export const maxDuration = 60;
+```
+
+Serves the routes under `/api/evolve/` (see [HTTP routes](#http-routes)). Keep `maxDuration = 60` so aggregation fits on serverless hosts.
+
+### `evolve.track(name, options?)`
+
+```ts
+import { evolve } from "next-evolve/server";
+
+await evolve.track("project_created", { userId: user.id });
+```
+
+Writes an event to your database. Never throws. Options:
+
+| Option      | Default                                             |                                                                                     |
+| ----------- | --------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `userId`    | —                                                   | Your user id. Links the event to experiments through `identify`                     |
+| `anonId`    | the visitor's `evolve_id` cookie (inside a request) | The visitor id                                                                      |
+| `value`     | —                                                   | A number, used by goals without their own `value`                                   |
+| `props`     | —                                                   | Any JSON object up to 2 KB (larger props are dropped, the event is kept)            |
+| `source`    | `"server"`                                          | A label goals can filter on, e.g. `"stripe"`                                        |
+| `ts`        | now                                                 | Event time (`Date`, ISO string or ms)                                               |
+| `dedupeKey` | —                                                   | Stored once; a second event with the same key is ignored (use the webhook event id) |
+
+### `evolve.identify(userId, { anonId? })`
+
+Links the visitor (the `evolve_id` cookie, or `anonId`) to your user id, so events with that `userId` (on other devices, or from your server) count for that visitor's experiments. The first link for a visitor wins. Never throws. Call it after sign-up or sign-in.
+
+## `next-evolve/client`
+
+### `<EvolveScript />`
+
+Put it once in the root layout's `<body>`. About 1.6 KB gzipped, no dependencies, not needed to show a variant. On every route it sends a page view and one exposure per counted region; on clicks (forms: on submit) of elements with `data-evolve-goal="<event>"` it sends that event. It batches every 2 seconds and on page hide, to `/api/evolve/collect` on your own origin. It does nothing under automation (`navigator.webdriver`).
+
+### `track(name, props?)` and `identify(userId)`
+
+Browser versions of the server calls. Prefer `evolve.identify()` on the server.
+
+## `next-evolve/proxy`
+
+### `createEvolveProxy(config, { buildBundle })`
+
+```ts
+// proxy.ts (Next 16)
+import { createEvolveProxy } from "next-evolve/proxy";
+import buildBundle from "./.evolve/bundle.generated";
+import evolveConfig from "./evolve.config";
+
+export const proxy = createEvolveProxy(evolveConfig, { buildBundle });
+export const config = { matcher: ["/", "/pricing", "/(ev_.*)"] };
+```
+
+On Next 15.5 use `middleware.ts`, `export const middleware = …`, and add `runtime: "nodejs"` to `config`. The matcher must cover every route in `evolve.config.ts` plus `/(ev_.*)`.
+
+### `applyEvolve(config, req, event, { buildBundle })`
+
+For an existing proxy. Returns a response for Evolve routes and `/ev_*` paths, or `null` for everything else:
+
+```ts
+import { applyEvolve, evolveReady } from "next-evolve/proxy";
+
+export async function proxy(req: NextRequest, event: NextFetchEvent) {
+  await evolveReady(evolveConfig); // only matters with Vercel Global Config
+  const evolved = applyEvolve(evolveConfig, req, event, { buildBundle });
+  if (evolved) return evolved;
+  // …your own logic
+}
+```
+
+### `evolveReady(config)`
+
+With Vercel Global Config, a fresh instance's first request waits up to 20 ms for one read of the store. Returns `null` when there's nothing to wait for.
+
+## `next-evolve/instrumentation`
+
+### `registerEvolve({ config, goals })`
+
+```ts
+// instrumentation.ts
+export async function register() {
+  if (process.env.NEXT_RUNTIME === "nodejs") {
+    const [{ registerEvolve }, { default: config }, { default: goals }] = await Promise.all([
+      import("next-evolve/instrumentation"),
+      import("./evolve.config"),
+      import("./evolve.goals"),
+    ]);
+    await registerEvolve({ config, goals });
+  }
+}
+```
+
+Registers your goals for the process (goal `value` functions need this), sends the manifest (routes, goals, versions, app URL) to the cloud once per process and, on long-running Node, polls the bundle in the background and keeps it on disk. Never throws.
+
+## CLI
+
+Run with `npx next-evolve <command>`. Reads `.env.local` and `.env` (never overriding variables already set).
+
+| Command                                                                                                                               | What it does                                                                                                                                                                                                                                                                              |
+| ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `init [--key] [--webhook-secret] [--db <url>] [--app-url <url>] [--mode static\|dynamic] [--routes "/ /pricing"] [--yes] [--dry-run]` | Sets Evolve up in this app (see the README). Re-running changes nothing that's already done. `--dry-run` prints the diff and writes, installs, migrates and sends nothing. `--yes` answers every prompt with the default. Without `--db` it offers `DATABASE_URL` / `POSTGRES_URL` if set |
+| `migrate [--url <postgres-url>]`                                                                                                      | Creates or updates the `evolve` schema (default `$EVOLVE_DATABASE_URL`). Run it on every deploy, or after upgrading `next-evolve`                                                                                                                                                         |
+| `pull`                                                                                                                                | Writes the verified bundle to `.evolve/bundle.generated.ts`. Runs as `prebuild`. Never fails the build: without a key or the cloud it keeps the previous file or writes an empty one                                                                                                      |
+| `push`                                                                                                                                | Sends the manifest (routes and goals) now. It's also sent when the app starts                                                                                                                                                                                                             |
+| `connect [--test] [--app-url <url>]`                                                                                                  | Checks the key; `--app-url` registers where the app lives; `--test` asks the cloud to call your sync route (ping) and aggregate route (signed dry run)                                                                                                                                    |
+| `doctor`                                                                                                                              | Checks the setup: Next.js version, env vars, key, database (reachable, migrated), bundle (valid, more than 7 days from expiry, build copy present), proxy matcher, pages, `<EvolveScript />`, cloud → app reachability, CDN. Exits 1 when a check fails                                   |
+| `aggregate [--upload]`                                                                                                                | Asks the cloud what to aggregate, runs it on your local database and prints the result; `--upload` sends it to the cloud. For local development, where the cloud can't reach your app                                                                                                     |
+
+## HTTP routes
+
+All served by `createEvolveHandler` under `/api/evolve/`.
+
+| Route                        | Caller                                                   | Auth                                                                   | Answers                                                                                                                                                        |
+| ---------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `POST /api/evolve/collect`   | `<EvolveScript />`                                       | Same origin only                                                       | `204`. Batches over 32 KB or 50 events, or cross-origin, are refused. Bot user agents, preview sessions and visitors without an `evolve_id` cookie are dropped |
+| `POST /api/evolve/track`     | Your servers, Segment, a CRM                             | `Authorization: Bearer $EVOLVE_TRACK_SECRET`                           | `{ accepted: n }`; `404` when `EVOLVE_TRACK_SECRET` isn't set; `401` wrong bearer; `400` bad body                                                              |
+| `POST /api/evolve/sync`      | Evolve Cloud (bundle changed, or a connection-test ping) | HMAC with `EVOLVE_WEBHOOK_SECRET`, 5-minute clock window, replay check | `202`, then fetches the bundle                                                                                                                                 |
+| `POST /api/evolve/aggregate` | Evolve Cloud                                             | HMAC with `EVOLVE_WEBHOOK_SECRET`; the response is signed too          | Counts and sums. `503` when the database isn't configured or is down; `409` for a replay; `429` while another aggregation runs                                 |
+| `GET /api/evolve/health`     | You, monitoring                                          | None                                                                   | `{ ok, protocol, db }` (`db`: whether a database URL is set)                                                                                                   |
+
+`/api/evolve/track` body:
+
+```json
+{
+  "events": [
+    {
+      "name": "subscription_started",
+      "userId": "u_123",
+      "value": 49,
+      "props": { "plan": "pro" },
+      "source": "segment",
+      "ts": "2026-11-01T12:00:00Z",
+      "dedupeKey": "evt_1"
+    }
+  ]
+}
+```
+
+At most 500 events per call. `name` is required; every other field is optional (as in `evolve.track`). The default `source` is `"webhook"`. The events are written before the response, so a sender that retries on failure won't lose any.

package/docs/concepts.md

@@ -0,0 +1,70 @@
+# Concepts
+
+## The pieces
+
+- **Region:** a component on a page that Evolve may change, rendered with `<Optimizable id="…">`. Its id is unique per site (`a-z`, `0-9`, `-`, up to 40 characters). The component is wrapped with `optimizable(Component, schema)`; the Zod schema lists the props Evolve may set and their limits.
+- **Control:** the props you pass to `<Optimizable props={…}>` in your code. Schema defaults apply.
+- **Variant:** a set of prop overrides made in the dashboard. Variant props are merged over control and validated against the schema; a variant that fails the schema renders control and isn't counted. A started variant can't change (visitors already saw it); pause it and add a new one instead.
+- **Experiment:** one region on one or more paths, 2–6 variants including control, a primary goal (and up to 5 secondary ones), and a traffic share. Two kinds:
+  - **A/B/n test:** a fixed split. Read the result when it's decided.
+  - **Bandit:** Evolve Cloud shifts traffic toward the better arm as data arrives (recomputed at most hourly, on the primary goal).
+- **Goal:** what counts as success, defined in `evolve.goals.ts` (an event or a page view, a window, optional value). See [goals-and-attribution.md](goals-and-attribution.md).
+- **Exposure:** the first time a visitor sees an experiment. The beacon reports it; one row per visitor per experiment in your database.
+
+Limits enforced by the cloud: at most 3 running experiments per path and one live experiment per region.
+
+## How a request is served
+
+1. The **proxy** (`proxy.ts`, or `middleware.ts` on Next 15.5) runs for the routes in `evolve.config.ts`. It reads the **bundle** from memory, picks a variant per running experiment and rewrites (static mode) or tags (dynamic mode) the request. It makes no network call; Evolve's part takes well under a millisecond.
+2. The page renders. `<Optimizable>` looks up the chosen variant's props and renders the component with them, inside a `<div style="display:contents" data-evolve-…>` marker.
+3. `<EvolveScript />` in the browser sends a page view and one exposure per marked region to `/api/evolve/collect` **on your own origin**. Your app writes them to your Postgres.
+4. On a schedule, Evolve Cloud sends a signed **aggregate request** to `/api/evolve/aggregate`. Your app runs SQL on its own database and answers with counts and sums per experiment × variant × goal × day. The cloud computes results (Bayesian; P(beat control), lift, risk) and, for bandits, new weights.
+5. When anything changes (start, pause, new weights), the cloud signs a new bundle and calls `/api/evolve/sync`; your app fetches the bundle. Apps also poll for it every 60 seconds.
+
+## The bundle
+
+The bundle is your site's serving configuration: which experiments run on which paths, their traffic share and weights, and each variant's props. It contains no results, priors, goal logic or plan rules.
+
+- It's signed by Evolve Cloud (Ed25519). The SDK ships the public key and rejects anything that doesn't verify, belongs to another site, or is older than the one it has.
+- It expires 14 days after it was signed. The cloud re-signs every active site's bundle daily. If your app can't reach the cloud, it keeps serving the last bundle until it expires, then serves control.
+- Sources, freshest first: memory, then (Vercel + Global Config) the store, then (long-running Node) a disk cache, then the build-time copy `next-evolve pull` writes to `.evolve/bundle.generated.ts` during `prebuild`.
+
+## Static and dynamic mode
+
+Each route in `evolve.config.ts` has a mode.
+
+|                     | Static (default)                                                         | Dynamic                                                                                       |
+| ------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
+| Page file           | Moved to `app/[evolve]/<route>/page.tsx` and wrapped with `withEvolve()` | Stays where it is                                                                             |
+| What the proxy does | Rewrites `/pricing` to `/<code>/pricing` (the code names the variants)   | Passes the code in a request header                                                           |
+| Caching             | One cached (ISR) render per variant                                      | Rendered per request                                                                          |
+| Use for             | Marketing pages                                                          | Pages that are already dynamic, apps with a top-level `[slug]` route, `cacheComponents: true` |
+
+`init` picks static unless moving the page isn't safe: a top-level dynamic segment (`app/[slug]`), a route group, `force-dynamic`, its own `generateStaticParams`, a `"use client"` page, or a layout shared with child routes. It says which reason applied.
+
+**`cacheComponents: true`** (on in new `create-next-app` projects since Next 16.4) rejects the segment config static mode uses, so `init` uses dynamic mode for every route. Wrap each `<Optimizable>` in `<Suspense>`: the region then streams in after the static shell, and the rest of the page stays prerendered.
+
+Direct requests to `/ev_…` paths return 404; they exist only as rewrite targets. In static mode, `evolveMetadata()` sets the canonical URL to the original path and marks variant renders `noindex`.
+
+`<Optimizable>` is for pages; inside layouts it isn't supported yet.
+
+## Who gets a variant
+
+- **New visitors** on a route with a running experiment get two cookies: `evolve_id` (a random id) and `evolve_a` (their assignments). Both are `HttpOnly`, `SameSite=Lax`, `Secure` on https, and last 365 days by default. A visitor keeps their variant on later visits.
+- **Traffic share:** visitors outside the share see control and aren't counted.
+- **Bots** (by user agent: search engines, AI crawlers, link unfurlers, Lighthouse, headless browsers) always get control, no cookies, and their events are dropped. Add your own patterns with `bots.extraPatterns`.
+- **Consent:** set `consent: (req) => boolean` in `evolve.config.ts`. When it returns `false` the visitor gets control and no cookies.
+- **No bundle** (new site with nothing started, or an expired bundle): control and no cookies.
+- **Preview links** from the dashboard force a variant for one browser session and record nothing.
+- Paused experiments are removed from the bundle; their visitors see control. Completed experiments serve the winner to everyone, uncounted, until you ship it in code and archive the experiment.
+
+## Where things run
+
+| In your app                             | In Evolve Cloud                                 |
+| --------------------------------------- | ----------------------------------------------- |
+| Variant assignment, cookies, bot filter | Experiments, variants, lifecycle                |
+| Event writes to your Postgres           | Statistics, decisions, bandit weights           |
+| Aggregation SQL on your database        | Scheduling aggregates, storing aggregate counts |
+| Bundle verification                     | Signing bundles                                 |
+
+The cloud never connects to your database. See [what-leaves-your-server.md](what-leaves-your-server.md).

package/docs/configuration.md

@@ -0,0 +1,74 @@
+# Configuration and environment variables
+
+## `evolve.config.ts`
+
+```ts
+import { defineConfig } from "next-evolve/config";
+
+export default defineConfig({
+  routes: {
+    "/": { mode: "static" },
+    "/pricing": { mode: "static" },
+    "/features": { mode: "dynamic" },
+  },
+  // everything below is optional; these are the defaults
+  store: "auto",
+  sync: { pollSeconds: 60 }, // 5 in development
+  database: { urlEnv: "EVOLVE_DATABASE_URL" },
+  aggregate: { maxMs: 25_000, statementTimeoutMs: 20_000 },
+  cookies: { maxAgeDays: 365, domain: undefined },
+  consent: undefined, // (req: Request) => boolean
+  bots: { extraPatterns: [] },
+  debug: process.env.NODE_ENV !== "production",
+});
+```
+
+| Option                         |                                                                                                                                                                                                                                                                                                          |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `routes`                       | Pages Evolve may test, by exact path (no wildcards or `[params]`, can't start with `/ev_`). `mode`: `"static"` (the page lives under `app/[evolve]/`, cached per variant) or `"dynamic"` (the page stays put, rendered per request). Add a route here **and** to the proxy matcher; `doctor` checks both |
+| `store`                        | `"auto"` uses Vercel Global Config when its env vars are set, else memory. `"memory"` or `"global-config"` force one                                                                                                                                                                                     |
+| `sync.pollSeconds`             | How often each instance checks for a new bundle (± 10% jitter)                                                                                                                                                                                                                                           |
+| `database.urlEnv`              | Which env var holds the database URL                                                                                                                                                                                                                                                                     |
+| `aggregate.maxMs`              | Time budget for one aggregate request; past it the response is partial and the cloud asks again                                                                                                                                                                                                          |
+| `aggregate.statementTimeoutMs` | Postgres `statement_timeout` per aggregation query                                                                                                                                                                                                                                                       |
+| `cookies.maxAgeDays`           | Lifetime of `evolve_id` and `evolve_a`                                                                                                                                                                                                                                                                   |
+| `cookies.domain`               | Set to `.example.com` to share assignments across subdomains                                                                                                                                                                                                                                             |
+| `consent`                      | Return `false` to serve control and set no cookies (e.g. before cookie consent)                                                                                                                                                                                                                          |
+| `bots.extraPatterns`           | Extra user-agent patterns (case-insensitive regular expressions) treated as bots                                                                                                                                                                                                                         |
+| `debug`                        | Extra logging                                                                                                                                                                                                                                                                                            |
+
+## Environment variables
+
+All server-only.
+
+| Var                       | Needed                  |                                                                                                                                                                                 |
+| ------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `EVOLVE_SECRET_KEY`       | yes (runtime and build) | Site key `evk_live_<site>_<secret>`. Authenticates calls to the cloud                                                                                                           |
+| `EVOLVE_WEBHOOK_SECRET`   | yes                     | `whsec_…`. Verifies the cloud's calls to your app and signs aggregate responses                                                                                                 |
+| `EVOLVE_DATABASE_URL`     | to measure              | Your Postgres. Without it variants serve and nothing is recorded. Use the pooled URL on serverless. Never sent anywhere                                                         |
+| `EVOLVE_TRACK_SECRET`     | optional                | Bearer secret for `POST /api/evolve/track`; the route is off (404) without it                                                                                                   |
+| `EVOLVE_APP_URL`          | off Vercel              | Your public base URL, sent with the manifest so the cloud can reach the sync and aggregate routes. On Vercel production it defaults to `https://$VERCEL_PROJECT_PRODUCTION_URL` |
+| `EVOLVE_CACHE_DIR`        | optional                | Disk cache directory for the bundle on long-running Node (default `os.tmpdir()`)                                                                                                |
+| `EVOLVE_CLOUD_URL`        | no                      | Defaults to `https://api.evolveab.com`                                                                                                                                          |
+| `EVOLVE_GLOBAL_CONFIG`    | optional (Vercel)       | Global Config connection string (read)                                                                                                                                          |
+| `EVOLVE_GLOBAL_CONFIG_ID` | optional (Vercel)       | Store id `ecfg_…` (writes)                                                                                                                                                      |
+| `EVOLVE_VERCEL_API_TOKEN` | optional (Vercel)       | Vercel token that can write the store                                                                                                                                           |
+| `EVOLVE_VERCEL_TEAM_ID`   | optional (Vercel)       | For team-owned stores                                                                                                                                                           |
+
+`init` reuses `DATABASE_URL` or `POSTGRES_URL` if you agree (it writes the value into `EVOLVE_DATABASE_URL`).
+
+Test-only variables (`EVOLVE_UNSAFE_TEST_PUBLIC_KEY`, `EVOLVE_UNSAFE_ALLOW_TEST_KEY`) exist for the SDK's own test suite. Never set them in production: they let a test key sign bundles.
+
+## Cookies
+
+| Cookie      | Value                                                      | Set when                                                |
+| ----------- | ---------------------------------------------------------- | ------------------------------------------------------- |
+| `evolve_id` | Random visitor id                                          | First visit to a tested route with a running experiment |
+| `evolve_a`  | The visitor's assignments (`experiment:variant`, up to 20) | Same, and when an assignment changes                    |
+| `evolve_pv` | A signed preview token                                     | Opening a dashboard preview link (session cookie)       |
+
+All are `HttpOnly`, `SameSite=Lax`, `Path=/`, and `Secure` over https. None is set for bots, before consent, or without a valid bundle.
+
+## Database
+
+`next-evolve migrate` creates a schema named `evolve` with these tables: `exposures` (one row per visitor per experiment), `events`, `identities`, `usage_daily` (tested page views per day), `aggregate_runs` (the last 24 h of aggregate responses, for retries) and `migrations`. Your own tables aren't touched. Rows are kept until you delete them.

package/docs/goals-and-attribution.md

@@ -0,0 +1,81 @@
+# Goals and attribution
+
+## Defining goals
+
+Goals live in `evolve.goals.ts`, in your repo:
+
+```ts
+import { defineGoals } from "next-evolve/config";
+
+export default defineGoals({
+  cta_click: { event: "cta_click", window: "1d" },
+  signup_page: { pageview: "/signup", window: "1d" },
+  docs_read: { pageview: "/docs/*" },
+  activated: { event: "project_created", window: "7d", unit: "user" },
+  pro_signup: { event: "signup", where: { plan: "pro" } },
+  paid: {
+    event: "subscription_started",
+    source: "stripe",
+    window: "30d",
+    value: (e) => e.props.amount as number,
+  },
+});
+```
+
+Keys are `a-z`, `0-9` and `_`, starting with a letter, up to 48 characters. Each goal is either an **event** goal or a **pageview** goal.
+
+| Field       | Applies to | Default      |                                                                                                                                         |
+| ----------- | ---------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `event`     | event      | —            | The event name to count                                                                                                                 |
+| `pageview`  | pageview   | —            | An exact path, or a prefix ending in `*`                                                                                                |
+| `window`    | both       | `"7d"`       | How long after a visitor's first exposure a conversion still counts: `"<n>m"`, `"<n>h"` or `"<n>d"`, at most 365 days                   |
+| `unit`      | both       | `"visitor"`  | `"visitor"` counts per browser; `"user"` counts per identified user across devices (needs `identify`)                                   |
+| `direction` | both       | `"increase"` | `"decrease"` when lower is better                                                                                                       |
+| `source`    | event      | any          | Only events with this `source`                                                                                                          |
+| `where`     | event      | —            | Only events whose props equal these values                                                                                              |
+| `value`     | event      | —            | Makes it a value goal (revenue per visitor instead of conversion rate): a numeric prop path (`"amount"`, `"order.total"`) or a function |
+
+**Value functions run in your app**, when the event is written, and the result is stored with the event. The cloud only learns that the goal has a local value function (`{ kind: "local-fn" }`), never the function. A goal without `value` uses the event's own `value` if it has one.
+
+The goal definitions (not the functions) are sent to the cloud when the app starts, so the dashboard can list them. Changing a goal's definition makes the cloud recount it from the experiment's start.
+
+## Firing events
+
+| From                                  | How                                                                         |
+| ------------------------------------- | --------------------------------------------------------------------------- |
+| A link or button                      | `data-evolve-goal="cta_click"` (fires on click)                             |
+| A form                                | `data-evolve-goal="signup"` on the `<form>` (fires on submit)               |
+| Browser code                          | `track("cta_click", { plan: "pro" })` from `next-evolve/client`             |
+| Server code (actions, route handlers) | `await evolve.track("signup", { userId })` from `next-evolve/server`        |
+| Another service (Segment, a CRM)      | `POST /api/evolve/track` with the bearer secret ([API](api.md#http-routes)) |
+| Stripe                                | `evolve.track` in your Stripe webhook handler ([recipe](stripe.md))         |
+
+Page views are recorded by `<EvolveScript />` automatically, but stored only when a pageview goal matches the path.
+
+## Identity
+
+The visitor's id is the `evolve_id` cookie. Browser events and server events inside a request carry it automatically. Events from elsewhere (webhooks, another device, a background job) only have your user id. Call `evolve.identify(userId)` once when a visitor signs up or signs in to link the two; from then on, events with that `userId` count for the visitor's experiments. The first link for a visitor wins.
+
+## Attribution
+
+For each experiment and goal, Evolve counts, per variant:
+
+- **Units:** visitors (or users, for `unit: "user"`) exposed to the variant. A visitor's variant is the one in their first exposure, and that never changes (intention to treat).
+- **Conversions:** units with at least one matching event in **[first exposure, first exposure + window)**. Events before the exposure don't count.
+- **Value:** the sum of matching events' values per unit, for value goals.
+
+Events match a unit by visitor id, or by user id through `identify`. Bots, visitors outside the traffic share and preview sessions aren't units.
+
+Results are grouped by the day of each unit's first exposure (UTC), so recent days stay "open" until their window has passed. The experiment page says "Window not elapsed for X% of visitors" while conversions may still arrive. Aggregates only count data older than 2 minutes.
+
+The SQL runs in your database, triggered by a signed request from the cloud. What comes back is counts and sums only; see [what-leaves-your-server.md](what-leaves-your-server.md).
+
+## Reading results
+
+The experiment page shows, per goal and variant: units, conversions, rate (or value per unit), lift over control with a 95% interval, P(beat control), P(best) and risk, plus a state:
+
+- **insufficient:** below the minimum visitors or conversions; it estimates how many more visitors per arm it needs.
+- **running:** enough data to compare, no decision yet.
+- **winner / loser:** P(beat control) ≥ 99% with expected loss ≤ 1% (winner), or P(beat control) ≤ 1% (loser).
+
+Arms with no visitors stay out of the comparison. **Recompute** runs an aggregate now (at most once a minute per site).

package/docs/production.md

@@ -0,0 +1,75 @@
+# Going to production
+
+## Checklist
+
+1. **Env vars.** Set these in your host's production environment (they're in `.env.local` after `init`). They're server-only; never prefix them with `NEXT_PUBLIC_`.
+
+   | Var                     |                                                     |
+   | ----------------------- | --------------------------------------------------- |
+   | `EVOLVE_SECRET_KEY`     | `evk_live_…` from the dashboard                     |
+   | `EVOLVE_WEBHOOK_SECRET` | `whsec_…` from the dashboard                        |
+   | `EVOLVE_DATABASE_URL`   | Your production Postgres (pooled URL on serverless) |
+   | `EVOLVE_TRACK_SECRET`   | Only if you use `POST /api/evolve/track`            |
+
+   `EVOLVE_SECRET_KEY` must also be set **at build time**: `prebuild` runs `next-evolve pull`, which bakes the current bundle into the build so a fresh instance serves it before its first fetch.
+
+2. **Migrations.** Run `npx next-evolve migrate` against the production database once, and again after upgrading `next-evolve`. It's safe to run on every deploy, for example in the build command: `next-evolve migrate && next build`.
+
+3. **App URL.** The cloud has to know where your app lives to send the sync webhook and aggregate requests. On Vercel production it's detected (`VERCEL_PROJECT_PRODUCTION_URL`); elsewhere set `EVOLVE_APP_URL=https://your-app.com`, or register it once:
+
+   ```sh
+   npx next-evolve connect --app-url https://your-app.com
+   ```
+
+   It must be a public `https` URL.
+
+4. **Check.** After deploying:
+
+   ```sh
+   npx next-evolve connect --test   # the cloud pings /api/evolve/sync and dry-runs /api/evolve/aggregate
+   npx next-evolve doctor           # everything else
+   ```
+
+   The site's **Connect** page in the dashboard shows the same status: manifest received, bundle fetched, sync webhook, aggregate route, last aggregate. **Run connection test** there does what `connect --test` does.
+
+5. **Firewalls and bot protection.** Evolve Cloud calls `POST /api/evolve/sync` and `POST /api/evolve/aggregate` on your app from servers without fixed IP addresses. If you use a WAF, bot protection or "attack mode" (Vercel Firewall, Cloudflare, …), add a rule that lets `/api/evolve/*` through. The requests are authenticated by their HMAC signature, so the route doesn't need other protection. If the connection test fails with `403` or a challenge page, this is why.
+
+## Hosts
+
+|                             | Vercel                                                                              | Vercel + Global Config                                                  | Node server / Docker (`next start`)                                         |
+| --------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| Fresh instance serves       | the build-time bundle                                                               | the bundle in Global Config (waits ≤ 20 ms), then the build-time bundle | the disk cache, then the build-time bundle                                  |
+| Background refresh          | poll the cloud every 60 s (± 10%) on traffic                                        | read Global Config (10 s cache)                                         | every 60 s, plus on traffic                                                 |
+| When an experiment changes  | the instance that gets the webhook updates at once; others within one poll interval | all instances within ~10 s                                              | the instance that gets the webhook at once; others within one poll interval |
+| Events while the DB is down | dropped (one retry)                                                                 | dropped (one retry)                                                     | buffered, up to 10,000 rows                                                 |
+
+"Within one poll interval" means up to ~66 s after an instance's last check, on its next request (that request is still served the old bundle; the fetch runs in the background).
+
+### Vercel + Global Config (recommended on Vercel)
+
+Without it, the sync webhook reaches one instance and the rest catch up by polling. With a [Global Config](https://vercel.com/docs/edge-config) store, the sync route writes the bundle there and every instance sees it within ~10 s.
+
+1. Create a Global Config store and connect it to the project.
+2. Set `EVOLVE_GLOBAL_CONFIG` (the store's connection string), `EVOLVE_GLOBAL_CONFIG_ID` (`ecfg_…`), `EVOLVE_VERCEL_API_TOKEN` (a Vercel access token that can write the store) and, for a team-owned store, `EVOLVE_VERCEL_TEAM_ID`.
+
+Bundles read from the store are verified like any other. Without the token the store is read-only and the sync route logs so.
+
+### Node server / Docker
+
+`registerEvolve()` (in `instrumentation.ts`) polls in the background and caches the bundle on disk in `os.tmpdir()`, or `EVOLVE_CACHE_DIR`. Mount a volume there if you want restarts to survive a cloud outage. The writer flushes buffered events on `SIGTERM`.
+
+### CDNs
+
+On Vercel the cache keys on the rewritten path, so each variant is cached separately. Elsewhere, the proxy sets `Cache-Control: private, no-store` on tested routes. If a CDN in front of your app ignores that and caches by URL, every visitor gets whichever variant was cached first. Don't cache tested routes at the CDN, or include the `evolve_a` cookie in the cache key.
+
+### Serverless functions
+
+The `/api/evolve/[...evolve]` route exports `maxDuration = 60`. Aggregation stops at 25 s by default (`aggregate.maxMs`) and returns a partial result the cloud follows up on.
+
+## How often results update
+
+The cloud asks your app for aggregates on a schedule set by your plan (every 5–60 minutes, plus a full recount daily; during the alpha the schedule may run only daily) and when you click **Recompute** (at most once a minute). Aggregates count data older than 2 minutes.
+
+## Upgrading
+
+Upgrade with your package manager, run `npx next-evolve migrate`, deploy. The SDK tells the cloud which protocol versions it speaks; the cloud supports the current and the previous one and shows "upgrade required" in the dashboard at least 90 days before dropping one.