@preprio/toolkit 0.5.0-rc.4 → 0.5.0-rc.6

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,156 +255,83 @@ 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 (beta)
+### Live preview in Next.js
 
-True live preview inside the Prepr editor iframe: keystrokes patch your query
-results instantly by item `_id`; saves refetch the affected queries.
+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.
 
-**Requirements.** Live preview runs only where the Prepr middleware handles
-the request with `preview: true` (`createPreprMiddleware(request, { preview })`
-in `proxy.ts`). Make sure your middleware `matcher` covers every page you
-preview: on a page it skips, live preview does nothing and shows no error.
-Pass your preview flag as `enabled` to every live preview entry point below;
-each one does nothing without it.
+**1. Run each query result through `normalizeQuery`**, with whatever client
+you fetch with:
 
-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:
+```ts
+import { normalizeQuery } from '@preprio/toolkit/nextjs';
 
-- Select `_id` (and ideally `__typename`) on every model and component level
-  that should live-update. Items without `_id` silently stay static.
-- In dynamic content fields, select `_id` on every entry type (`Text`,
-  `Quote`, …). `Assets` entries have no `_id` of their own: select
-  `items { _id }` instead.
-- A `Text` entry's content updates whether the query selects `body`,
-  `html` or `text` (the latter with tags stripped).
-- Render each dynamic content entry inside an element marked with
-  `data-prepr-edit-target="<field>.<index>"` and
-  `data-prepr-entry-id="<entry _id>"` (for `Assets`, the first asset's
-  `_id`). The index is the fallback when no id matches.
-- Values without a hidden edit link (images, videos, other URLs) are made
-  click-to-edit with `previewAttrs({ id, field }, { enabled: isPreview })`
-  on the element that renders them.
-- 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.
+const preview = process.env.VERCEL_ENV !== 'production';
+
+const data = await fetchFromPrepr(GetPageDocument, { slug }); // any client
+const page = await normalizeQuery(GetPageDocument, data, { enabled: preview });
+```
 
-Configure once in a small client component mounted in your root layout:
+**2. Mount `PreprRefresh` once in the root layout:**
 
 ```tsx
-'use client';
-import { useEffect } from 'react';
-import { initLivePreview } from '@preprio/toolkit/nextjs/live';
+import { PreprRefresh } from '@preprio/toolkit/nextjs/live';
 
-export default function LivePreviewInit({ preview }: { preview: boolean }) {
-  useEffect(() => {
-    initLivePreview({
-      // Your preview flag. Without it nothing starts.
-      enabled: preview,
-      // Runs a registered query against Prepr GraphQL. `query` is whatever
-      // you registered (string or DocumentNode) — you own the transport.
-      fetcher: async (query, variables) => {
-        /* POST to your Prepr GraphQL endpoint, return json.data */
-      },
-    });
-  }, [preview]);
-  return null;
+{
+  preview && <PreprRefresh enabled />;
 }
 ```
 
-Register query results in client components with `useLive`:
+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 PageContent({ data, slug }) {
-  const liveData = useLive(data, {
-    query: GetPageBySlugDocument,
-    variables: { slug },
-  });
-  // render from liveData — it re-renders on editor keystrokes and saves
+export default function Hero({ hero }: { hero: HeroFragment }) {
+  const live = useLive(hero);
+  return <h1>{live.title}</h1>;
 }
 ```
 
-In `'use client'` files always import from `@preprio/toolkit/nextjs/live` —
-the `/nextjs` barrel also exports server-only helpers (`next/headers`), which
-a client module graph must not include.
-
-Omitting `query`/`variables` degrades that registration to keystroke pushes
-only. For server-component pages, mount `<PreprRefresh enabled={preview} />`
-instead — it calls `router.refresh()` on every save. 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.
-
-Without `enabled`, and outside the Prepr editor iframe, all of this is a
-passthrough with zero overhead. The CMS editor must emit `prepr:fieldChange` (per keystroke) and
-`prepr:itemChanged` (on save, with the root content item id) into the preview
-iframe — `examples/editor-emulator` emulates this for local development.
-Unsaved structural changes (adding/reordering components) appear after save;
-typed text is live immediately.
+**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`:
 
-#### Unsaved changes in server components: `normalizeQuery` (experimental, Next.js 16+)
-
-Server components show the editor's unsaved changes when you pass their query
-results through `normalizeQuery`, with whatever client you fetch with:
-
-```ts
-import { normalizeQuery } from '@preprio/toolkit/nextjs';
+```tsx
+'use client';
+import { useEffect } from 'react';
+import { initLivePreview, useLive } from '@preprio/toolkit/nextjs/live';
 
-const preview = process.env.VERCEL_ENV !== 'production';
+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;
+}
 
