directus-live-preview-bridge 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ritsa Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,205 @@
+# Directus Live Preview bridge
+
+`directus-live-preview-bridge` sends unsaved item edits from the Directus Data
+Studio to the page open in Live Preview. It does not save content or call the
+Directus API.
+
+The package is one Directus bundle with two parts. A hook adds a deferred
+same-origin script tag to the Data Studio, and an endpoint serves the script at
+`/live-preview-bridge/script.js`. Keeping the executable code in an external
+same-origin response works with the Data Studio's Content Security Policy.
+
+## Requirements
+
+- Directus 12
+- Node.js 22 or later
+- A frontend that handles the bridge protocol described below
+
+The bundle uses Directus' server-side `embed` hook. Directus does not expose
+that hook to sandboxed extensions, so this package runs as an unsandboxed API
+extension. Review the source before installing it in a production project.
+
+## Install
+
+Install the package alongside Directus:
+
+```sh
+pnpm add directus-live-preview-bridge
+```
+
+For a custom Directus Docker image:
+
+```dockerfile
+FROM directus/directus:12.3.1
+
+USER root
+RUN corepack enable
+USER node
+
+RUN pnpm add directus-live-preview-bridge
+```
+
+You can also build this repository and copy `package.json` plus `dist/` into
+`extensions/directus-live-preview-bridge/`. Restart Directus after installing
+the bundle.
+
+### Marketplace installs
+
+The npm package contains the metadata required by the Directus Marketplace.
+Because the bundle is unsandboxed, Directus hides it under the default
+`MARKETPLACE_TRUST=sandbox` setting. Self-hosted and Enterprise Cloud projects
+must set `MARKETPLACE_TRUST=all` before installing it from the Marketplace.
+
+## Connect a preview frontend
+
+The bridge posts this payload to the current Live Preview iframe:
+
+```ts
+type LivePreviewEditsMessage = {
+  type: 'directus-live-preview-bridge:edits';
+  collection: string;
+  primaryKey: unknown;
+  edits: Record<string, unknown>;
+  initialValues: Record<string, unknown>;
+};
+```
+
+The target origin comes from the iframe URL. The bridge never uses `*` as the
+`postMessage` target.
+
+Register the listener before telling the Data Studio that the preview is ready:
+
+```ts
+const EDITS_MESSAGE_TYPE = 'directus-live-preview-bridge:edits';
+const READY_MESSAGE_TYPE = 'directus-live-preview-bridge:ready';
+
+export function connectDirectusLivePreview(
+  directusUrl: string,
+  allowedCollections: ReadonlySet<string>,
+  applyEdits: (message: {
+    collection: string;
+    primaryKey: unknown;
+    edits: Record<string, unknown>;
+    initialValues?: Record<string, unknown>;
+  }) => void,
+) {
+  const directusOrigin = new URL(directusUrl).origin;
+
+  function receiveEdits(event: MessageEvent) {
+    if (event.origin !== directusOrigin || event.source !== window.parent)
+      return;
+
+    const message = event.data;
+
+    if (
+      !message ||
+      message.type !== EDITS_MESSAGE_TYPE ||
+      typeof message.collection !== 'string' ||
+      !allowedCollections.has(message.collection) ||
+      typeof message.edits !== 'object' ||
+      message.edits === null ||
+      Array.isArray(message.edits) ||
+      (message.initialValues !== undefined &&
+        (typeof message.initialValues !== 'object' ||
+          message.initialValues === null ||
+          Array.isArray(message.initialValues)))
+    ) {
+      return;
+    }
+
+    applyEdits(message);
+  }
+
+  window.addEventListener('message', receiveEdits);
+  window.parent.postMessage({ type: READY_MESSAGE_TYPE }, directusOrigin);
+
+  return () => window.removeEventListener('message', receiveEdits);
+}
+```
+
+Validate the collection and item in your application before merging `edits` into
+rendered data. Treat every cross-window message as untrusted input, even when
+its origin is expected.
+
+Each message is a complete snapshot of the current `edits`, not an incremental
+patch. Render allowed fields from `initialValues`, then apply the current edits.
+Do not merge into the previous rendered result: a field reset removes its edit
+key. After a save, `initialValues` contains the new saved baseline and `edits`
+can be empty. Older bridge versions omit `initialValues`; use server-fetched
+content as the baseline for those messages. Both objects can contain fields
+available to the editor, so use a trusted preview frontend.
+
+The ready message matters. The Data Studio may send its first update before the
+preview application has mounted. On receipt, the bridge replays the latest
+state.
+
+### Next.js App Router example
+
+The [Next.js guide](docs/nextjs.md) shows a complete Directus 12 and Next.js App
+Router setup. It covers Draft Mode, a protected preview route, server-side
+Directus fetching, a React client component that applies unsaved edits, and an
+optional route for leaving Draft Mode.
+
+## Configuration
+
+The defaults work when Directus is served from the root of its origin.
+
+| Environment variable                   | Default                          | Purpose                                                                                                                               |
+| -------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `LIVE_PREVIEW_BRIDGE_SCRIPT_PATH`      | `/live-preview-bridge/script.js` | Root-relative endpoint path inserted into the Data Studio. Set this when a reverse proxy serves Directus below a path such as `/cms`. |
+| `LIVE_PREVIEW_BRIDGE_POLL_INTERVAL_MS` | `120`                            | How often the bridge reads staged form state. Accepted values are integers from `50` through `5000`.                                  |
+
+For a Directus instance served at `https://example.com/cms`, use:
+
+```env
+LIVE_PREVIEW_BRIDGE_SCRIPT_PATH=/cms/live-preview-bridge/script.js
+```
+
+The script path only accepts a same-origin, root-relative URL. Invalid values
+fall back to the default and produce a warning in the Directus log.
+
+## How edit capture works
+
+Directus 12 does not provide a public client API for reading the staged item
+form. The bridge finds the current form through Vue's mounted VNode tree and
+polls its props. This tree is present in production builds, including those that
+omit per-element Vue devtools metadata. The bridge reads normalized form values
+for native inputs and custom controls such as dropdowns. It skips loading or
+unmounted forms and does not keep a separate cache of native input values.
+
+This dependency on Data Studio internals is why the package targets Directus 12
+explicitly. Run the test suite against a Directus upgrade before rolling it out.
+
+The bridge serializes edits through JSON before posting them. Circular values
+are skipped, and repeated payloads are not sent again unless the iframe reports
+that it is ready.
+
+## Development
+
+```sh
+npm install
+npm run check
+```
+
+`npm run check` type-checks the source, runs the tests, checks formatting,
+builds the bundle, and validates the Directus manifest. Use `npm run dev` for a
+watch build or `npm run link` to link the package into a local Directus
+extensions directory.
+
+The full development dependency audit currently reports an upstream `unhead`
+advisory through the Directus SDK. It is not included in the compiled extension
+or installed by package consumers. The
+[security policy](https://github.com/ritsa-tech/directus-live-preview-bridge/blob/main/SECURITY.md#development-dependency-audit)
+records the dependency path and verification commands.
+
+Releases use Conventional Commits and Release Please. The publish job uses npm
+trusted publishing. npm requires the package to exist before that trust can be
+configured, so maintainers must publish the initial version manually. After
+that, configure `ritsa-tech/directus-live-preview-bridge` and
+`.github/workflows/release-please.yml` as the trusted publisher. The publish job
+uses an `npm` GitHub environment. Add required reviewers to that environment if
+releases need manual approval.
+
+## License
+
+[MIT](LICENSE)

package/dist/api.js

@@ -0,0 +1 @@
+const e=120,n="/live-preview-bridge/script.js",t="https://directus.invalid";function r(e={}){const n=window;if(n.__directusLivePreviewBridgeInstalled)return;n.__directusLivePreviewBridgeInstalled=!0;const t=Number.isInteger(e.pollIntervalMs)&&Number(e.pollIntervalMs)>=50&&Number(e.pollIntervalMs)<=5e3?Number(e.pollIntervalMs):120;let r=null,i=null,l=null;function o(e){return"object"==typeof e&&null!==e&&!Array.isArray(e)}function s(e){if("string"==typeof e.collection&&e.collection)return e.collection;if(!Array.isArray(e.fields))return null;const n=e.fields[0];return o(n)&&"string"==typeof n.collection&&n.collection&&e.fields.every(e=>o(e)&&e.collection===n.collection)?n.collection:null}function c(e){const n=Array.from(document.querySelectorAll("[data-v-app]"),e=>e._vnode),t=new Set;for(;n.length;){const r=n.pop();if(!o(r)||t.has(r))continue;t.add(r);const i=r,l=i.component;if(l){if(l.isUnmounted||l.isDeactivated)continue;const t=l.props;if(l.subTree?.el===e&&t&&null!==s(t)&&"modelValue"in t&&"initialValues"in t)return l;n.push(l.subTree)}else i.suspense?n.push(i.suspense.activeBranch):Array.isArray(i.children)&&n.push(...i.children)}return null}function u(){const e=document.querySelector(".live-preview iframe#frame");return e instanceof HTMLIFrameElement&&e.contentWindow?e:null}function a(e){try{const n=new URL(e.src);return"http:"!==n.protocol&&"https:"!==n.protocol?null:n.origin}catch{return null}}function p(){const e=u(),n=e?function(){for(const e of document.querySelectorAll(".v-form")){const n=!l||l.isUnmounted||l.isDeactivated||l.subTree?.el!==e?c(e):l,t=n?.props;if(!t)continue;const r=s(t);if(r)return l=n,t.loading?null:{collection:r,edits:o(t.modelValue)?t.modelValue:{},initialValues:o(t.initialValues)?t.initialValues:{},primaryKey:t.primaryKey??null}}return l=null,null}():null;if(!e||!n)return l=null,r=null,void(i=null);const t=a(e);if(!t)return;const p=function(e){try{return JSON.stringify(e)}catch{return null}}({type:"directus-live-preview-bridge:edits",...n});if(null===p)return;const d=`${e.src}\0${p}`;e===r&&d===i||(e.contentWindow?.postMessage(JSON.parse(p),t),r=e,i=d)}window.addEventListener("message",e=>{if("directus-live-preview-bridge:ready"!==e.data?.type)return;const n=u();if(!n||e.source!==n.contentWindow)return;const t=a(n);t&&e.origin===t&&(i=null,p())}),window.setInterval(p,t)}const i=[{name:"live-preview-bridge-hook",config:({embed:e},{env:r,logger:i})=>{const l=r.LIVE_PREVIEW_BRIDGE_SCRIPT_PATH,o=function(e){if(null==e||""===e)return n;if("string"!=typeof e||!e.startsWith("/"))return n;try{const r=new URL(e,t);return r.origin!==t?n:`${r.pathname}${r.search}${r.hash}`}catch{return n}}(l);var s;l&&l!==n&&o===n&&i.warn("LIVE_PREVIEW_BRIDGE_SCRIPT_PATH must be a same-origin, root-relative URL path. Using the default path."),e("body",`<script defer src="${s=o,s.replaceAll("&","&amp;").replaceAll('"',"&quot;").replaceAll("'","&#39;").replaceAll("<","&lt;").replaceAll(">","&gt;")}"><\/script>`)}}],l=[{name:"live-preview-bridge-endpoint",config:{id:"live-preview-bridge",handler(n,{env:t,logger:i}){const l=t.LIVE_PREVIEW_BRIDGE_POLL_INTERVAL_MS,o=function(n){if(null==n||""===n)return e;const t=Number(n);return!Number.isInteger(t)||t<50||t>5e3?e:t}(l);void 0!==l&&o===e&&Number(l)!==e&&i.warn("LIVE_PREVIEW_BRIDGE_POLL_INTERVAL_MS must be an integer from 50 through 5000. Using 120 ms.");const s=function(e){const n=JSON.stringify({pollIntervalMs:e});return`;(${r.toString()})(${n});`}(o);n.get("/script.js",(e,n)=>{n.set("Cache-Control","no-store").set("X-Content-Type-Options","nosniff").type("application/javascript").send(s)})}}}],o=[];export{l as endpoints,i as hooks,o as operations};

package/dist/app.js

@@ -0,0 +1 @@
+const o=[],t=[],c=[],e=[],n=[],p=[],r=[];export{t as displays,o as interfaces,c as layouts,e as modules,r as operations,n as panels,p as themes};

package/docs/nextjs.md

@@ -0,0 +1,402 @@
+# Use the bridge with Next.js Draft Mode
+
+This example uses the Next.js App Router and its async request APIs. It matches
+Next.js 15 and 16, where `draftMode()` returns a promise. The example collection
+is `articles`, with `id`, `status`, `title`, and `body` fields.
+
+Draft Mode and this bridge solve different parts of previewing:
+
+| Part                 | Responsibility                                                                                                             |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| Directus item status | Determines whether a saved item is a draft or published.                                                                   |
+| Next.js Draft Mode   | Sets a browser cookie so Next.js renders the request using draft-aware data fetching instead of a cached published result. |
+| Live Preview bridge  | Sends the values currently typed in the Directus form, including changes that have not been saved.                         |
+
+The request flow is straightforward. Directus opens a protected Next.js route
+inside its Live Preview iframe. That route validates the request, enables Draft
+Mode, and redirects to the article page. The Server Component fetches the saved
+draft as its initial value. After hydration, the client component receives
+unsaved form edits from the bridge and merges the supported fields into React
+state.
+
+Next.js documents the Draft Mode cookie and async API in its
+[Draft Mode guide](https://nextjs.org/docs/app/guides/draft-mode). Directus
+documents the collection Preview URL in its
+[Live Preview guide](https://directus.io/docs/tutorials/getting-started/set-up-live-preview-with-next-js).
+
+## 1. Configure environment variables
+
+Add these values to the Next.js project:
+
+```env
+# Available to the client. This is an origin, not an API token.
+NEXT_PUBLIC_DIRECTUS_URL=https://directus.example.com
+
+# Server-only token with read access to the fields used by the preview.
+DIRECTUS_SERVER_TOKEN=replace-with-a-limited-read-token
+
+# Shared by the Next.js preview route and the Directus Preview URL.
+DIRECTUS_PREVIEW_SECRET=replace-with-a-long-random-value
+```
+
+Keep `DIRECTUS_SERVER_TOKEN` and `DIRECTUS_PREVIEW_SECRET` out of variables with
+the `NEXT_PUBLIC_` prefix. The browser does not need either secret. Give the
+Directus token read access only to the collections and fields the preview uses.
+
+## 2. Fetch saved Directus data on the server
+
+Create `lib/directus.ts`. This helper fetches the saved draft while Draft Mode
+is enabled. Normal visitors only receive items whose status is `published`.
+
+```ts
+export type Article = {
+  id: string;
+  status: 'draft' | 'published' | 'archived';
+  title: string;
+  body: string;
+};
+
+type DirectusListResponse<T> = {
+  data: T[];
+};
+
+const directusUrl = process.env.NEXT_PUBLIC_DIRECTUS_URL;
+const directusToken = process.env.DIRECTUS_SERVER_TOKEN;
+
+if (!directusUrl || !directusToken) {
+  throw new Error(
+    'NEXT_PUBLIC_DIRECTUS_URL and DIRECTUS_SERVER_TOKEN are required.',
+  );
+}
+
+export async function getArticle(
+  id: string,
+  includeDrafts: boolean,
+): Promise<Article | null> {
+  const baseUrl = directusUrl.endsWith('/') ? directusUrl : `${directusUrl}/`;
+  const url = new URL('items/articles', baseUrl);
+  const filter = {
+    id: { _eq: id },
+    ...(includeDrafts ? {} : { status: { _eq: 'published' } }),
+  };
+
+  url.searchParams.set('filter', JSON.stringify(filter));
+  url.searchParams.set('fields', 'id,status,title,body');
+  url.searchParams.set('limit', '1');
+
+  const response = await fetch(url, {
+    headers: {
+      Authorization: `Bearer ${directusToken}`,
+    },
+    ...(includeDrafts
+      ? { cache: 'no-store' as const }
+      : { next: { revalidate: 60 } }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Directus returned ${response.status}.`);
+  }
+
+  const result = (await response.json()) as DirectusListResponse<Article>;
+  return result.data[0] ?? null;
+}
+```
+
+The `no-store` branch is deliberate. Draft requests should not share a cached
+response with another request. Change the published revalidation interval to
+match the site's normal caching policy. Adjust the status names and fields if
+the Directus collection uses different values. Keep any Directus reverse-proxy
+path in `NEXT_PUBLIC_DIRECTUS_URL`; the URL construction above preserves it.
+
+## 3. Enable Draft Mode through a protected route
+
+Create `app/api/draft/route.ts`:
+
+```ts
+import { draftMode } from 'next/headers';
+import { redirect } from 'next/navigation';
+
+import { getArticle } from '@/lib/directus';
+
+const VALID_ID = /^[A-Za-z0-9_-]+$/;
+
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url);
+  const secret = searchParams.get('secret');
+  const id = searchParams.get('id');
+
+  if (
+    !process.env.DIRECTUS_PREVIEW_SECRET ||
+    secret !== process.env.DIRECTUS_PREVIEW_SECRET
+  ) {
+    return new Response('Invalid preview secret.', { status: 401 });
+  }
+
+  if (!id || !VALID_ID.test(id)) {
+    return new Response('Invalid article ID.', { status: 400 });
+  }
+
+  const article = await getArticle(id, true);
+
+  if (!article) {
+    return new Response('Article not found.', { status: 404 });
+  }
+
+  const draft = await draftMode();
+  draft.enable();
+
+  redirect(`/articles/${encodeURIComponent(article.id)}`);
+}
+```
+
+The route checks that the item exists before setting the Draft Mode cookie. It
+also constructs the redirect from the verified item instead of redirecting to an
+arbitrary query parameter. That avoids turning the route into an open redirect.
+
+The cookie is named `__prerender_bypass`. Next.js generates a new value for each
+build, so a deployment invalidates older Draft Mode cookies. Draft Mode does not
+grant Directus access by itself. The server-only Directus token still controls
+which saved records the page can fetch.
+
+## 4. Configure the Directus Preview URL
+
+In Directus, open **Settings > Data Model > Articles** and set the Preview URL
+to this pattern:
+
+```text
+https://frontend.example.com/api/draft?secret=YOUR_SECRET&id=ID
+```
+
+Use the Directus field picker to insert the `ID` field after `id=`. Replace
+`YOUR_SECRET` with the same value as `DIRECTUS_PREVIEW_SECRET`. Use HTTPS
+outside local development because the secret is part of the URL.
+
+When an editor opens Live Preview, Directus loads this URL in its iframe. The
+route sets the cookie and redirects the iframe to `/articles/<id>`.
+
+If the Next.js application sends a Content Security Policy, its
+`frame-ancestors` directive must allow the Directus origin. Remove conflicting
+`X-Frame-Options: SAMEORIGIN` headers. Otherwise the browser will refuse to
+render the site inside Directus.
+
+## 5. Read Draft Mode in the page
+
+Create `app/articles/[id]/page.tsx`:
+
+```tsx
+import { draftMode } from 'next/headers';
+import { notFound } from 'next/navigation';
+
+import { ArticlePreview } from '@/components/article-preview';
+import { getArticle } from '@/lib/directus';
+
+export default async function ArticlePage({
+  params,
+}: {
+  params: Promise<{ id: string }>;
+}) {
+  const [{ id }, { isEnabled }] = await Promise.all([params, draftMode()]);
+  const article = await getArticle(id, isEnabled);
+
+  if (!article) notFound();
+
+  const directusUrl = process.env.NEXT_PUBLIC_DIRECTUS_URL;
+
+  if (!directusUrl) {
+    throw new Error('NEXT_PUBLIC_DIRECTUS_URL is required.');
+  }
+
+  return (
+    <ArticlePreview
+      key={article.id}
+      initialArticle={article}
+      directusUrl={directusUrl}
+      livePreviewEnabled={isEnabled}
+    />
+  );
+}
+```
+
+`draftMode()` is async in current Next.js releases. The page starts `params` and
+`draftMode()` together to avoid waiting for them one at a time. The item fetch
+begins after both values are available because it needs the ID and the Draft
+Mode state.
+
+## 6. Apply unsaved edits in a client component
+
+Create `components/article-preview.tsx`:
+
+```tsx
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+import type { Article } from '@/lib/directus';
+
+const EDITS_MESSAGE_TYPE = 'directus-live-preview-bridge:edits';
+const READY_MESSAGE_TYPE = 'directus-live-preview-bridge:ready';
+const ALLOWED_COLLECTIONS = new Set(['articles']);
+
+type LivePreviewMessage = {
+  type: typeof EDITS_MESSAGE_TYPE;
+  collection: string;
+  primaryKey: unknown;
+  edits: Record<string, unknown>;
+  initialValues?: Record<string, unknown>;
+};
+
+function useDirectusLivePreview({
+  directusUrl,
+  enabled,
+  onEdits,
+}: {
+  directusUrl: string;
+  enabled: boolean;
+  onEdits: (message: LivePreviewMessage) => void;
+}) {
+  const onEditsRef = useRef(onEdits);
+
+  useEffect(() => {
+    onEditsRef.current = onEdits;
+  }, [onEdits]);
+
+  useEffect(() => {
+    if (!enabled || window.parent === window) return;
+
+    const directusOrigin = new URL(directusUrl).origin;
+
+    function receiveEdits(event: MessageEvent) {
+      if (event.origin !== directusOrigin || event.source !== window.parent) {
+        return;
+      }
+
+      const message = event.data;
+
+      if (
+        !message ||
+        message.type !== EDITS_MESSAGE_TYPE ||
+        typeof message.collection !== 'string' ||
+        !ALLOWED_COLLECTIONS.has(message.collection) ||
+        typeof message.edits !== 'object' ||
+        message.edits === null ||
+        Array.isArray(message.edits) ||
+        (message.initialValues !== undefined &&
+          (typeof message.initialValues !== 'object' ||
+            message.initialValues === null ||
+            Array.isArray(message.initialValues)))
+      ) {
+        return;
+      }
+
+      onEditsRef.current(message);
+    }
+
+    window.addEventListener('message', receiveEdits);
+    window.parent.postMessage({ type: READY_MESSAGE_TYPE }, directusOrigin);
+
+    return () => window.removeEventListener('message', receiveEdits);
+  }, [directusUrl, enabled]);
+}
+
+export function ArticlePreview({
+  initialArticle,
+  directusUrl,
+  livePreviewEnabled,
+}: {
+  initialArticle: Article;
+  directusUrl: string;
+  livePreviewEnabled: boolean;
+}) {
+  const [snapshot, setSnapshot] = useState<LivePreviewMessage | null>(null);
+  const activeSnapshot =
+    livePreviewEnabled &&
+    String(snapshot?.primaryKey) === String(initialArticle.id)
+      ? snapshot
+      : null;
+  const baseline = activeSnapshot?.initialValues ?? initialArticle;
+  const edits = activeSnapshot?.edits ?? {};
+  const article = {
+    ...initialArticle,
+    title:
+      typeof edits.title === 'string'
+        ? edits.title
+        : typeof baseline.title === 'string'
+          ? baseline.title
+          : initialArticle.title,
+    body:
+      typeof edits.body === 'string'
+        ? edits.body
+        : typeof baseline.body === 'string'
+          ? baseline.body
+          : initialArticle.body,
+  };
+
+  useDirectusLivePreview({
+    directusUrl,
+    enabled: livePreviewEnabled,
+    onEdits(message) {
+      if (
+        message.collection !== 'articles' ||
+        String(message.primaryKey) !== String(initialArticle.id)
+      ) {
+        return;
+      }
+
+      setSnapshot(message);
+    },
+  });
+
+  return (
+    <main>
+      <h1>{article.title}</h1>
+      <p>{article.body}</p>
+    </main>
+  );
+}
+```
+
+The effect installs one global listener and removes it during cleanup. The
+callback ref lets React use the latest edit handler without removing and adding
+the window listener after every render. Each message replaces the previous
+snapshot. The component derives the article from saved `initialValues` plus
+current `edits`, validating each accepted field. Removing an edit restores its
+saved value, and a save updates the baseline. When an older bridge omits
+`initialValues`, the server-fetched article supplies the baseline.
+
+Keep the listener in one client component near the preview page root. If many
+descendants need the edited article, put the state in a React context provider
+and keep this same single listener in the provider.
+
+## 7. Add an optional exit route
+
+Draft Mode lasts until its cookie is cleared or the browser session ends. To
+provide an explicit exit, create `app/api/draft/disable/route.ts`:
+
+```ts
+import { draftMode } from 'next/headers';
+import { redirect } from 'next/navigation';
+
+export async function GET() {
+  const draft = await draftMode();
+  draft.disable();
+  redirect('/');
+}
+```
+
+Link to `/api/draft/disable` with a normal anchor. If `next/link` is used, set
+`prefetch={false}` so prefetching cannot clear Draft Mode before the editor
+clicks the link.
+
+## Cookies inside the Directus iframe
+
+Draft Mode relies on a browser cookie. A Directus instance and preview site on
+different sites can trigger third-party cookie restrictions because the Next.js
+page runs inside a Directus iframe. For local HTTP testing, Next.js explicitly
+requires third-party cookies and storage access to be allowed. If the cookie is
+blocked, host Directus and the preview site under the same parent site or adjust
+the browser policy used by editors.
+
+You can confirm Draft Mode is active by inspecting the iframe request for the
+`__prerender_bypass` cookie. You can confirm the bridge separately by watching
+for `directus-live-preview-bridge:ready` and
+`directus-live-preview-bridge:edits` messages in the browser developer tools.

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "directus-live-preview-bridge",
+  "version": "0.1.0",
+  "description": "Stream unsaved Directus item edits to Live Preview frontends.",
+  "icon": "preview",
+  "keywords": [
+    "directus",
+    "directus-extension",
+    "directus-extension-bundle",
+    "live-preview"
+  ],
+  "homepage": "https://github.com/ritsa-tech/directus-live-preview-bridge#readme",
+  "bugs": {
+    "url": "https://github.com/ritsa-tech/directus-live-preview-bridge/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ritsa-tech/directus-live-preview-bridge.git"
+  },
+  "author": {
+    "name": "Ritsa Tech",
+    "url": "https://ritsa.tech"
+  },
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "directus:extension": {
+    "type": "bundle",
+    "partial": false,
+    "path": {
+      "app": "dist/app.js",
+      "api": "dist/api.js"
+    },
+    "entries": [
+      {
+        "type": "hook",
+        "name": "live-preview-bridge-hook",
+        "source": "src/hook/index.ts"
+      },
+      {
+        "type": "endpoint",
+        "name": "live-preview-bridge-endpoint",
+        "source": "src/endpoint/index.ts"
+      }
+    ],
+    "host": "^12.0.0"
+  },
+  "scripts": {
+    "add": "directus-extension add",
+    "build": "directus-extension build",
+    "check": "npm run typecheck && npm run test && npm run format:check && npm run build && npm run test:dist && npm run validate",
+    "dev": "directus-extension build --watch --no-minify",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "link": "directus-extension link",
+    "prepack": "npm run check",
+    "test": "vitest run",
+    "test:dist": "node scripts/check-dist.mjs",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "validate": "directus-extension validate"
+  },
+  "devDependencies": {
+    "@directus/extensions-sdk": "18.0.4",
+    "@types/node": "^22.20.1",
+    "happy-dom": "^20.14.0",
+    "prettier": "^3.9.6",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "vue": "^3.5.24"
+  }
+}