@preprio/toolkit 0.5.0-rc.5 → 0.5.1-dom.0

package/README.md

@@ -17,9 +17,8 @@ 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) · [Live preview](#live-preview).
+Jump to your framework: [Next.js](#nextjs) · [Astro](#astro) · [SvelteKit](#sveltekit) · [Nuxt](#nuxt) · [React without a framework](#react-no-framework) · [PHP, Ruby, Python and other backends](#any-backend-drop-in-script) · [anything else](#any-other-framework).
 
 Coming from `@preprio/prepr-nextjs`? See the [migration guide](https://github.com/preprio/prepr-toolkit/blob/main/MIGRATION.md).
 
@@ -123,12 +122,9 @@ 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/nuxt`           | `vue` (only for the `.vue` components)                  |
-| `@preprio/toolkit/nuxt/live`      | `vue` >= 3.3                                            |
 
 ## The preview gate
 
@@ -254,83 +250,158 @@ 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
+### Live preview (beta)
 
-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.
+True live preview inside the Prepr editor iframe: keystrokes patch your query
+results instantly by item `_id`; saves refetch the affected queries.
 
-**1. Run each query result through `normalizeQuery`**, with whatever client
-you fetch with:
+**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.
 
-```ts
-import { normalizeQuery } from '@preprio/toolkit/nextjs';
-
-const preview = process.env.VERCEL_ENV !== 'production';
+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:
 
-const data = await fetchFromPrepr(GetPageDocument, { slug }); // any client
-const page = await normalizeQuery(GetPageDocument, data, { enabled: preview });
-```
+- 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.
 
-**2. Mount `PreprRefresh` once in the root layout:**
+Configure once in a small client component mounted in your root layout:
 
 ```tsx
-import { PreprRefresh } from '@preprio/toolkit/nextjs/live';
+'use client';
+import { useEffect } from 'react';
+import { initLivePreview } from '@preprio/toolkit/nextjs/live';
 
-{
-  preview && <PreprRefresh enabled />;
+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;
 }
 ```
 
-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.
+Register query results in client components with `useLive`:
 
 ```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>;
+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
 }
 ```
 
-**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`:
+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.
 
-```tsx
-'use client';
-import { useEffect } from 'react';
-import { initLivePreview, useLive } from '@preprio/toolkit/nextjs/live';
+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.
 
-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;
-}
+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.
+
+#### 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';
+
+const preview = process.env.VERCEL_ENV !== 'production';
 
-// In a client component:
-const liveData = useLive(data, { query: GetPageDocument, variables: { slug } });
+const data = await fetchFromPrepr(GetPageDocument, { slug }); // any client
+const page = await normalizeQuery(GetPageDocument, data, { enabled: preview });
 ```
 
-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.
+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. A backend that cannot run them uses
+`startHtmlLivePreview({ apply: 'dom' })`; see
+[Any backend](#any-backend-drop-in-script).
 
 ## Astro
 
@@ -383,11 +454,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 in Astro
+### Live preview (experimental)
 
-To turn on [live preview](#live-preview), pass `preview` to `onPreprRequest`
-as above, and run each query result through `normalizeQuery` with the same
-flag:
+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:
 
 ```astro
 ---
@@ -403,8 +474,13 @@ 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 pages must render on
-demand (`output: 'server'`, or `export const prerender = false`).
+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.
 
 ## SvelteKit
 
@@ -466,35 +542,6 @@ 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).
@@ -546,25 +593,24 @@ 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
+### Live preview (experimental)
 
-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:
+Show the editor's unsaved changes while they type, 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,
+  enabled: preview, // your preview flag; nothing starts without it
   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.
+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.
 
 ## React (no framework)
 
@@ -641,6 +687,49 @@ This double-counts the first pageview, since the pixel's own install event fires
 
 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.
 
+## Any backend: drop-in script
+
+For server-rendered sites whose backend is not JavaScript (Laravel, Symfony, Rails, Django, …). The browser side needs one script tag; live preview needs no server support.
+
+**1. Render the props** into the page on preview deployments only, as JSON:
+
+```html
+<script type="application/json" data-prepr-toolbar-props>
+  {
+    "props": {
+      "activeSegment": null,
+      "activeVariant": null,
+      "segments": [{ "_id": "…", "name": "Students" }]
+    },
+    "options": { "locale": "nl" }
+  }
+</script>
+```
+
+`segments` comes from a `{ _Segments { _id name } }` query against your preview GraphQL URL; `activeSegment` / `activeVariant` from the `Prepr-Segments` / `Prepr-ABtesting` cookies (see [How It Works](#middleware)). Escape the JSON for a `<script>` element (`<` as `\u003c`).
+
+**2. Load the script**, from your bundle or a CDN:
+
+```javascript
+import '@preprio/toolkit/auto';
+```
+
+```html
+<script
+  type="module"
+  src="https://cdn.jsdelivr.net/npm/@preprio/toolkit@VERSION/dist/browser/auto.js"
+></script>
+```
+
+It mounts the toolbar, click-to-edit and live preview, and does nothing on a page without the props tag. Client-side page swaps (Livewire `wire:navigate`, Turbo, htmx) are handled: when `<body>` is replaced the preview starts again on the new page.
+
+**Live preview.** Inside the Prepr editor, text the editor types is written straight into the elements whose edit links point at the changed field. Images, links and added or reordered blocks appear on save, when the page is requested again. Two attributes tune it:
+
+- `data-prepr-live="html"` on an element (or an ancestor) writes rich text as markup, reduced to formatting tags first. Without it, rich text waits for save, so it never loses its formatting while the editor types.
+- `data-prepr-live="off"` leaves an element alone, for values the template reformats (dates, truncation) that should wait for save.
+
+Set `"live": "server"` in the payload if your server applies the editor's changes itself (see [`readLiveLogFromRequest`](#live-preview-beta)), or `"live": false` to turn live preview off.
+
 ## Any other framework
 
 The core is runtime-neutral: it works off a WHATWG `Request` and hands back the headers to forward to Prepr plus the cookies to persist. Adapting it to Express, Hono, Fastify, or a plain server is roughly twenty lines.
@@ -687,115 +776,6 @@ 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:
-
-- Select `_id` (and ideally `__typename`) on every model and component level
-  that should live-update. Items without `_id` 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: 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
@@ -912,6 +892,26 @@ controller.destroy();
 
 `trackEvent` and `setTrackingParam` are independent of `loadTrackingPixel` — they work against `window.prepr` however it got installed, including a legacy HTML snippet already on the page. If no pixel is installed at all they warn once in the console and return without throwing.
 
+#### `startHtmlLivePreview(options?)`
+
+Live preview for server-rendered pages without a client framework. A no-op outside the Prepr editor. Returns `{ stop() }`.
+
+| Option                 | Type                | Default      | Description                                                                                                                                                                                                                                                                   |
+| ---------------------- | ------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `apply`                | `'server' \| 'dom'` | `'server'`   | `'server'` requests the page again with the changes (the server applies them with `normalizeQuery`). `'dom'` writes plain-text changes into the page directly and needs no server support; rich text waits for save unless the element opts in with `data-prepr-live="html"`. |
+| `allowedEditorOrigins` | `string[]`          | `*.prepr.io` | As in [Preview options](#preview-options).                                                                                                                                                                                                                                    |
+| `strictMode`           | `boolean`           | `false`      | As in [Preview options](#preview-options).                                                                                                                                                                                                                                    |
+
+Every mode renders the stored page again on save.
+
+#### `applyPatchLogToDom(log, root?)`
+
+The `'dom'` mode on its own: writes a parsed patch log's text changes into the elements that render them and returns `{ applied, skipped }`. For custom setups; `startHtmlLivePreview` and `@preprio/toolkit/auto` call it for you.
+
+#### `startPreprAuto()`
+
+From `@preprio/toolkit/auto`, which also calls it on import. Starts the preview from the page's `data-prepr-toolbar-props` JSON and returns a function that stops it. See [Any backend](#any-backend-drop-in-script).
+
 #### `stegaClean(value)`
 
 Strips stega-encoded characters from a string. Rarely needed, since cleaning is automatic (see [Visual editing](#visual-editing)), but available when you need a clean value for comparison, sorting, or a non-DOM API.
@@ -957,15 +957,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`, `normalizedQuery` 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` 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_.
 
@@ -1101,14 +1101,6 @@ 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. 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.

package/dist/astro/index.cjs

@@ -31,7 +31,7 @@ __export(astro_exports, {
 module.exports = __toCommonJS(astro_exports);
 
 // src/version.ts
-var VERSION = "0.5.0-rc.5";
+var VERSION = "0.5.1-dom.0";
 
 // src/core/features.ts
 function isEnabled(config) {

package/dist/astro/index.js

@@ -1,5 +1,5 @@
 // src/version.ts
-var VERSION = "0.5.0-rc.5";
+var VERSION = "0.5.1-dom.0";
 
 // src/core/features.ts
 function isEnabled(config) {