@preprio/toolkit 0.5.0-rc.2 → 0.6.0-alpha.1

package/README.md

@@ -200,25 +200,326 @@ To skip Prepr for some routes entirely, return early with `NextResponse.next()`
 
 The pixel collects the interaction data that powers personalization and A/B testing. Include it in **all** environments, preview and production alike — the Quick Start layout already does. `PreprTrackingPixel` renders nothing and loads the CDN script on mount, so its position in the tree does not matter.
 
-### With Apollo Client
+### Fetching content
+
+`createPreprClient` sends codegen-typed queries to Prepr and returns Prepr's personalization verdict next to the data. It lives on its own subpath and needs the `graphql` package, which graphql-codegen already installs (otherwise: `npm install graphql`).
 
 ```typescript
-import { getClient } from '@/lib/client';
+import { createPreprClient } from '@preprio/toolkit/nextjs/graphql';
 import { GetPageBySlugDocument } from '@/gql/graphql';
-import { getPreprHeaders } from '@preprio/toolkit/nextjs';
 
-async function getPage(slug: string) {
-  const { data } = await getClient().query({
-    query: GetPageBySlugDocument,
-    variables: { slug },
-    context: { headers: await getPreprHeaders() },
-    fetchPolicy: 'no-cache',
-  });
+const prepr = createPreprClient({ url: process.env.PREPR_GRAPHQL_URL! });
+
+// Same response for every visitor: goes through the Data Cache, tagged 'prepr'.
+const { data } = await prepr.query(GetPageBySlugDocument, { slug });
+
+// This visitor's segment / A-B variant: forwards the Prepr headers, never cached.
+const { data, personalized } = await prepr.query(
+  GetPageBySlugDocument,
+  { slug },
+  { personalize: true },
+);
+```
+
+Codegen's default client-preset output works as is; `documentMode: 'string'` works too.
+
+`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.
+
+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.
+
+Custom headers go in two places. Client-level `headers` (`createPreprClient({ url, headers })`) are sent with every request and keep queries cacheable, so use them for fixed values such as a header your proxy requires. Per-query `headers` (or `init.headers`) may carry per-visitor values, so they make that request `no-store`.
+
+#### 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.
+
+**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:
+
+```tsx
+import { PreprStack } from '@preprio/toolkit/nextjs/graphql';
 
+// 1. Fetch every variant, in a cached function. Same query, one extra option.
+async function getPage(slug: string) {
+  'use cache';
+  const { data } = await prepr.query(
+    PageDocument,
+    { slug },
+    { variants: true },
+  );
   return data;
 }