-const data = await fetchFromPrepr(GetPageDocument, { slug }); // any client
-const page = await normalizeQuery(GetPageDocument, data, { enabled: preview });
+// In a client component:
+const liveData = useLive(data, { query: GetPageDocument, variables: { slug } });
 ```
 
-Mount `<PreprRefresh enabled={preview} />` in the root layout. While an
-editor types, it sends the unsaved changes to the server and the route
-re-renders with them; on save it refreshes with the stored content.
-
-- The query (source text, a `DocumentNode`, or a typed document string) tells
-  the toolkit which response key holds which field. Changes land under
-  aliases, inside single components, on dynamic content entries, and on every
-  place the same item appears. Fields the query did not select are left
-  alone. Select `_id` on every item and component that should update.
-- Changed text keeps its hidden edit link, so it stays click-to-edit.
-- `useLive` data keeps the typed values across these re-renders.
-
-**Production safety.** Pass `enabled` from the same preview flag you give the
-middleware, and never `true` on a production deployment:
-
-- With `enabled: false` (the default) the result is returned untouched and
-  the request is never read, so static and ISR pages stay static.
-  `PreprRefresh`, `initLivePreview` and `useLive` don't listen to the editor
-  at all.
-- Next.js registers the toolkit's server action in every build that imports
-  `@preprio/toolkit/nextjs/live`, so anyone can call it, browsers and scripts
-  alike. It does nothing (no parsing, no storage, no re-render) unless the
-  Prepr middleware handled the request with `preview: true`. The middleware
-  drops `Prepr-*` headers a client sends, so this can't be forged on a page
-  the middleware runs for. On a page its `matcher` skips, a forged header can
-  at most trigger an extra render, never change content, because
-  `normalizeQuery` there still needs `enabled`.
-- Changes only reach the re-render of the editor's own server action call.
-  The action stores them in the server process under a random, single-use
-  token and sets only that token as a cookie that expires immediately. Any
-  other request carrying the cookie, such as a plain or cacheable GET that
-  replays a token, sees nothing.
-- Changes are only accepted from the Prepr editor (`https://*.prepr.io`, or
-  your `allowedEditorOrigins` via `initLivePreview`), 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.
-
-On Next.js 15 and older the action does nothing and pages update on save.
-
-For Astro and Nuxt, see their sections. The framework-free core exports,
-`normalizeQuery(query, result, { log })`, `startHtmlLivePreview()` and
-`readLiveLogFromRequest(request)` from `@preprio/toolkit`, cover any other
-server-rendered stack.
+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
 
@@ -452,11 +384,11 @@ 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 (experimental)
+### Live preview in Astro
 
-Show the editor's unsaved changes while they type. Pass `preview` to
-`onPreprRequest` as above, and run each query result through
-`normalizeQuery` with your preview flag:
+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
 ---
@@ -472,13 +404,8 @@ const page = normalizeQuery(GetPageDocument, data, {
 
 `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 must render on demand
-(`output: 'server'`).
-
-Safety: the middleware only accepts changes in preview, from a same-origin
-`POST` that carries the toolkit's header and a JSON body, and marks that
-response `Cache-Control: private, no-store`. With `enabled: false` the result
-is returned untouched. Changes are accepted only from the Prepr editor.
+changed; on save it shows the stored content. Preview pages must render on
+demand (`output: 'server'`, or `export const prerender = false`).
 
 ## SvelteKit
 
@@ -540,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).
@@ -591,24 +547,25 @@ 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 (experimental)
+### Live preview in Nuxt
 
-Show the editor's unsaved changes while they type, with no server round trip:
+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, // your preview flag; nothing starts without it
+  enabled: preview,
   onSave: refresh,
 });
 ```
 
 Render from `page`. Nuxt hydrates the whole page, so every component that
-shows a changed field updates. Without `enabled`, on the server and outside
-the Prepr editor's preview iframe it returns the data unchanged. Changes are accepted only from
-the Prepr editor.
+shows a changed field updates. On save, `refresh` refetches the stored
+content.
 
 ## React (no framework)
 
@@ -665,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.
 
@@ -731,6 +687,214 @@ 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` and
+`__typename` are added wherever your schema has them: 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 fields, at no runtime cost.
+
+```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.
+
+#### 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.
+- 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
@@ -892,15 +1056,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' \| '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` and `useNormalizedQuery`. |
-| `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_.
 
@@ -1036,6 +1200,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.