@preprio/toolkit 0.6.0-alpha.0 → 0.6.0-alpha.10

package/README.md

@@ -225,7 +225,9 @@ Codegen's default client-preset output works as is; `documentMode: 'string'` wor
 
 `personalized` is `true` when the queried fields contain segment variants or A/B tests, at any depth. Use it to decide whether a page can be served statically.
 
-To serve pages from the cache until you publish, set `revalidate: false` and call `revalidateTag('prepr')` from a Prepr publish webhook. With `revalidate` unset, the installed Next version's fetch caching default applies.
+To serve pages from the cache until you publish, set `revalidate: false` and call `revalidateTag('prepr')` from a Prepr publish webhook. With `revalidate` unset, the installed Next version's fetch caching default applies. With Cache Components, a webhook can refresh only the pages showing the changed item instead: see [Refreshing on publish](#refreshing-on-publish).
+
+Tags you pass per query in `init.next.tags` are added to the client's `cacheTags`, never in place of them.
 
 In preview, pass `preview: true`: queries skip the cache and stega markers stay in text for click-to-edit. They are always stripped from URL-like fields.
 
@@ -233,11 +235,11 @@ Custom headers go in two places. Client-level `headers` (`createPreprClient({ ur
 
 #### Personalization with Cache Components
 
-With [Cache Components](https://nextjs.org/docs/app/getting-started/cache-components) (`cacheComponents: true`), a personalized page is still served from the cache: what never varies and every A/B test are in the static shell, and only the parts that differ per segment stream in. You keep your own query and your own components.
+With [Cache Components](https://nextjs.org/docs/app/getting-started/cache-components) (`cacheComponents: true`), a personalized page is still served from the cache, whole: every variant of every A/B test and personalization group is in the prerendered page, and each page view's decision shows the visitor's variant before the page paints. Nothing streams, and no default variant shows first to be swapped out. You keep your own query and your own components.
 
 **Do you need this?** Only if your pages are cached. A page that renders per request already gets this visitor's variants from `query(..., { personalize: true })`; render the result as is and skip this section.
 
-A normal page needs three changes:
+A normal page needs two changes, plus the [proxy](#the-proxy):
 
 ```tsx
 import { PreprStack } from '@preprio/toolkit/nextjs/graphql';
@@ -261,14 +263,10 @@ export default async function Page({
   const slug = (await params).slug?.join('/') || '/';
   const data = await getPage(slug);
 
-  // 2. Ask which variants this visitor gets. Do not await it.
-  const decisions = prepr.decide(PageDocument, { slug }, { from: data });
-
-  // 3. Render the list through PreprStack instead of directly.
+  // 2. Render the list through PreprStack instead of directly.
   return (
     <PreprStack
       items={data.Page.content}
-      decisions={decisions}
       render={(items, { index }) => <Sections items={items} offset={index} />}
     />
   );
@@ -288,7 +286,6 @@ Because `render` runs per block, a position counted inside `Sections` (`items.ma
 // After
 <PreprStack
   items={data.Page.content}
-  decisions={decisions}
   render={(items, { index }) => <Sections items={items} offset={index} />}
 />
 
@@ -308,11 +305,11 @@ A group takes one position, whichever variant shows. A group that shows nothing
 | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
 | One page-builder list (`content`, `sections`, `stack`)                      | One `PreprStack` around it.                                                                       |
 | Personalized lists inside sections (cards, buttons, models in a section)    | Nothing. They are narrowed down with the section they sit in.                                     |
-| Several lists (hero, body, sidebar)                                         | One `PreprStack` per list, all with the same `decisions`.                                         |
+| Several lists (hero, body, sidebar)                                         | One `PreprStack` per list.                                                                        |
 | A personalized list outside any list you already wrap (e.g. `Page.buttons`) | Its own `PreprStack`.                                                                             |
 | Data used outside rendering (`generateMetadata`, JSON-LD)                   | `resolveVariants(data)` gives the default variants and A.                                         |
 | Impression tracking for Prepr's metrics                                     | `trackVariants` on `PreprStack`; see [Impressions and conversions](#impressions-and-conversions). |
-| No personalization on a page                                                | Nothing to change. `PreprStack` renders it statically and `decide()` sends no request.            |
+| No personalization on a page                                                | Nothing to change. `PreprStack` renders it as is and the proxy sends no request.                  |
 
 ##### Impressions and conversions
 
@@ -321,7 +318,7 @@ Prepr's tracking pixel counts impressions of an element carrying `data-prepr-var
 Opt in with `trackVariants`, and `PreprStack` puts the key on the section each personalized and A/B variant renders:
 
 ```tsx
-<PreprStack items={data.Page.content} decisions={decisions} trackVariants render={…} />
+<PreprStack items={data.Page.content} trackVariants render={…} />
 ```
 
 For variants nested inside a section (cards, buttons, models), and outside Next.js, spread `preprVariantProps(item)` on the element that shows the item:
@@ -335,62 +332,94 @@ Conversions stay your choice: put `data-prepr-variant-event` (or `data-prepr-var
 - Keys are added after the page hydrates; the pixel picks them up then. Each item of a variant tags the element it renders, in order. A variant that renders a different number of elements than it has items (a section with several root elements, or one rendering nothing) tags only its first element.
 - With `trackVariants`, each variant sits in a `display: contents` wrapper. It takes no box, but CSS child combinators (`>`) and `:first-child` from the stack's parent no longer reach the sections.
 - An element that already has `data-prepr-variant-key` keeps it, so existing manual tagging keeps working.
-- Tagging yourself (with your own `_context { variant_key }` or `preprVariantProps`)? Skip the tag when `render` gets `placeholder: true`: that render is the default variant standing in until the visitor's variant of a segment group streams in, and the pixel counts anything with a key that appears on screen, however briefly.
-
-  ```tsx
-  render={(items, { index, placeholder }) => (
-    <Sections items={items} offset={index} tagVariants={!placeholder} />
-  )}
-  ```
-
-- A hidden A/B variant never scrolls into view, so it records no impression.
+- `trackVariants` tags only the variant that is shown, once it is shown. A section holding a personalized list (a logo strip whose logos vary) gets the key of the variant it shows. Do not tag stack sections yourself (with your own `_context { variant_key }` or `preprVariantProps`): that puts a key on every variant in the page, including the invisible default that holds its space while the decision is on its way, and Prepr's pixel counts any tagged element in view, invisible or not.
 
-##### A/B tests
+##### The proxy
 
-`PreprStack` renders both variants of an A/B test in the static shell and shows the visitor's one before first paint; A is the default, also for crawlers. The visitor's bucket comes from a cookie set in your middleware. Prepr assigns the bucket, once per visitor, and only on pages that have an A/B test:
+One call in `proxy.ts` gives `PreprStack` what it needs: the visitor's Prepr headers and customer id, and each page view's decision: the visitor's variant of every A/B test and personalization group on a page, in one Prepr request. Only the first load of a URL by a visitor waits for it; see [How each visitor gets their variant](#how-each-visitor-gets-their-variant). Tell it which query each URL renders; most sites route every page through one query:
 
 ```ts
 // proxy.ts
-const response = createPreprMiddleware(request, { preview });
-await resolvePreprBucket(request, response, {
-  url: process.env.PREPR_GRAPHQL_URL!,
-  preview,
-  onlyIf: () => prepr.hasAbTests(PageDocument, { slug }),
+import { createPreprProxy } from '@preprio/toolkit/nextjs/graphql';
+
+const handlePrepr = createPreprProxy({
+  client: prepr,
+  // URL → the query that page renders with `variants: true`; null for non-CMS URLs.
+  page: (url) => ({
+    document: PageDocument,
+    variables: { slug: url.pathname },
+  }),
+  preview: process.env.PREPR_ENV === 'preview',
 });
-return response;
-```
-
-Sites without A/B tests leave this out. Under a strict Content-Security-Policy, pass `nonce` to `PreprStack`.
-
-##### Personalized content above the fold
 
-A segment group streams in: the default variant shows first, then this visitor's variant replaces it. Below the fold nobody sees that. In the hero they do, so for the blocks on screen before the visitor scrolls, decide in the proxy instead:
+export function proxy(request: NextRequest) {
+  return handlePrepr(request); // add your own cookies or headers to this response
+}
+```
 
 ```tsx
-<PreprStack items={data.Page.content} decisions={decisions} aboveTheFold={1} render={…} />
+// app/layout.tsx, once: decides every client-side navigation
+import { PreprPersonalizationSwitch } from '@preprio/toolkit/nextjs';
+
+<PreprPersonalizationSwitch />;
 ```
 
+Deriving the decision query from `PageDocument` needs Prepr's schema, which a fresh server instance downloads before its first decision. Build the decision query ahead of time instead and pass it as `decision`: the codegen plugin (see [Using your own GraphQL client](#using-your-own-graphql-client)) writes it next to your query, and the proxy sends it as is.
+
 ```ts
-// proxy.ts, after createPreprMiddleware
-await prepr.resolveDecisions(
-  request,
-  response,
-  PageDocument,
-  { slug },
-  {
-    // Only pages whose personalized content is above the fold need it.
-    onlyIf: () => slug === '/',
-  },
-);
+import { PageDecisionQuery } from './gql/prepr-queries';
+
+page: (url) => ({
+  document: PageDocument,
+  decision: PageDecisionQuery, // no schema download at runtime
+  variables: { slug: url.pathname },
+}),
 ```
 
-`PreprStack` puts every variant of those blocks' segment groups in the cached page, and the A/B switch script shows the variant the proxy decided before first paint: nothing on screen changes. `resolveDecisions` forwards the visitor's headers (customer id, UTM parameters, IP, HubSpot id) to Prepr and stores the answer in the `prepr_decisions` cookie.
+API routes, `/_next/` and URLs whose last segment has a file extension (`/logo.png`, but also `/docs/v1.2`) are skipped. A decision request for any other URL `page` maps to a query sends one decision query; a page without groups gets an empty answer. Pass `onlyIf: (request) => boolean` to skip Prepr for some requests, such as crawlers, which then get the default variants. In preview it also sends the editor through the [draft route](#preview) first. `createPreprMiddleware` and `preprDraftRedirect` stay exported for proxies that need them separately; decision requests are answered by `createPreprProxy` only.
+
+##### A/B tests
+
+A/B tests go through the same decision as segment groups: both variants are in the prerendered page, hidden until the page view's decision shows the visitor's one. Prepr assigns a variant per experiment, from the visitor's customer id and that experiment's split, so the decision is the only reliable source; one stored bucket per visitor cannot follow a 20/80 and a 50/50 test at once. A is the default, also for crawlers and when Prepr cannot be asked. Pass `bucket` to `PreprStack` only when the route already knows it. Under a strict Content-Security-Policy, pass `nonce` to `PreprStack`.
+
+##### How each visitor gets their variant
+
+Every page view is decided, and its personalized sections paint with the visitor's variant. Decisions are kept per URL in the visitor's `prepr_decisions` cookie, which the proxy and the browser both read and write (see **Reuse** below); nothing is reused from a prefetch, the router cache or another URL's view.
 
-- It asks Prepr once per visit, not per page view: later requests reuse the stored decision unless something arrives that can change the segment (UTM parameters, a first visit, a segment forced in preview). Pass `reuse: false` to ask on every request. A visitor who joins a segment mid-visit sees it from the next request that asks.
-- That request is uncached, so its time depends on how far your functions run from Prepr: deploy them in the region closest to your visitors and to Prepr, and use `onlyIf` to limit it to pages that need it. Pages without segment groups are skipped after a cached check (the same one `hasAbTests` uses).
-- Without a decision (the lookup failed or took longer than `timeoutMs`, default 1000), the default variant shows.
-- The page carries the HTML of every variant of those groups, and images in hidden variants still download.
-- An item with a segment group nested inside it keeps streaming; only groups at the top level of the list are decided in the proxy.
+- **Page loads.** The page is the same for every visitor and comes from the cache. When the cookie holds no decision for the URL, the proxy asks Prepr before sending it (one request, at most `timeoutMs`) and puts the answer in the cookie; otherwise the page passes straight through. An inline script at the start of each `PreprStack` reads the cookie and shows the visitor's variants before the page paints. So only a visitor's first load of each personalized URL waits for Prepr, on the server, where the browser keeps showing the previous page instead of an empty section. Pages without personalization are remembered by the proxy and never wait.
+- **Client-side navigations.** When the visitor hovers over a link (or presses it, on touch devices), `PreprPersonalizationSwitch` asks the proxy for the target page's decision. A click whose decision is in, which hovering and the cookie mostly ensure, goes through at once; one without (a quick tap, a link reached by keyboard) waits for it, so the new page always paints with the visitor's variants. Links to pages without personalization never wait. Prefetches still bring the page itself; only the decision is fetched.
+- **Never the default first.** Until a view's decision is in, its personalized sections are not shown: the default variant keeps its space, invisible, so the page does not move when the visitor's variant appears (only by any difference in height). The default variant only shows when it is the decision: for visitors in none of the segments, for requests `onlyIf` skips, and when Prepr does not answer within `timeoutMs` (default 1000). Navigations started from code to a URL without a decision ask for one when the page opens; its personalized sections appear when it arrives.
+- **Reuse.** Back and Forward show a page as this tab last showed it, at once, without asking Prepr. Any other view of a URL the cookie holds a decision for shows it at once too: under 10 seconds old without asking again, since Prepr needs a few seconds to process a visitor's activity anyway; up to 30 minutes old while a new decision is asked for in the background. When that one differs, it changes only the sections still below the screen; a section the visitor can see, or has scrolled past, keeps its variant for that view, so nothing they are reading is swapped or moves under them. The next view shows the new decision. A page without personalization answers with no groups, which is trusted for an hour with no background check, so links to it cost nothing; when that page renders personalization by then (published since), it asks at once. A URL with other UTM parameters is another view; a failed answer is kept for 10 seconds and never replaces a real one.
+- **"Right" means what Prepr knows when the visitor clicks.** Prepr assigns segments from the visitor's tracked activity. If it has not yet processed the pixel event of the previous page view, the decision cannot include it, and the visitor sees that segment from a later page view.
+- **Costs.** The page carries the HTML of every variant, and an item with groups nested inside it once per combination of their variants. `render` gets `defaultVariant`: give `priority` images only to the default variant and `loading="lazy"` to the others, or the browser downloads every variant's hero image. Every page load with personalization, and every link hovered or pressed (also a press that turns into a scroll), is at most one decision request when this tab has no fresh decision for that URL, answered from Prepr's cache when other visitors had the same answer.
+- Without JavaScript, visitors see the default variants.
+
+##### Deploying
+
+Pages are sent without waiting for Prepr; only the personalized sections wait for their decision, and most of that time is spent at Prepr, in two steps:
+
+- **Who is the visitor?** For a visitor Prepr has not seen before, it first works out their segments, which takes a few hundred milliseconds on pages with segment groups. A returning visitor is resolved at once.
+- **The answer.** Prepr's CDN caches each decision per page, segment set and A/B bucket, and shares it between visitors who get the same. A cached answer takes tens of milliseconds; working one out takes most of a second, once per page and combination until Prepr's cache drops it.
+
+Under steady traffic most answers come from that cache. Your deployment adds the rest:
+
+- **Region.** Run your functions, the proxy included, in the region closest to your visitors and to Prepr.
+- **Keep connections open.** Node.js closes idle connections after a few seconds. On the Node.js runtime, give the client a `fetch` that keeps them longer; this affects only the client's own requests:
+
+  ```ts
+  import { Agent } from 'undici';
+
+  const keepAlive = new Agent({ keepAliveTimeout: 60_000 });
+  export const prepr = createPreprClient({
+    url: process.env.PREPR_GRAPHQL_URL!,
+    fetch: (input, init) =>
+      fetch(input, { ...init, dispatcher: keepAlive } as RequestInit),
+  });
+  ```
+
+- **Instances.** On Vercel, Fluid Compute reuses a function instance, and its open connections, across requests, so under steady traffic the connection stays warm. Each fresh instance pays the setup on its first request; keep instances warm with your platform's settings if your traffic is low.
+- **No schema at runtime.** Pass the codegen plugin's decision query as `decision` (see [The proxy](#the-proxy)), so a fresh instance does not download Prepr's schema before its first decision.
+- **Timeout.** When Prepr does not answer within `timeoutMs` (default 1000), the personalized sections show the default variants, with nothing swapped in later. It caps how long a first page load waits for Prepr.
 
 ##### Preview
 
@@ -405,17 +434,84 @@ const draft = preprDraftRedirect(request, { preview });
 if (draft) return draft;
 ```
 
-Outside preview both do nothing (the route answers 404). Keep the route out of your proxy `matcher`, or pass its path as `route` when it lives elsewhere. Inside the Prepr editor, browsers that refuse the draft cookie get the cached page instead, so keep a publish webhook calling `revalidateTag('prepr')`.
+Outside preview both do nothing (the route answers 404). Keep the route out of your proxy `matcher`, or pass its path as `route` when it lives elsewhere. Inside the Prepr editor, browsers that refuse the draft cookie get the cached page instead, so keep a publish webhook (below) in place.
+
+##### Refreshing on publish
+
+`revalidateTag('prepr')` refreshes every Prepr page on every publish. To refresh only the pages that show the changed item, tag each cached page with its items and let a Prepr webhook revalidate the item's tag.
+
+1. **Tag the page with its items.** Add `tagItems: true` to the query inside `'use cache'`. The entry gets a `prepr:<_id>` tag for every item in the result, at any depth; with `variants: true` that is every variant's items, so a change to any variant reaches the page.
+
+   ```tsx
+   async function getPage(slug: string) {
+     'use cache';
+     const { data } = await prepr().query(
+       GetPageBySlugDocument,
+       { slug },
+       { variants: true, tagItems: true },
+     );
+     return data;
+   }
+   ```
+
+   With your own client, call `cacheTag(...preprCacheTags(data))` inside `'use cache'` instead.
+
+2. **New items are covered too.** A new item is in no cached result yet, so `tagItems` also tags two kinds of query with their model's `prepr:model:<model>` tag, which a publish of any item of that model revalidates:
+   - list queries (`Posts { items { … } }`), so a new post joins the list;
+   - lookups that found nothing (`Page(slug: "new")` returning `null`), so publishing that page replaces the cached "not found".
+
+   Other pages that depend on which items exist (a sitemap, a count) can add the tag themselves:
+
+   ```ts
+   import { cacheTag } from 'next/cache';
+   import { preprModelTag } from '@preprio/toolkit/nextjs/graphql';
+
+   cacheTag(preprModelTag('Post')); // the model's name in Prepr or its GraphQL type
+   ```
+
+   The model name is compared without case, spaces or punctuation, so `'Blog post'` (what webhooks send) and `BlogPost` (the GraphQL type) give the same tag. A model whose API ID was renamed away from its name does not match.
+
+3. **Add the webhook route.**
+
+   ```ts
+   // app/api/prepr/webhook/route.ts
+   import { createPreprWebhookRoute } from '@preprio/toolkit/nextjs';
+
+   export const POST = createPreprWebhookRoute({
+     secret: process.env.PREPR_WEBHOOK_SECRET,
+   });
+   ```
+
+   Keep the route out of your proxy `matcher`.
+
+4. **Create the webhook in Prepr.** Under **Settings → Webhooks**, add `https://<your-site>/api/prepr/webhook` with the events `content_item.published`, `content_item.unpublished`, `content_item.deleted` and `content_item.invalidated`, plus `asset.changed`, `asset.deleted` and `schema.changed`. Other events are acknowledged and ignored, so subscribing to more does no harm. Save, then copy the webhook's **ID** into `PREPR_WEBHOOK_SECRET`: Prepr signs every request with it.
+
+The route checks the `Prepr-Signature` header (an HMAC-SHA256 of the body, keyed with the webhook ID, as hex or base64) and answers 401 to a missing or wrong signature, or to a request older than five minutes. A valid event revalidates:
+
+| Tag                   | When                                                                                              | Reaches                                                       |
+| --------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `prepr:<id>`          | `content_item.published`, `.unpublished`, `.deleted`, `.invalidated`; `asset.changed`, `.deleted` | pages showing that item or asset                              |
+| `prepr:model:<model>` | `content_item.published`, `.unpublished`, `.deleted`                                              | list queries, lookups that found nothing, pages tagged by you |
+| `prepr:any`           | the same events as `prepr:<id>`                                                                   | pages with more items than Next.js's tag limit                |
+| `prepr:schema`        | `schema.changed`                                                                                  | the schema the client rewrites queries with                   |
+
+Draft edits (`content_item.changed`, `.created`), visitor and segment events revalidate nothing: they change no published page.
+
+Revalidation uses `revalidateTag(tag, { expire: 0 })`, so the next request after a publish gets the new page. Pass `profile: 'max'` to serve the old page once more while the new one renders in the background.
+
+Next.js accepts at most 128 tags per `cacheTag()` call. A page with more items is tagged `prepr:any` instead (`PREPR_ANY_ITEM_TAG`), so it refreshes on every event, as with `revalidateTag('prepr')`. The response lists the revalidated tags, which Prepr shows on the webhook's detail page.
+
+`tagItems` makes that query skip the Data Cache: a Data Cache entry carries only the client's `cacheTags`, so after an item tag is revalidated, the `'use cache'` function would re-run against the stale response. The `'use cache'` entry is the cache. The client's `cacheTags` still apply to the entry, so `revalidateTag('prepr')` keeps refreshing everything. `tagItems` needs Next.js 16 and throws outside a `'use cache'` function.
 
 <details>
 <summary>How it works</summary>
 
 - **`variants: true`** adds `personalize: false` to every personalizable field in your query, at any depth, and selects each item's `_context`. The client learns which fields are personalizable from one schema introspection request per client, kept in the Data Cache.
-- **`decide()`** sends your query cut down to the lists that hold segment groups on this page (`from: data`), selecting only `_context`, with the visitor's headers and never cached. Prepr decides from everything the middleware forwards: customer profile, UTM parameters, visitor IP, HubSpot id. A page without segment groups makes no request.
-- **`PreprStack`** renders items that never vary in the static shell. Each segment group, and each item with a segment group nested inside it, gets its own `<Suspense>` boundary: the default variant is the fallback and this visitor's variant streams in. A group with no default variant still gets its place. A failed decision falls back to the defaults.
-- **A/B variants** are both in the HTML, each in a `display: contents` wrapper; an inline script (and a layout effect after in-app navigation) shows the bucket from the cookie. A hidden variant never becomes visible, so the tracking pixel records no impression for it.
+- **Decisions** send your query cut down to the lists that hold segment groups, selecting only `_context`, with the visitor's headers and never cached. Prepr decides from everything the middleware forwards: customer profile, UTM parameters, visitor IP, HubSpot id. A page without segment groups makes no request. `prepr.decide()` does the same inside a render, for rendering variants yourself with `resolveVariants`; `PreprStack` does not need it.
+- **`PreprStack`** renders every variant of each segment group, and each item with groups nested inside it once per combination of their variants, in `display: contents` wrappers that stay hidden until the view's decision marks one to show. A group with no default variant still gets its place.
+- **A/B variants** are both in the HTML and picked by the same decision as segment groups. A hidden variant never becomes visible, so the tracking pixel records no impression for it.
 - **`hasAbTests`** sends your query without its leaf fields and no visitor headers, so Prepr's CDN caches it, and reads the answer from the `Vary` header. Answers are reused for a minute.
-- **Tags carry over.** The client's `'prepr'` fetch tag applies to the `'use cache'` entry, so `revalidateTag('prepr')` refreshes it without a `cacheTag()` call.
+- **Tags carry over.** The client's `'prepr'` fetch tag applies to the `'use cache'` entry, so `revalidateTag('prepr')` refreshes it without a `cacheTag()` call. `tagItems` adds a tag per item; see [Refreshing on publish](#refreshing-on-publish).
 - **Outside `'use cache'`, set `revalidate`** on the client (`false` or seconds). Otherwise a query outside both `'use cache'` and `<Suspense>` fails the build with "uncached data was accessed outside of `<Suspense>`".
 
 </details>
@@ -424,6 +520,102 @@ Outside preview both do nothing (the route answers 404). Keep the route out of y
 
 Do not catch and swallow errors from `query` without [`unstable_rethrow`](https://nextjs.org/docs/app/api-reference/functions/unstable_rethrow): Next.js signals dynamic rendering by throwing from inside `fetch`, and the client passes those signals through.
 
+#### Using your own GraphQL client
+
+Everything the toolkit's client does for personalization is two query rewrites and one helper. Use them with any client: Apollo, urql, or plain `fetch`.
+
+1. **Variants query** (same for every visitor, cache it): `toVariantsQuery(query, schema)`.
+2. **Decision query** (per visitor, never cached, with the visitor's Prepr headers): `toDecisionQuery(query, schema, { from: variantsData })`, then `decisionsFrom(data)`.
+3. **Render** with `PreprStack` (Next.js) or `resolveVariants(data, { decisions, bucket })` anywhere.
+
+The rewrites need to know which fields take `personalize`: `loadPreprSchema(url)` fetches that once and keeps it in memory.
+
+```ts
+import {
+  decisionsFrom,
+  loadPreprSchema,
+  resolveVariants,
+  toDecisionQuery,
+  toVariantsQuery,
+} from '@preprio/toolkit/graphql';
+
+const url = process.env.PREPR_GRAPHQL_URL!;
+const schema = await loadPreprSchema(url);
+
+async function post(
+  query: string,
+  variables: object,
+  headers: HeadersInit = {},
+) {
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', ...headers },
+    body: JSON.stringify({ query, variables }),
+  });
+  const json = await res.json();
+  if (!res.ok || json.errors)
+    throw new Error(`Prepr GraphQL request failed (${res.status})`);
+  return json.data;
+}
+
+const variables = { slug: '/' };
+const page = await post(toVariantsQuery(PAGE_QUERY, schema), variables); // cacheable
+
+const decisionQuery = toDecisionQuery(PAGE_QUERY, schema, { from: page });
+const decisions = decisionQuery
+  ? decisionsFrom(await post(decisionQuery, variables, visitorPreprHeaders))
+  : new Map();
+
+const content = resolveVariants(page.Page.content, { decisions, bucket });
+```
+
+`visitorPreprHeaders` are the headers the middleware forwards (`getPreprHeaders()` in Next.js); `bucket` is the visitor's A/B bucket, when you know it; leave it out and A/B tests use the decision too (see below).
+
+With Apollo, parse the strings once and use them like any document:
+
+```ts
+import { gql } from '@apollo/client';
+
+const PageVariants = gql(toVariantsQuery(PAGE_QUERY, schema));
+const { data: page } = await client.query({ query: PageVariants, variables });
+
+const decisionQuery = toDecisionQuery(PAGE_QUERY, schema, { from: page });
+const decisions = decisionQuery
+  ? decisionsFrom(
+      (
+        await client.query({
+          query: gql(decisionQuery),
+          variables,
+          context: { headers: visitorPreprHeaders },
+          fetchPolicy: 'no-cache', // per visitor: never from Apollo's cache
+        })
+      ).data,
+    )
+  : new Map();
+```
+
+**At build time with graphql-codegen.** The plugin writes both queries per named query into a file, so nothing is rewritten and no schema is loaded at runtime:
+
+```ts
+// codegen.ts
+generates: {
+  'src/gql/prepr-queries.ts': {
+    plugins: ['@preprio/toolkit/graphql/codegen'],
+  },
+},
+```
+
+```ts
+import {
+  GetPageBySlugDecisionQuery,
+  GetPageBySlugVariantsQuery,
+} from './gql/prepr-queries';
+```
+
+Only named queries with personalizable fields get exports; two queries with the same name fail the run. The generated decision query asks about every personalizable list. When you have the variants result at hand, `toDecisionQuery(query, schema, { from })` is smaller and markedly faster for visitors Prepr has not seen before.
+
+A decision query without `from` also returns the visitor's variant of each A/B test, per experiment and its split; `from` limits it to the lists with segment groups. Otherwise pass a known bucket to `resolveVariants`.
+
 ### Image loader
 
 Prepr's stream CDN resizes at the edge. Routing `next/image` through the bundled loader makes Next request the exact width it needs, instead of pulling the full-resolution original and re-encoding it through `/_next/image`.
@@ -819,12 +1011,25 @@ Each wrapper exposes the same five helpers, differing only in how they reach the
 | `cacheTags` (Next.js)  | `['prepr']`                       | Tags on cacheable fetches.                                                                                       |
 | `revalidate` (Next.js) | unset                             | `next.revalidate` on cacheable fetches.                                                                          |
 
-`query(document, variables?, options?)` takes a query string, a `TypedDocumentString` or a `DocumentNode`, and resolves to `{ data, personalized }`. Per-query options: `headers`, `init`, `fetch`, plus `personalize` (framework versions) and `event` (Nuxt, SvelteKit, Astro). A request carrying per-query headers or `init.headers` is `no-store`; client-level `headers` are not.
+`query(document, variables?, options?)` takes a query string, a `TypedDocumentString` or a `DocumentNode`, and resolves to `{ data, personalized }`. Per-query options: `headers`, `init`, `fetch`, plus `personalize` (framework versions), `tagItems` (Next.js 16, inside `'use cache'`) and `event` (Nuxt, SvelteKit, Astro). A request carrying per-query headers or `init.headers` is `no-store`; client-level `headers` are not.
 
 Import `PreprError` from the same subpath as the client when checking `instanceof`: CommonJS entry points do not share classes. `error.code` works from anywhere.
 
 `isPersonalizedResponse(response)`, exported from every entry point, reads the same verdict from a response fetched with your own client. It does not need `graphql`.
 
+For your own GraphQL client (see [Using your own GraphQL client](#using-your-own-graphql-client)), every `/graphql` subpath also exports:
+
+| Function                                                   | Returns                                                                                |
+| ---------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `loadPreprSchema(url, { fetch? })`                         | What the rewrites need from your schema, loaded once per URL. Failures are not cached. |
+| `toVariantsQuery(query, schema)`                           | The variants query as a string: what `variants: true` sends.                           |
+| `toDecisionQuery(query, schema, { from?, topLevelOnly? })` | The per-visitor decision query as a string, or `null` when there is nothing to decide. |
+| `decisionsFrom(data)`                                      | Decisions from a decision query's `data`, for `resolveVariants` or `PreprStack`.       |
+| `preprCacheTags(data)`                                     | `prepr:<_id>` for every item in a result, or `['prepr:any']` past 128 items.           |
+| `preprModelTag(model)`                                     | `prepr:model:<model>`, for list pages.                                                 |
+
+`@preprio/toolkit/graphql/codegen` is a graphql-codegen plugin that writes `<Name>VariantsQuery` and `<Name>DecisionQuery` for every named query with personalizable fields.
+
 ### Token helpers
 
 Exported from every entry point, including the core.
@@ -847,6 +1052,10 @@ The toolbar. Takes the props returned by `getToolbarProps`, and renders nothing
 <PreprToolbar {...toolbarProps} />
 ```
 
+#### `PreprPersonalizationSwitch`
+
+From `@preprio/toolkit/nextjs`. Gets each client-side navigation's decision in before the click: when the visitor hovers over a same-site link (or presses it, on touch devices), it asks `createPreprProxy` for the target page's decision. A click whose decision is not in yet waits for it (see [How each visitor gets their variant](#how-each-visitor-gets-their-variant)). Mount it once in the root layout, so links on pages without a `PreprStack` are covered too. Links to other sites and links that open a new tab or download are left alone. The decision requests are answered by `createPreprProxy` only. Takes no props and renders nothing.
+
 #### `PreprPreview`
 
 From `@preprio/toolkit/react`. The framework-free equivalent of `PreprToolbar`: same preview runtime, with the router binding left to you. Renders nothing.

package/dist/astro/{chunk-3UVUDDNY.js → chunk-CG2QBHNU.js}

@@ -1,5 +1,5 @@
 // src/version.ts
-var VERSION = "0.6.0-alpha.0";
+var VERSION = "0.6.0-alpha.10";
 
 // src/core/features.ts
 function isEnabled(config) {