+
+export default async function Page({
+  params,
+}: {
+  params: Promise<{ slug?: string[] }>;
+}) {
+  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.
+  return (
+    <PreprStack
+      items={data.Page.content}
+      decisions={decisions}
+      render={(items, { index }) => <Sections items={items} offset={index} />}
+    />
+  );
+}
+```
+
+##### Your components: one extra prop
+
+`PreprStack` splits the list into blocks (what never varies, each personalization group, each A/B test) and calls `render` once per block. Each call receives items exactly as a query without personalization would return them: the variant this visitor gets, with every list nested inside an item narrowed down the same way.
+
+Because `render` runs per block, a position counted inside `Sections` (`items.map((item, i) => …)`) starts at 0 in every block. `index` is where the block starts in the whole page; add it, and the first section still owns the `<h1>` and the priority image:
+
+```tsx
+// Before
+<Sections items={data.Page.content} />
+
+// After
+<PreprStack
+  items={data.Page.content}
+  decisions={decisions}
+  render={(items, { index }) => <Sections items={items} offset={index} />}
+/>
+
+// Sections: the only change is `offset + i`
+function Sections({ items, offset = 0 }: { items: Section[]; offset?: number }) {
+  return items.map((item, i) => <Section key={item._id} item={item} position={offset + i} />);
+}
+```
+
+A group takes one position, whichever variant shows. A group that shows nothing to a visitor (only a segment variant, no default) still takes its position: the page is prerendered before anyone's segment is known.
+
+**The one rule:** a `variants: true` result holds every variant. Every list you render from it goes through `PreprStack`, or visitors see all variants at once.
+
+##### Fitting your page
+
+| Your page has…                                                              | Do this                                                                                           |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| 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`.                                         |
+| 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.            |
+
+##### Impressions and conversions
+
+Prepr's tracking pixel counts impressions of an element carrying `data-prepr-variant-key`, and clicks on any `data-prepr-variant-event` element inside it ([Prepr docs](https://docs.prepr.io/personalization/setting-up-personalization#track-impressions-and-conversions)). The client already fetches every variant's key, so you never select `_context { variant_key }` yourself.
+
+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={…} />
+```
+
+For variants nested inside a section (cards, buttons, models), and outside Next.js, spread `preprVariantProps(item)` on the element that shows the item:
+
+```tsx
+<article {...preprVariantProps(card)}>…</article>
+```
+
+Conversions stay your choice: put `data-prepr-variant-event` (or `data-prepr-variant-event="QuoteRequest"`) on the element that counts, for example once in your button component.
+
+- 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.
+
+##### A/B tests
+
+`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:
+
+```ts
+// proxy.ts
+const response = createPreprMiddleware(request, { preview });
+await resolvePreprBucket(request, response, {
+  url: process.env.PREPR_GRAPHQL_URL!,
+  preview,
+  onlyIf: () => prepr.hasAbTests(PageDocument, { slug }),
+});
+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:
+
+```tsx
+<PreprStack items={data.Page.content} decisions={decisions} aboveTheFold={1} render={…} />
+```
+
+```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 === '/',
+  },
+);
+```
+
+`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.
+
+- 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.
+
+##### Preview
+
+Run preview in [draft mode](https://nextjs.org/docs/app/guides/draft-mode), so editors see an edit on the next load instead of the cached page:
+
+```ts
+// app/api/prepr/draft/route.ts
+export const GET = createPreprDraftRoute({ preview });
+
+// proxy.ts, before anything else
+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')`.
+
+<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.
+- **`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.
+- **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>
+
+`examples/nextjs-cache-components` is a runnable version.
+
+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 (`resolvePreprBucket` stores it in a cookie).
+
+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/B tests need no decision query: render both variants and pick the visitor's bucket, as `PreprStack` and `resolvePreprBucket` do, or pass the 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`.
@@ -295,6 +596,19 @@ import { getPreprHeaders } from '@preprio/toolkit/astro';
 const headers = getPreprHeaders(Astro.request.headers);
 ```
 
+Or let the client forward the headers (needs `graphql`, see [Fetching content](#fetching-content)):
+
+```typescript
+import { createPreprClient } from '@preprio/toolkit/astro/graphql';
+
+const prepr = createPreprClient({ url: import.meta.env.PREPR_GRAPHQL_URL });
+const { data } = await prepr.query(
+  GetPageBySlugDocument,
+  { slug },
+  { personalize: true, event: Astro },
+);
+```
+
 `import.meta.env.DEV` is Astro's own dev flag; swap in whatever signal marks preview in your deployment.
 
 The `.astro` components ship as source, compiled by your own Astro/Vite pipeline. They use full-page navigation by default, matching Astro's MPA model — switching segment or variant re-runs the server-rendered output.
@@ -357,6 +671,23 @@ import { getPreprHeadersFromLocals } from '@preprio/toolkit/sveltekit';
 const preprHeaders = getPreprHeadersFromLocals(event.locals);
 ```
 
+Or let the client forward them (needs `graphql`, see [Fetching content](#fetching-content)). Passing the event also routes the request through `event.fetch`:
+
+```typescript
+import { createPreprClient } from '@preprio/toolkit/sveltekit/graphql';
+
+const prepr = createPreprClient({ url: env.PREPR_GRAPHQL_URL });
+
+export const load: PageServerLoad = async (event) => {
+  const { data } = await prepr.query(
+    GetPageBySlugDocument,
+    { slug: event.params.slug },
+    { personalize: true, event },
+  );
+  return { page: data.Page };
+};
+```
+
 The `.svelte` components ship as source (compiled by your own Vite/Svelte pipeline) and mount client-side via `onMount`, so they never run during SSR.
 
 See the runnable example at `examples/sveltekit` for the full source of truth.
@@ -408,6 +739,26 @@ import { getPreprHeadersFromEvent } from '@preprio/toolkit/nuxt';
 const preprHeaders = getPreprHeadersFromEvent(event);
 ```
 
+Or let the client forward them from a server route (needs `graphql`, see [Fetching content](#fetching-content)):
+
+```typescript
+// server/api/page.get.ts
+import { createPreprClient } from '@preprio/toolkit/nuxt/graphql';
+
+const prepr = createPreprClient({ url: useRuntimeConfig().preprGraphqlUrl });
+
+export default defineEventHandler(async (event) => {
+  const { data } = await prepr.query(
+    GetPageBySlugDocument,
+    { slug: getQuery(event).slug },
+    { personalize: true, event },
+  );
+  return data;
+});
+```
+
+`personalize: true` needs the h3 event. During client-side navigation there is none and the query throws `CONTEXT_ERROR`, so run personalized queries in server routes.
+
 The `.vue` components ship as source (compiled by your own Vite/Vue pipeline) and mount client-side via `onMounted`, so they never run during SSR.
 
 See the runnable example at `examples/nuxt` for the full source of truth.
@@ -549,6 +900,38 @@ Each wrapper exposes the same five helpers, differing only in how they reach the
 
 `getPreprUUID()` returning `null` is a useful check when headers seem to be missing — it means the middleware did not cover the route.
 
+### GraphQL client
+
+`createPreprClient(options)` ships on `@preprio/toolkit/graphql` and on each framework's `/graphql` subpath (`@preprio/toolkit/nextjs/graphql`, `/nuxt/graphql`, `/sveltekit/graphql`, `/astro/graphql`). These subpaths need the `graphql` package (`>=16`); nothing else in the toolkit does. The core version takes explicit `headers`; the framework versions add `personalize`.
+
+| Option                 | Default                           | Effect                                                                                                           |
+| ---------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `url`                  | —                                 | Full `https://graphql.prepr.io/<token>` URL. Throws `PreprError` when invalid.                                   |
+| `preview`              | `false`                           | Every query is `no-store`; stega defaults to `'urls'`.                                                           |
+| `stega`                | `'urls'` in preview, else `'all'` | Which strings get stega markers stripped: URL-like keys only, all, or `'none'`.                                  |
+| `fetch`                | global `fetch`                    | Custom fetch. Also accepted per query.                                                                           |
+| `fastlyQuery`          | `false`                           | Send queries as a GET with a `Fastly-Query` header, served by Prepr's edge. Opt-in: undocumented Prepr behavior. |
+| `headers`              | —                                 | Sent with every request. Fixed per client, so queries stay cacheable.                                            |
+| `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.
+
+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`.       |
+
+`@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.
@@ -694,14 +1077,14 @@ createPreprMiddleware(request, response, { preview });
 createPreprPreview({ props, options: { debug: true, locale: 'nl' } });
 ```
 
-| Option                 | Type            | Default       | Description                                                                                                                                                 |
-| ---------------------- | --------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `debug`                | `boolean`       | `false`       | Enable debug logging.                                                                                                                                       |
-| `locale`               | `'en' \| 'nl'`  | auto-detected | UI language. Falls back to the first supported browser language, then `en`.                                                                                 |
-| `features`             | `PreprFeatures` | all enabled   | Which features run. See [Feature flags](#feature-flags).                                                                                                    |
-| `ui`                   | `boolean`       | `true`        | Mount the visible toolbar. See [Headless preview](#headless-preview-no-toolbar-ui).                                                                         |
-| `allowedEditorOrigins` | `string[]`      | `*.prepr.io`  | Exact editor origins allowed to drive this preview, for self-hosted or local editors. Replaces the wildcard. `['*']` accepts any origin — development only. |
-| `autoClean`            | `boolean`       | `true`        | Strip the invisible stega characters from visible text. See [Stega auto-cleaning](#stega-auto-cleaning).                                                    |
+| Option                 | Type            | Default       | Description                                                                                              |
+| ---------------------- | --------------- | ------------- | -------------------------------------------------------------------------------------------------------- |
+| `debug`                | `boolean`       | `false`       | Enable debug logging.                                                                                    |
+| `locale`               | `'en' \| 'nl'`  | auto-detected | UI language. Falls back to the first supported browser language, then `en`.                              |
+| `features`             | `PreprFeatures` | all enabled   | Which features run. See [Feature flags](#feature-flags).                                                 |
+| `ui`                   | `boolean`       | `true`        | Mount the visible toolbar. See [Headless preview](#headless-preview-no-toolbar-ui).                      |
+| `allowedEditorOrigins` | `string[]`      | `*.prepr.io`  | Exact editor origins allowed to drive this preview, for self-hosted editors. Replaces the wildcard.      |
+| `autoClean`            | `boolean`       | `true`        | Strip the invisible stega characters from visible text. See [Stega auto-cleaning](#stega-auto-cleaning). |
 
 `features` and `ui` are independent: `features` decides _what runs_, `ui` decides _whether the toolbar is visible_.
 
@@ -831,6 +1214,10 @@ createPreprPreview({ props, options: { locale: 'nl' } });
 - **Check whether the encoded text sits in a hidden element.** The parent of the encoded text node is what becomes editable, and a parent that renders no box (`display: none`, `visibility: hidden`, the `hidden` attribute) is skipped — it cannot be hovered or clicked. Put `data-prepr-edit-target` on the visible ancestor that should be editable instead. See [Choosing the element that becomes editable](#choosing-the-element-that-becomes-editable).
 - **Inspect the tagged elements**: `document.querySelectorAll('[data-prepr-encoded]')` in the console lists everything edit mode found. An element you expected to be in that list points at one of the two cases above.
 
+### Every variant shows at once
+
+The list came from a `variants: true` query but was rendered directly. Pass it through `PreprStack` (or `resolveVariants`); see [Personalization with Cache Components](#personalization-with-cache-components).
+
 ### Headers not working
 
 - **Middleware setup**: confirm `middleware.ts` sits in the project root (or `src/`) and its matcher covers the route.
@@ -839,7 +1226,7 @@ createPreprPreview({ props, options: { locale: 'nl' } });
 
 ### Segments switch but content does not change
 
-The toolbar sets the segment; your data fetch decides what to do with it. Check that the fetch forwards `getPreprHeaders()` and is not being served from cache — use `cache: 'no-store'`, or Apollo's `fetchPolicy: 'no-cache'`, on personalized queries.
+The toolbar sets the segment; your data fetch decides what to do with it. Check that the fetch forwards `getPreprHeaders()` and is not being served from cache — use `cache: 'no-store'`, or Apollo's `fetchPolicy: 'no-cache'`, on personalized queries. `createPreprClient` with `personalize: true` does both.
 
 ### Build issues
 
@@ -865,7 +1252,7 @@ try {
 }
 ```
 
-Codes: `INVALID_TOKEN`, `MISSING_TOKEN`, `HTTP_ERROR`, `FETCH_ERROR`, `INVALID_RESPONSE`, `CONTEXT_ERROR`.
+Codes: `INVALID_TOKEN`, `MISSING_TOKEN`, `HTTP_ERROR`, `FETCH_ERROR`, `INVALID_RESPONSE`, `CONTEXT_ERROR`, `GRAPHQL_ERROR`, `INVALID_DOCUMENT`.
 
 `getToolbarProps` is the exception — it swallows these and returns an empty segment list, so a bad token cannot crash your app.
 
@@ -963,13 +1350,14 @@ Without it the `<em>` would be the editable element; with it the whole figure is
 
 Runnable examples live in the repository root:
 
-| Example              | What it shows                                                      |
-| -------------------- | ------------------------------------------------------------------ |
-| `examples/nextjs`    | App Router, middleware, Apollo, custom image loader                |
-| `examples/astro`     | Astro middleware and `.astro` components                           |
-| `examples/sveltekit` | `hooks.server.ts`, `+layout.server.ts`, `.svelte` components       |
-| `examples/nuxt`      | `server/middleware`, `useAsyncData`, `.vue` components             |
-| `examples/express`   | Vanilla core — a hand-written adapter for an unsupported framework |
+| Example                            | What it shows                                                      |
+| ---------------------------------- | ------------------------------------------------------------------ |
+| `examples/nextjs`                  | App Router, middleware, `createPreprClient`, custom image loader   |
+| `examples/nextjs-cache-components` | Cache Components: cached page shell, personalized `<Suspense>`     |
+| `examples/astro`                   | Astro middleware and `.astro` components                           |
+| `examples/sveltekit`               | `hooks.server.ts`, `+layout.server.ts`, `.svelte` components       |
+| `examples/nuxt`                    | `server/middleware`, `useAsyncData`, `.vue` components             |
+| `examples/express`                 | Vanilla core — a hand-written adapter for an unsupported framework |
 
 ## Migrating from `@preprio/prepr-nextjs`