@preprio/toolkit 0.5.0-rc.1 → 0.5.0-rc.10

package/README.md

@@ -17,8 +17,9 @@ Every integration is the same three steps:
 1. **Middleware** — resolves the visitor's customer ID, segment, and A/B variant into request headers.
 2. **Layout** — mounts the preview toolbar and the tracking pixel.
 3. **Data fetching** — forwards the Prepr headers on your GraphQL requests, so Prepr returns personalized content.
+4. **Live preview** (optional) — shows the editor's unsaved changes in Prepr's side-by-side preview while they type. See [Live preview](#live-preview).
 
-Jump to your framework: [Next.js](#nextjs) · [Astro](#astro) · [SvelteKit](#sveltekit) · [Nuxt](#nuxt) · [React without a framework](#react-no-framework) · [anything else](#any-other-framework).
+Jump to your framework: [Next.js](#nextjs) · [Astro](#astro) · [SvelteKit](#sveltekit) · [Nuxt](#nuxt) · [React without a framework](#react-no-framework) · [anything else](#any-other-framework) · [Live preview](#live-preview).
 
 Coming from `@preprio/prepr-nextjs`? See the [migration guide](https://github.com/preprio/prepr-toolkit/blob/main/MIGRATION.md).
 
@@ -122,9 +123,13 @@ Per-framework peer dependencies — all optional; installing without them is fin
 | `@preprio/toolkit` (vanilla core) | none                                                    |
 | `@preprio/toolkit/react`          | `react` >= 17, `react-dom` >= 17                        |
 | `@preprio/toolkit/nextjs`         | `next` >= 13, `react` >= 17, `react-dom` >= 17          |
+| `@preprio/toolkit/nextjs/live`    | `next` >= 13, `react` >= 18 (live preview)              |
 | `@preprio/toolkit/astro`          | none (`.astro` components compile in your own pipeline) |
 | `@preprio/toolkit/sveltekit`      | `svelte` (only for the `.svelte` components)            |
+| `@preprio/toolkit/sveltekit/live` | none (returns a plain Svelte store)                     |
+| `@preprio/toolkit/codegen`        | `graphql` >= 16 (build time, from your Codegen setup)   |
 | `@preprio/toolkit/nuxt`           | `vue` (only for the `.vue` components)                  |
+| `@preprio/toolkit/nuxt/live`      | `vue` >= 3.3                                            |
 
 ## The preview gate
 
@@ -250,6 +255,84 @@ The loader rewrites `w_` to the width Next asks for and scales `h_` alongside it
 
 See the runnable example at `examples/nextjs` for the full source of truth.
 
+### Live preview in Next.js
+
+Two additions turn on [live preview](#live-preview) for an App Router site.
+Both take your preview flag, the same one you pass the middleware.
+
+**1. Run each query result through `normalizeQuery`**, with whatever client
+you fetch with:
+
+```ts
+import { normalizeQuery } from '@preprio/toolkit/nextjs';
+
+const preview = process.env.VERCEL_ENV !== 'production';
+
+const data = await fetchFromPrepr(GetPageDocument, { slug }); // any client
+const page = await normalizeQuery(GetPageDocument, data, { enabled: preview });
+```
+
+**2. Mount `PreprRefresh` once in the root layout:**
+
+```tsx
+import { PreprRefresh } from '@preprio/toolkit/nextjs/live';
+
+{
+  preview && <PreprRefresh enabled />;
+}
+```
+
+While an editor types, `PreprRefresh` sends the unsaved changes to a server
+action and the route re-renders with them; on save it calls
+`router.refresh()` for the stored content. Server components need nothing
+else. Requires Next.js 16 or later; on Next.js 15 and older pages update on
+save only.
+
+**Client components** can skip the server round trip: wrap the data they
+render in `useLive`, and keystrokes patch it in the browser. Import it from
+`@preprio/toolkit/nextjs/live` — the `/nextjs` barrel also exports
+server-only helpers (`next/headers`), which a client module graph must not
+include.
+
+```tsx
+'use client';
+import { useLive } from '@preprio/toolkit/nextjs/live';
+
+export default function Hero({ hero }: { hero: HeroFragment }) {
+  const live = useLive(hero);
+  return <h1>{live.title}</h1>;
+}
+```
+
+**Client-fetched data** (no server components): instead of `PreprRefresh`,
+call `initLivePreview({ enabled: preview, fetcher })` once in a client
+component, and pass `{ query, variables }` to `useLive`. On save the toolkit
+runs the query again through your `fetcher`:
+
+```tsx
+'use client';
+import { useEffect } from 'react';
+import { initLivePreview, useLive } from '@preprio/toolkit/nextjs/live';
+
+export function LivePreviewInit({ preview }: { preview: boolean }) {
+  useEffect(() => {
+    initLivePreview({
+      enabled: preview,
+      // Runs a registered query against Prepr GraphQL; return `json.data`.
+      fetcher: (query, variables) => fetchFromPrepr(query, variables),
+    });
+  }, [preview]);
+  return null;
+}
+
+// In a client component:
+const liveData = useLive(data, { query: GetPageDocument, variables: { slug } });
+```
+
+Don't combine `PreprRefresh` with `useLive` registrations that pass a
+`query`: a save would both refetch and refresh. `useLive` without a `query`
+works alongside it.
+
 ## Astro
 
 **`src/middleware.ts`**
@@ -301,6 +384,29 @@ The `.astro` components ship as source, compiled by your own Astro/Vite pipeline
 
 See the runnable example at `examples/astro` for the full source of truth.
 
+### Live preview in Astro
+
+To turn on [live preview](#live-preview), pass `preview` to `onPreprRequest`
+as above, and run each query result through `normalizeQuery` with the same
+flag:
+
+```astro
+---
+import { normalizeQuery } from '@preprio/toolkit/astro';
+
+const data = await fetchFromPrepr(GetPageDocument, { slug }); // any client
+const page = normalizeQuery(GetPageDocument, data, {
+  enabled: preview,
+  locals: Astro.locals,
+});
+---
+```
+
+`PreprToolbar.astro` does the rest. Inside the Prepr editor it requests the
+page again with the unsaved changes and updates only the parts of the DOM that
+changed; on save it shows the stored content. Preview pages must render on
+demand (`output: 'server'`, or `export const prerender = false`).
+
 ## SvelteKit
 
 **`src/hooks.server.ts`**
@@ -361,6 +467,35 @@ The `.svelte` components ship as source (compiled by your own Vite/Svelte pipeli
 
 See the runnable example at `examples/sveltekit` for the full source of truth.
 
+### Live preview in SvelteKit
+
+To turn on [live preview](#live-preview), return your preview flag from
+`load`, then run the query result through `normalizedQuery`. It applies the
+editor's changes in the browser, with no server round trip:
+
+```svelte
+<script lang="ts">
+  import { invalidateAll } from '$app/navigation';
+  import { normalizedQuery } from '@preprio/toolkit/sveltekit/live';
+
+  let { data } = $props();
+
+  const result = $derived(
+    normalizedQuery(GetPageDocument, data.result, {
+      enabled: data.preview,
+      onSave: invalidateAll,
+    }),
+  );
+</script>
+
+<h1>{$result.Page.title}</h1>
+```
+
+`normalizedQuery` returns a Svelte store: render from `$result`. Pass the
+result in the shape the query returns (`{ Page: … }`, not just the page), so
+the toolkit can tell which response key holds which field. On save,
+`invalidateAll` reruns your `load` functions for the stored content.
+
 ## Nuxt
 
 Requires Nitro's Node.js preset (the Nuxt default).
@@ -412,6 +547,26 @@ The `.vue` components ship as source (compiled by your own Vite/Vue pipeline) an
 
 See the runnable example at `examples/nuxt` for the full source of truth.
 
+### Live preview in Nuxt
+
+To turn on [live preview](#live-preview), run the `useAsyncData` result
+through `useNormalizedQuery` with your preview flag. It applies the editor's
+changes in the browser, with no server round trip:
+
+```ts
+import { useNormalizedQuery } from '@preprio/toolkit/nuxt/live';
+
+const { data, refresh } = await useAsyncData('page', () => fetchPage(slug));
+const page = useNormalizedQuery(GetPageDocument, data, {
+  enabled: preview,
+  onSave: refresh,
+});
+```
+
+Render from `page`. Nuxt hydrates the whole page, so every component that
+shows a changed field updates. On save, `refresh` refetches the stored
+content.
+
 ## React (no framework)
 
 `@preprio/toolkit/react` carries the two components that need nothing but React — for Vite + React Router, TanStack Router, Remix SPA mode, or Create React App. Next.js users want the [Next.js section](#nextjs) instead; its `PreprToolbar` binds the App Router for you.
@@ -467,23 +622,22 @@ const location = useLocation();
 
 ### Tracking pageviews
 
-`loadTrackingPixel` queues one `pageload` event when it installs. Client-side route changes emit nothing on their own, so fire them yourself:
+The pixel tracks pageviews by itself, client-side route changes included. It counts a view for the Prepr content item named by a `prepr:id` meta tag in `<head>`, and watches that tag: when a route change points it at another item, the pixel records a new view. Render the tag on every page that shows a Prepr item:
 
 ```tsx
-import { useEffect } from 'react';
-import { useLocation } from 'react-router';
-import { trackEvent } from '@preprio/toolkit';
-
-function usePreprPageviews() {
-  const { pathname } = useLocation();
-
-  useEffect(() => {
-    trackEvent('pageload');
-  }, [pathname]);
+function Page({ page }: { page: { _id: string } }) {
+  return (
+    <>
+      <meta property="prepr:id" content={page._id} />
+      {/* … */}
+    </>
+  );
 }
 ```
 
-This double-counts the first pageview, since the pixel's own install event fires too. Skip the initial run with a ref if the exact count matters.
+React 19 hoists a `<meta>` rendered anywhere in the tree into `<head>`. On React 18, set it with your head manager (`react-helmet-async` or similar) instead.
+
+A page without the tag records no view. Calling `trackEvent('pageload')` yourself does not help: the pixel takes one `pageload` per page load and ignores the rest. Use `trackEvent` for your own events, such as `trackEvent('add_to_cart', { productId })`.
 
 The `id` is your access token, and in a client-rendered app it is public — bundled into JS and visible in devtools. Use a tracking-only token; do not derive it from a browser-exposed GraphQL URL, which would also expose content read access.
 
@@ -533,6 +687,236 @@ const controller = createPreprPreview({ props: toolbarProps });
 
 Serialize the server-computed props into the page — a `<script type="application/json">` tag works well — and read them back on the client. See the runnable example at `examples/express` for the full source of truth.
 
+## Live preview
+
+Inside Prepr's side-by-side preview, live preview shows what an editor types
+before they save: text, links and other fields update on the page as they
+type, and a save shows the stored content. Outside the editor, and when it is
+not enabled, it does nothing and costs nothing: the runtime loads only inside
+the editor iframe.
+
+| Framework | Entry point                       | Applies changes                       | Setup                                   |
+| --------- | --------------------------------- | ------------------------------------- | --------------------------------------- |
+| Next.js   | `@preprio/toolkit/nextjs/live`    | On the server (`normalizeQuery`)      | [Next.js](#live-preview-in-nextjs)      |
+| Astro     | `@preprio/toolkit/astro`          | On the server (`normalizeQuery`)      | [Astro](#live-preview-in-astro)         |
+| SvelteKit | `@preprio/toolkit/sveltekit/live` | In the browser (`normalizedQuery`)    | [SvelteKit](#live-preview-in-sveltekit) |
+| Nuxt      | `@preprio/toolkit/nuxt/live`      | In the browser (`useNormalizedQuery`) | [Nuxt](#live-preview-in-nuxt)           |
+
+Other server-rendered stacks can use the framework-free core exports from
+`@preprio/toolkit`: `readLiveLogFromRequest(request)` in the server handler,
+`normalizeQuery(query, result, { log })` on each result, and
+`startHtmlLivePreview()` in the browser. The Astro wrapper is built from
+exactly these.
+
+### Before you start
+
+1. **Set up the toolbar for your framework first.** Live preview runs only
+   where the Prepr middleware handles the request with `preview: true`. Make
+   sure the middleware covers every page you preview: on a page it skips,
+   live preview does nothing and shows no error.
+2. **Pass your preview flag as `enabled`** to every live preview entry point.
+   Each one does nothing without it. Never pass `true` on a production
+   deployment.
+3. **Point Prepr at your preview deployment.** In Prepr, set the preview URL
+   to a deployment that uses the **GraphQL Preview** access token, with
+   **Enable edit mode** checked.
+4. **Allow Prepr to frame your site.** If your server sends a
+   `Content-Security-Policy`, add your Prepr environments to
+   `frame-ancestors`, for example
+   `frame-ancestors https://acme.prepr.io https://dev-acme.prepr.io`.
+
+### Preparing your queries
+
+Live updates and click-to-edit find content by id, never by position, so
+they stay correct while an editor adds, removes or reorders blocks before
+saving. Every model, component and dynamic content entry that should
+live-update needs `_id` (and ideally `__typename`) in the query result; items
+without `_id` stay static.
+
+There are three ways to get them there. Pick the first that fits your setup.
+
+#### Option 1: GraphQL Codegen (recommended)
+
+Add the `preprIds` document transform to your Codegen output. `_id` is
+added wherever your schema has one: on models and components, and inside
+each member of a dynamic content field. Collections like `Pages` and unions
+themselves never get an `_id`, so the queries stay valid. Your `.graphql`
+files stay as they are; the generated documents and types include the field,
+at no runtime cost. Adding a field never breaks code that compiles today, so
+this is safe to turn on in an existing project.
+
+```ts
+// codegen.ts
+import type { CodegenConfig } from '@graphql-codegen/cli';
+import { preprIds } from '@preprio/toolkit/codegen';
+
+const config: CodegenConfig = {
+  schema: process.env.PREPR_GRAPHQL_URL,
+  documents: ['src/queries/**/*.graphql'],
+  generates: {
+    'src/gql/': {
+      preset: 'client',
+      documentTransforms: [preprIds],
+    },
+  },
+};
+
+export default config;
+```
+
+Run Codegen again after adding it. Needs `graphql` 16 or later, which a
+Codegen setup already has.
+
+To add `__typename` everywhere too, use `createPreprIds({ typename: true })`
+instead. It is off by default because a selected `__typename` changes the
+generated types: each member of a union is typed on its own, so code that
+reads a union's fields without checking `__typename` first stops compiling.
+Live preview only needs it on dynamic content entries, where you select it
+already to render them.
+
+#### Option 2: at runtime, without Codegen
+
+`addPreprIds(document, schema)` does the same to a parsed query. It needs
+your schema, which Prepr serves through introspection on the same GraphQL
+URL. Load it once on the server, and transform each query once:
+
+```ts
+import { addPreprIds } from '@preprio/toolkit/codegen';
+import {
+  buildClientSchema,
+  getIntrospectionQuery,
+  parse,
+  print,
+  type GraphQLSchema,
+} from 'graphql';
+
+const url = process.env.PREPR_GRAPHQL_URL!;
+
+let schema: Promise<GraphQLSchema> | undefined;
+function preprSchema(): Promise<GraphQLSchema> {
+  schema ??= fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ query: getIntrospectionQuery() }),
+  })
+    .then((response) => response.json())
+    .then(({ data }) => buildClientSchema(data));
+  return schema;
+}
+
+const prepared = new Map<string, string>();
+export async function withPreprIds(query: string): Promise<string> {
+  let result = prepared.get(query);
+  if (!result) {
+    result = print(addPreprIds(parse(query), await preprSchema()));
+    prepared.set(query, result);
+  }
+  return result;
+}
+```
+
+Then send `await withPreprIds(query)` instead of `query` in your fetch
+helper. With a client that takes a `DocumentNode`, pass
+`addPreprIds(document, schema)` instead. Keep this on the server: the
+GraphQL URL carries your access token.
+
+#### Option 3: by hand
+
+Select `_id` (and `__typename`) on every model and component level, and on
+every entry type in dynamic content fields (`Text`, `Quote`, …). `Assets`
+entries have no `_id` of their own: select `items { _id }` instead.
+
+The rest is about rendering:
+
+- A `Text` entry's content updates whether the query selects `body`,
+  `html` or `text` (the latter with tags stripped).
+- **Dynamic content entries are found automatically.** In preview,
+  `normalizeQuery`, `normalizedQuery` and `useNormalizedQuery` add each
+  entry's `_id` (and, for `Text` entries, the field path) to the hidden edit
+  link of every text inside it. Click-to-edit and the editor's "jump to
+  field" then find the entry by id, also after an editor reorders entries.
+  Render a `Text` entry's HTML straight into one wrapper element, so its
+  edit link lands on that wrapper and the whole entry is outlined.
+- Prepr images are click-to-edit inside the editor without any markup: the
+  toolkit matches image URLs (also through image optimizers like
+  `/_next/image`) to the open item's assets.
+- **Set the attributes yourself only where that does not reach:**
+  - Data you fetch in the browser without those helpers: run it through
+    `annotateEditLinks(result, query)` from `@preprio/toolkit`, or mark the
+    element as below.
+  - An entry with no text and no Prepr image (an embed, a video URL): wrap
+    it in an element with `data-prepr-edit-target="<field>.<index>"` and
+    `data-prepr-entry-id="<entry _id>"` (for `Assets`, the first asset's
+    `_id`). Attributes you set always win over the automatic ones.
+  - Other values without a hidden edit link (video and other URLs): make
+    them click-to-edit with
+    `previewAttrs({ id, field }, { enabled: preview })` on the element that
+    renders them. Encoded text inside that element does not override it.
+  - Fields Prepr returns without an edit link, such as remote content, next
+    to a text field that has one: `stegaTarget(text, { field })` reads the
+    item and path from the text and points at the sibling field, ready for
+    `previewAttrs`. Use `products.items.2` to point at one entry.
+
+    ```tsx
+    // Each product card opens its row of the component's `products` field.
+    <article
+      {...previewAttrs(
+        stegaTarget(block.title, { field: `products.items.${index}` }),
+        { enabled: preview },
+      )}
+    >
+    ```
+- Where the page renders a linked item whose content comes from items nested
+  inside it (for example a personalization or a shared section referenced
+  from a stack), wrap it in an element with
+  `data-prepr-reference="<linked item _id>"`. The editor only knows the items
+  the open item links to directly; content inside the wrapper is outlined as
+  that linked item, and clicking it opens the link in the editor.
+
+Typed text and changed fields show immediately. Structural changes, such as
+adding or reordering components, appear after save.
+
+### Options
+
+`PreprRefresh`, `initLivePreview`, `normalizedQuery` and `useNormalizedQuery`
+take the same two options as the toolbar (in Astro, set them on the
+toolbar's `options`):
+
+- **`allowedEditorOrigins`** — exact editor origins, replacing the
+  `https://*.prepr.io` default. Only needed when Prepr runs on your own domain.
+- **`strictMode`** — set it when your preview token uses GraphQL strict mode
+  (required fields never null). The editor then holds back new entries until
+  their required fields are filled, and never sends a cleared required field
+  as null.
+
+### Security
+
+- **Disabled means untouched.** With `enabled: false` (the default) results
+  are returned as they are and the request is never read, so static and ISR
+  pages stay static.
+- **Only the Prepr editor can send changes.** Changes are accepted only from
+  `https://*.prepr.io` (or your `allowedEditorOrigins`), never from another
+  page that frames your site. They are validated as hostile input: link
+  fields never take `javascript:`, `vbscript:` or `data:` URLs. HTML text is
+  passed on as typed, like rich text from the API.
+- **One editor's changes never reach anyone else.** On the server-side
+  frameworks, changes are read only in preview. Astro accepts them only from
+  a same-origin `POST` carrying the toolkit's header and marks that response
+  `Cache-Control: private, no-store`. Next.js stores them in the server
+  process under a random, single-use token, so a replayed or cached request
+  sees nothing.
+- **The Next.js server action is public but inert.** Next.js registers the
+  toolkit's server action in every build that imports
+  `@preprio/toolkit/nextjs/live`, so anyone can call it. It does nothing
+  unless the Prepr middleware handled the request with `preview: true`, and
+  the middleware drops `Prepr-*` headers a client sends.
+
+### Trying it locally
+
+The Next.js, Astro, SvelteKit and Nuxt examples all have live preview wired
+up. Open them from a Prepr environment whose preview URL points at your local
+server.
+
 ## API Reference
 
 ### Framework server helpers
@@ -636,7 +1020,7 @@ controller.destroy();
 | Option       | Type                     | Description                                                                                                                                                                                                                                                                                      |
 | ------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `props`      | `PreprToolbarProps`      | From `getToolbarProps`. Optional — a headless preview has no segment list to pass.                                                                                                                                                                                                               |
-| `options`    | `PreprPreviewOptions`    | `{ debug?, locale?, features?, ui?, allowedEditorOrigins?, autoClean? }`. See [Preview options](#preview-options).                                                                                                                                                                               |
+| `options`    | `PreprPreviewOptions`    | `{ debug?, locale?, features?, ui?, allowedEditorOrigins?, strictMode?, autoClean? }`. See [Preview options](#preview-options).                                                                                                                                                                  |
 | `navigation` | `PreprNavigationAdapter` | How segment/variant switches navigate. Optional — omitted, the toolbar uses `window.location.assign` (a full page load). `reload` is optional too, runs after a preview-mode toggle, and defaults to `window.location.reload()`. The Next.js and SvelteKit wrappers wire all of this up for you. |
 
 `createPreprPreview` is a no-op outside a browser (no `window`/`document`) and returns a controller whose `destroy()` does nothing, so it is safe to call during SSR. Call it **once per page** — two calls start two bridges and announce the preview twice.
@@ -694,14 +1078,15 @@ 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 editors. Replaces the wildcard.      |
-| `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' \| 'fr' \| 'de'` | auto-detected | UI language. Falls back to the first supported browser language, then `en`. Inside the Prepr editor, the editor's interface language wins.                                                                                                                                                       |
+| `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.                                                                                                                                      |
+| `strictMode`           | `boolean`                      | `false`       | Your preview token uses GraphQL strict mode (required fields never null). The editor then holds back new entries until their required fields are filled and never sends a cleared required field as null. Also on `PreprRefresh`, `initLivePreview`, `normalizedQuery` and `useNormalizedQuery`. |
+| `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_.
 
@@ -809,7 +1194,7 @@ Because the toolbar renders inside a shadow root, none of your own page CSS —
 
 ### Internationalization
 
-The toolbar UI ships with English and Dutch. Pass `locale` explicitly, or omit it to auto-detect from the browser and fall back to `en`:
+The toolbar UI ships with English, Dutch, French and German. Pass `locale` explicitly, or omit it to auto-detect from the browser and fall back to `en`. Inside the Prepr editor's preview, the visual editor's labels follow the language the editor user has set for the CMS, falling back to `locale` when the editor sends a language the toolkit does not support:
 
 ```typescript
 createPreprPreview({ props, options: { locale: 'nl' } });
@@ -837,6 +1222,14 @@ createPreprPreview({ props, options: { locale: 'nl' } });
 - **API calls**: personalization only works if you spread `getPreprHeaders()` into your GraphQL fetch. Missing headers is the most common reason segments appear to have no effect.
 - **Chained middleware**: when chaining, pass the existing `NextResponse` as the second argument. Creating a fresh `NextResponse.next()` afterwards discards Prepr's request headers.
 
+### Live preview does not update
+
+- **Check `enabled`**: every live preview entry point needs your preview flag, and the middleware must run with `preview: true` for that page.
+- **Check the preview URL in Prepr**: it must point at a deployment that uses the GraphQL Preview token. A production build with preview off shows saved content only.
+- **Check `_id`**: an item or component whose query does not select `_id` stays static. Add the `preprIds` Codegen transform, or see [Preparing your queries](#preparing-your-queries).
+- **Check the frame**: a `Refused to frame` error in the browser console means your `Content-Security-Policy` `frame-ancestors` does not list your Prepr environment.
+- **Next.js only shows changes on save**: `normalizeQuery` with `PreprRefresh` needs Next.js 16 or later.
+
 ### 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.