fontdue-js 3.0.0-alpha12 → 3.0.0-alpha13

package/.playwright-mcp/console-2026-06-15T09-14-00-118Z.log

@@ -0,0 +1,84 @@
+[     597ms] [INFO] %cDownload the React DevTools for a better development experience: https://react.dev/link/react-devtools font-weight:bold @ webpack-internal:///(app-pages-browser)/./node_modules/next/dist/compiled/react-dom/cjs/react-dom-client.development.js:25630
+[     747ms] Error: Switched to client rendering because the server rendering errored:
+
+Relay: Missing @required value at path 'collection' in 'BuyButtonIDQuery'.
+    at handleFieldErrors (webpack-internal:///(ssr)/./node_modules/relay-runtime/lib/util/handlePotentialSnapshotErrors.js:36:19)
+    at handlePotentialSnapshotErrors (webpack-internal:///(ssr)/./node_modules/relay-runtime/lib/util/handlePotentialSnapshotErrors.js:70:5)
+    at handlePotentialSnapshotErrorsForState (webpack-internal:///(ssr)/./node_modules/react-relay/lib/relay-hooks/useFragmentInternal_CURRENT.js:120:5)
+    at useFragmentInternal (webpack-internal:///(ssr)/./node_modules/react-relay/lib/relay-hooks/useFragmentInternal_CURRENT.js:420:3)
+    at useFragmentInternal (webpack-internal:///(ssr)/./node_modules/react-relay/lib/relay-hooks/useFragmentInternal.js:11:54)
+    at useLazyLoadQueryNode (webpack-internal:///(ssr)/./node_modules/react-relay/lib/relay-hooks/useLazyLoadQueryNode.js:64:14)
+    at useLazyLoadQuery (webpack-internal:///(ssr)/./node_modules/react-relay/lib/relay-hooks/useLazyLoadQuery.js:13:14)
+    at BuyButtonIDQueryRenderer (webpack-internal:///(ssr)/./node_modules/fontdue-js/dist/components/BuyButton/index.js:104:79)
+    at Object.react_stack_bottom_frame (/Users/tom/code/fontdue/generaltype/node_modules/next/dist/compiled/next-server/app-page.runtime.dev.js:2:292649)
+    at renderWithHooks (/Users/tom/code/fontdue/generaltype/node_modules/next/dist/compiled/next-server/app-page.runtime.dev.js:2:114080)
+    at renderElement (/Users/tom/code/fontdue/generaltype/node_modules/next/dist/compiled/next-server/app-page.runtime.dev.js:2:128752)
+    at retryNode (/Users/tom/code/fontdue/generaltype/node_modules/next/dist/compiled/next-server/app-page.runtime.dev.js:2:194584)
+    at performWork (/Users/tom/code/fontdue/generaltype/node_modules/next/dist/compiled/next-server/app-page.runtime.dev.js:2:215436)
+    at Immediate._onImmediate (/Users/tom/code/fontdue/generaltype/node_modules/next/dist/compiled/next-server/app-page.runtime.dev.js:2:98974)
+    at process.processImmediate (node:internal/timers:491:21)
+    at process.callbackTrampoline (node:internal/async_hooks:130:17)
+[    1442ms] Error: Relay: Missing @required value at path 'collection' in 'BuyButtonIDQuery'.
+    at handleFieldErrors (webpack-internal:///(app-pages-browser)/./node_modules/relay-runtime/lib/util/handlePotentialSnapshotErrors.js:36:19)
+    at handlePotentialSnapshotErrors (webpack-internal:///(app-pages-browser)/./node_modules/relay-runtime/lib/util/handlePotentialSnapshotErrors.js:70:5)
+    at handlePotentialSnapshotErrorsForState (webpack-internal:///(app-pages-browser)/./node_modules/react-relay/lib/relay-hooks/useFragmentInternal_CURRENT.js:120:5)
+    at useFragmentInternal (webpack-internal:///(app-pages-browser)/./node_modules/react-relay/lib/relay-hooks/useFragmentInternal_CURRENT.js:420:3)
+    at useFragmentInternal (webpack-internal:///(app-pages-browser)/./node_modules/react-relay/lib/relay-hooks/useFragmentInternal.js:11:54)
+    at useLazyLoadQueryNode (webpack-internal:///(app-pages-browser)/./node_modules/react-relay/lib/relay-hooks/useLazyLoadQueryNode.js:64:14)
+    at useLazyLoadQuery (webpack-internal:///(app-pages-browser)/./node_modules/react-relay/lib/relay-hooks/useLazyLoadQuery.js:13:14)
+    at BuyButtonIDQueryRenderer (webpack-internal:///(app-pages-browser)/./node_modules/fontdue-js/dist/components/BuyButton/index.js:116:79)
+    at Object.react_stack_bottom_frame (webpack-internal:///(app-pages-browser)/./node_modules/next/dist/compiled/react-dom/cjs/react-dom-client.development.js:23584:20)
+    at renderWithHooks (webpack-internal:///(app-pages-browser)/./node_modules/next/dist/compiled/react-dom/cjs/react-dom-client.development.js:6793:22)
+    at updateFunctionComponent (webpack-internal:///(app-pages-browser)/./node_modules/next/dist/compiled/react-dom/cjs/react-dom-client.development.js:9247:19)
+    at beginWork (webpack-internal:///(app-pages-browser)/./node_modules/next/dist/compiled/react-dom/cjs/react-dom-client.development.js:10858:18)
+    at runWithFiberInDEV (webpack-internal:///(app-pages-browser)/./node_modules/next/dist/compiled/react-dom/cjs/react-dom-client.development.js:872:30)
+    at performUnitOfWork (webpack-internal:///(app-pages-browser)/./node_modules/next/dist/compiled/react-dom/cjs/react-dom-client.development.js:15727:22)
+    at workLoopSync (webpack-internal:///(app-pages-browser)/./node_modules/next/dist/compiled/react-dom/cjs/react-dom-client.development.js:15547:41)
+    at renderRootSync (webpack-internal:///(app-pages-browser)/./node_modules/next/dist/compiled/react-dom/cjs/react-dom-client.development.js:15527:11)
+    at performWorkOnRoot (webpack-internal:///(app-pages-browser)/./node_modules/next/dist/compiled/react-dom/cjs/react-dom-client.development.js:15034:44)
+    at performWorkOnRootViaSchedulerTask (webpack-internal:///(app-pages-browser)/./node_modules/next/dist/compiled/react-dom/cjs/react-dom-client.development.js:16816:7)
+    at MessagePort.performWorkUntilDeadline (webpack-internal:///(app-pages-browser)/./node_modules/next/dist/compiled/scheduler/cjs/scheduler.development.js:45:48)
+[  217249ms] [LOG] [Fast Refresh] rebuilding @ webpack-internal:///(app-pages-browser)/./node_modules/next/dist/client/dev/hot-reloader/app/hot-reloader-app.js:196
+[  217808ms] [WARNING] [Fast Refresh] performing full reload because your application had an unrecoverable error @ webpack-internal:///(app-pages-browser)/./node_modules/next/dist/client/dev/hot-reloader/app/hot-reloader-app.js:113
+[  219163ms] [INFO] %cDownload the React DevTools for a better development experience: https://react.dev/link/react-devtools font-weight:bold @ webpack-internal:///(app-pages-browser)/./node_modules/next/dist/compiled/react-dom/cjs/react-dom-client.development.js:25630
+[  730814ms] [INFO] %cDownload the React DevTools for a better development experience: https://react.dev/link/react-devtools font-weight:bold @ webpack-internal:///(app-pages-browser)/./node_modules/next/dist/compiled/react-dom/cjs/react-dom-client.development.js:25630
+[  735697ms] [INFO] %cDownload the React DevTools for a better development experience: https://react.dev/link/react-devtools font-weight:bold @ webpack-internal:///(app-pages-browser)/./node_modules/next/dist/compiled/react-dom/cjs/react-dom-client.development.js:25630
+[  735780ms] Error: Switched to client rendering because the server rendering errored:
+
+Relay: Missing @required value at path 'collection' in 'BuyButtonIDQuery'.
+    at handleFieldErrors (webpack-internal:///(ssr)/./node_modules/relay-runtime/lib/util/handlePotentialSnapshotErrors.js:36:19)
+    at handlePotentialSnapshotErrors (webpack-internal:///(ssr)/./node_modules/relay-runtime/lib/util/handlePotentialSnapshotErrors.js:70:5)
+    at handlePotentialSnapshotErrorsForState (webpack-internal:///(ssr)/./node_modules/react-relay/lib/relay-hooks/useFragmentInternal_CURRENT.js:120:5)
+    at useFragmentInternal (webpack-internal:///(ssr)/./node_modules/react-relay/lib/relay-hooks/useFragmentInternal_CURRENT.js:420:3)
+    at useFragmentInternal (webpack-internal:///(ssr)/./node_modules/react-relay/lib/relay-hooks/useFragmentInternal.js:11:54)
+    at useLazyLoadQueryNode (webpack-internal:///(ssr)/./node_modules/react-relay/lib/relay-hooks/useLazyLoadQueryNode.js:64:14)
+    at useLazyLoadQuery (webpack-internal:///(ssr)/./node_modules/react-relay/lib/relay-hooks/useLazyLoadQuery.js:13:14)
+    at BuyButtonIDQueryRenderer (webpack-internal:///(ssr)/./node_modules/fontdue-js/dist/components/BuyButton/index.js:104:79)
+    at Object.react_stack_bottom_frame (/Users/tom/code/fontdue/generaltype/node_modules/next/dist/compiled/next-server/app-page.runtime.dev.js:2:292649)
+    at renderWithHooks (/Users/tom/code/fontdue/generaltype/node_modules/next/dist/compiled/next-server/app-page.runtime.dev.js:2:114080)
+    at renderElement (/Users/tom/code/fontdue/generaltype/node_modules/next/dist/compiled/next-server/app-page.runtime.dev.js:2:128752)
+    at retryNode (/Users/tom/code/fontdue/generaltype/node_modules/next/dist/compiled/next-server/app-page.runtime.dev.js:2:194584)
+    at performWork (/Users/tom/code/fontdue/generaltype/node_modules/next/dist/compiled/next-server/app-page.runtime.dev.js:2:215436)
+    at Immediate._onImmediate (/Users/tom/code/fontdue/generaltype/node_modules/next/dist/compiled/next-server/app-page.runtime.dev.js:2:98974)
+    at process.processImmediate (node:internal/timers:491:21)
+    at process.callbackTrampoline (node:internal/async_hooks:130:17)
+[  747981ms] [INFO] %cDownload the React DevTools for a better development experience: https://react.dev/link/react-devtools font-weight:bold @ webpack-internal:///(app-pages-browser)/./node_modules/next/dist/compiled/react-dom/cjs/react-dom-client.development.js:25630
+[  748069ms] Error: Switched to client rendering because the server rendering errored:
+
+Relay: Missing @required value at path 'collection' in 'BuyButtonIDQuery'.
+    at handleFieldErrors (webpack-internal:///(ssr)/./node_modules/relay-runtime/lib/util/handlePotentialSnapshotErrors.js:36:19)
+    at handlePotentialSnapshotErrors (webpack-internal:///(ssr)/./node_modules/relay-runtime/lib/util/handlePotentialSnapshotErrors.js:70:5)
+    at handlePotentialSnapshotErrorsForState (webpack-internal:///(ssr)/./node_modules/react-relay/lib/relay-hooks/useFragmentInternal_CURRENT.js:120:5)
+    at useFragmentInternal (webpack-internal:///(ssr)/./node_modules/react-relay/lib/relay-hooks/useFragmentInternal_CURRENT.js:420:3)
+    at useFragmentInternal (webpack-internal:///(ssr)/./node_modules/react-relay/lib/relay-hooks/useFragmentInternal.js:11:54)
+    at useLazyLoadQueryNode (webpack-internal:///(ssr)/./node_modules/react-relay/lib/relay-hooks/useLazyLoadQueryNode.js:64:14)
+    at useLazyLoadQuery (webpack-internal:///(ssr)/./node_modules/react-relay/lib/relay-hooks/useLazyLoadQuery.js:13:14)
+    at BuyButtonIDQueryRenderer (webpack-internal:///(ssr)/./node_modules/fontdue-js/dist/components/BuyButton/index.js:104:79)
+    at Object.react_stack_bottom_frame (/Users/tom/code/fontdue/generaltype/node_modules/next/dist/compiled/next-server/app-page.runtime.dev.js:2:292649)
+    at renderWithHooks (/Users/tom/code/fontdue/generaltype/node_modules/next/dist/compiled/next-server/app-page.runtime.dev.js:2:114080)
+    at renderElement (/Users/tom/code/fontdue/generaltype/node_modules/next/dist/compiled/next-server/app-page.runtime.dev.js:2:128752)
+    at retryNode (/Users/tom/code/fontdue/generaltype/node_modules/next/dist/compiled/next-server/app-page.runtime.dev.js:2:194584)
+    at performWork (/Users/tom/code/fontdue/generaltype/node_modules/next/dist/compiled/next-server/app-page.runtime.dev.js:2:215436)
+    at Immediate._onImmediate (/Users/tom/code/fontdue/generaltype/node_modules/next/dist/compiled/next-server/app-page.runtime.dev.js:2:98974)
+    at process.processImmediate (node:internal/timers:491:21)
+    at process.callbackTrampoline (node:internal/async_hooks:130:17)

package/.playwright-mcp/console-2026-06-15T09-25-42-726Z.log

@@ -0,0 +1,2 @@
+[    4008ms] [ERROR] Refused to get unsafe header "X-Sg-Cs" @ https://www.google.com/search?q=generaltype.fontdue.xuyz&oq=generaltype.fontdue.xuyz&gs_lcrp=EgZjaHJvbWUyBggAEEUYOdIBCDMwODhqMGo3qAIAsAIA&sourceid=chrome&ie=UTF-8&sei=HMUvapfSAv7Ii-gP_8yN6A0:68
+[    4008ms] [ERROR] Refused to get unsafe header "X-Sorry-Redirect" @ https://www.google.com/search?q=generaltype.fontdue.xuyz&oq=generaltype.fontdue.xuyz&gs_lcrp=EgZjaHJvbWUyBggAEEUYOdIBCDMwODhqMGo3qAIAsAIA&sourceid=chrome&ie=UTF-8&sei=HMUvapfSAv7Ii-gP_8yN6A0:68

package/.playwright-mcp/console-2026-06-15T09-25-47-707Z.log

@@ -0,0 +1 @@
+[    5170ms] [VERBOSE] [DOM] Input elements should have autocomplete attributes (suggested: "current-password"): (More info: https://goo.gl/9p2vKq) %o @ https://www.fontdue.xyz/login?redirect_to=%2Fadmin:0

package/.playwright-mcp/page-2026-06-15T09-14-01-054Z.yml

@@ -0,0 +1,13 @@
+- generic [active] [ref=e1]:
+  - generic [ref=e6] [cursor=pointer]:
+    - button "Open Next.js Dev Tools" [ref=e7]:
+      - img [ref=e8]
+    - generic [ref=e11]:
+      - button "Open issues overlay" [ref=e12]:
+        - generic [ref=e13]:
+          - generic [ref=e14]: "0"
+          - generic [ref=e15]: "1"
+        - generic [ref=e16]: Issue
+      - button "Collapse issues badge" [ref=e17]:
+        - img [ref=e18]
+  - alert [ref=e20]

package/CHANGELOG.md

@@ -7,8 +7,8 @@ In alpha on the `alpha` dist-tag — install with `npm install fontdue-js@alpha`
   - `fontdue-js/preview` — `handlePreviewRequest` (a Web-standard enter/exit route handler), `readPreviewToken`, `previewAuthHeaders`, and the cookie/endpoint constants.
   - `fontdue-js/preview/server` — `runWithPreview`, which holds the preview token in `AsyncLocalStorage` for the duration of a request so every server fetch and preload forwards it automatically, and forces preview responses out of shared/CDN caches so an admin's render is never served to the public.
 
-  On Next.js (which has no app-installable ambient context) the adapter's `prepareFontdueRender` folds the draft-mode token into the per-render config instead — the same effect, so the embedded components reveal hidden fonts server-side. See the README "Admin preview".
-- **One server fetch for every framework.** `fontdue-js/server` exports `createFontdueFetch({ url?, headers?, cacheTags? })` — a ready-made server-side GraphQL fetcher with URL resolution, error handling, `FontdueNotFoundError`, and automatic preview-token forwarding. Each input resolves per call from the explicit option, the per-render config (`runWithPreview` or the Next adapter), then the environment, and passing `cacheTags` opts the fetch into Next's data cache + `/api/revalidate` (inert in other runtimes) — so Next and the other frameworks now share the same fetcher rather than Next hand-rolling its own. See the README "Server-side GraphQL fetches".
+  Next.js uses draft mode rather than ambient context, and needs no per-render setup call: mounting `<FontdueProvider>` wires every server fetch and the embedded components' server preloads to forward the token, apply the cache tags for `/api/revalidate`, and serve a live render while previewing — including embeds rendered inside a Server Component, which now preload server-side with the admin token instead of falling back to a client refetch. `configureFontduePreview()` (from `fontdue-js/next`) stays exported for when you want the resolved endpoint inside a render (e.g. a `metadataBase` fallback), but it's optional. See the README "Admin preview".
+- **One server fetch for every framework.** `fontdue-js/server` exports `createFontdueFetch({ url?, headers?, cacheTags? })` — a ready-made server-side GraphQL fetcher with URL resolution, error handling, `FontdueNotFoundError`, and automatic preview-token forwarding. Each input resolves per call from the explicit option, the per-render config (`runWithPreview` elsewhere, or the config the Next adapter resolves per render once `<FontdueProvider>` is mounted), then the environment, and passing `cacheTags` opts the fetch into Next's data cache + `/api/revalidate` (inert in other runtimes) — so Next and the other frameworks now share the same fetcher rather than Next hand-rolling its own. See the README "Server-side GraphQL fetches".
 - **Server-rendered embeds.** Components now render their full HTML on the server where the framework supports it (v2 hydrated some empty and fetched on the client), via the `load{Component}Query()` preload helpers.
 - **Migrating from v2 (Next.js)** is a small, mechanical upgrade — see the README "Migrating a Next.js site from v2". `useFontStyle` is renamed to `useFont` (the old name still works as an alias).
 

package/README.md

@@ -413,30 +413,32 @@ export { POST } from "fontdue-js/next/revalidate";
 
 and set the Deploy hook URL in your Fontdue admin (Settings → Website settings) to `https://your-site.example/api/revalidate`. Fontdue calls it whenever your site's content changes, purging everything tagged `graphql` so the next request renders fresh.
 
-fontdue-js's own server-side fetches opt into Next's data cache (and the `graphql` tag) automatically — static pages revalidated by the deploy hook is the intended way to run a Fontdue site, not dynamic rendering. Give your own fetches the same treatment; `currentFontdueEndpoint()` below shows how.
+fontdue-js's own server-side fetches opt into Next's data cache (and the `graphql` tag) automatically — static pages revalidated by the deploy hook is the intended way to run a Fontdue site, not dynamic rendering. Give your own fetches the same treatment; the setup below shows how.
 
 ### Your own GraphQL fetches
 
-Use the same [`createFontdueFetch`](#server-side-graphql-fetches) as every other framework, and give it the current render's endpoint so it ties into Next's data cache and `/api/revalidate`. `currentFontdueEndpoint()` (from `fontdue-js/next`) describes that endpoint — the base origin, required headers, and the per-site cache tags:
+Use the same [`createFontdueFetch`](#server-side-graphql-fetches) as every other framework. Mounting `<FontdueProvider>` in your layout is enough to wire it up — there's no per-render setup call:
 
 ```ts
+// src/lib/graphql.ts
 import { createFontdueFetch } from "fontdue-js/server";
-import { currentFontdueEndpoint } from "fontdue-js/next";
-
-export async function fetchGraphql<Q>(name: string, query: string, variables?: unknown) {
-  const endpoint = currentFontdueEndpoint();
-  const fetchFontdue = createFontdueFetch({
-    url: endpoint.origin,
-    headers: endpoint.headers,
-    // Opts the fetch into Next's data cache (force-cache) and tags it so the
-    // deploy hook purges it. Drop cacheTags (pass `[]`) on a preview render.
-    cacheTags: endpoint.tags,
-  });
-  return fetchFontdue<Q>(name, query, variables);
+
+export const fetchGraphql = createFontdueFetch();
+```
+
+```ts
+// any page / layout / generateMetadata
+import { fetchGraphql } from "@/lib/graphql";
+
+export default async function Page() {
+  const data = await fetchGraphql<IndexQuery>("Index.graphql");
+  // …
 }
 ```
 
-`currentFontdueEndpoint()` resolves the per-render tenant in multi-tenant mode (after `prepareFontdueRender`) or the `NEXT_PUBLIC_FONTDUE_URL` site otherwise; the shape is exported as `type FontdueEndpoint`. Route handlers render outside React, so pass the endpoint they got from `prepareFontdueRender` explicitly. For preview, see [Admin preview → Next.js](#nextjs).
+`createFontdueFetch()` resolves its config per fetch from Next's request context: it points your fetches at your site (`NEXT_PUBLIC_FONTDUE_URL`), applies the cache tags that tie them into `/api/revalidate`, and — when a logged-in admin is previewing — forwards the admin token and serves the render live (see [Admin preview](#admin-preview)). Resolving per fetch means soft navigations that re-render only the page segment are covered too, with nothing to repeat per entry point.
+
+Route handlers (robots/sitemap) aren't React renders, so they read the endpoint from `fontdueEndpoint()` (from `fontdue-js/next`; shape: `type FontdueEndpoint`) and pass it to `createFontdueFetch({ url, headers, cacheTags })` directly. `configureFontduePreview()` is still exported if you want the resolved endpoint inside a render (e.g. a `metadataBase` fallback), but it's optional now that mounting the provider wires the config up.
 
 ## Migrating a Next.js site from v2
 
@@ -468,7 +470,7 @@ For a site built on the [example repo](https://github.com/fontdue/example-next)
 
    Keep the Deploy hook URL in your Fontdue admin pointed at it.
 
-4. **Delete caching workarounds you no longer need.** `export const fetchCache = "default-cache"` in the layout (if you added it) is obsolete — fontdue-js opts its own fetches into the data cache now. For your app's own GraphQL fetches, move the transport to `createFontdueFetch` and pass it `cacheTags: endpoint.tags` so caching and `/api/revalidate` are handled for you — see [Your own GraphQL fetches](#your-own-graphql-fetches).
+4. **Delete caching workarounds you no longer need.** `export const fetchCache = "default-cache"` in the layout (if you added it) is obsolete — fontdue-js opts its own fetches into the data cache now. For your app's own GraphQL fetches, move the transport to `createFontdueFetch`; mounting `<FontdueProvider>` then handles caching, `/api/revalidate`, and admin preview for you — see [Your own GraphQL fetches](#your-own-graphql-fetches).
 
 5. **Remove the `url` prop from `<FontdueProvider>` if you passed one.** It never configured server-side fetches (server components have no context); v3 resolves everything from `NEXT_PUBLIC_FONTDUE_URL`. The prop still works as a client-side runtime override, but with the env var set you don't need it.
 
@@ -493,10 +495,10 @@ export const fetchGraphql = createFontdueFetch();
 const data = await fetchGraphql<IndexQuery>("Index", indexQuery, { slug });
 ```
 
-`createFontdueFetch({ url?, headers?, cacheTags? })` returns `fetchGraphql(operationName, query, variables?)`. It POSTs to `/graphql`, unwraps `data`, throws on GraphQL errors, and throws `FontdueNotFoundError` when the host doesn't resolve to a site — catch it to render your framework's 404. It's the same fetcher in every framework; each input resolves per call from the explicit option, then the per-render config (set by `runWithPreview` or the Next adapter), then the environment:
+`createFontdueFetch({ url?, headers?, cacheTags? })` returns `fetchGraphql(operationName, query, variables?)`. It POSTs to `/graphql`, unwraps `data`, throws on GraphQL errors, and throws `FontdueNotFoundError` when the host doesn't resolve to a site — catch it to render your framework's 404. It's the same fetcher in every framework; each input resolves per call:
 
-- **url** — option → per-render tenant URL → `FONTDUE_URL` / `PUBLIC_FONTDUE_URL` / `VITE_FONTDUE_URL`.
-- **headers** — merged ambient + explicit (explicit wins); this is how the [admin preview](#admin-preview) token is forwarded automatically.
+- **url** — the explicit option, else `FONTDUE_URL` / `PUBLIC_FONTDUE_URL` / `VITE_FONTDUE_URL` from the environment.
+- **headers** — the explicit option merged over the ambient [admin preview](#admin-preview) context (`runWithPreview`), so the preview token is forwarded automatically.
 - **cacheTags** — when present, the fetch opts into Next's data cache (`force-cache` + tags) so `/api/revalidate` can purge it; absent/empty leaves it uncached. The Next hints are inert in other runtimes, where HTML is cached at the response/CDN layer instead.
 
 **Upgrading a hand-rolled fetch.** If you already have something like this:
@@ -525,7 +527,7 @@ export const fetchGraphql = createFontdueFetch();
 
 You get URL resolution, error handling, `FontdueNotFoundError`, and automatic preview-token forwarding for free.
 
-> **Next.js:** the same `createFontdueFetch` — pass it the endpoint's `cacheTags` so it ties into Next's data cache and the `/api/revalidate` deploy hook. See [Your own GraphQL fetches](#your-own-graphql-fetches) under the Next adapter.
+> **Next.js:** the same `createFontdueFetch` — mounting `<FontdueProvider>` ties it into Next's data cache, the `/api/revalidate` deploy hook, and admin preview, with no per-render setup call. See [Your own GraphQL fetches](#your-own-graphql-fetches) under the Next adapter.
 
 ## Admin preview
 
@@ -580,7 +582,7 @@ const preload = await loadTypeTesterQuery(vars, { headers });
 
 ### Next.js
 
-Next uses [draft mode](https://nextjs.org/docs/app/building-your-application/configuring/draft-mode) rather than ambient context. The route layers `draftMode()` on top of `handlePreviewRequest`:
+Next uses [draft mode](https://nextjs.org/docs/app/building-your-application/configuring/draft-mode) rather than ambient context. The preview route layers `draftMode()` on top of `handlePreviewRequest`:
 
 ```ts
 // app/api/preview/route.ts
@@ -600,36 +602,9 @@ export async function DELETE(request: Request) {
 }
 ```
 
-Two things then forward the token on a Next render:
-
-- **`prepareFontdueRender`** — the call you already make at the top of every page folds the draft-mode token into the per-render config, so the embedded components (type testers, store) reveal hidden fonts server-side automatically. This is the Next counterpart to `runWithPreview`.
-- **Your own fetch** reads draft mode and hands the token to `createFontdueFetch`, dropping the cache tags so the render stays live:
-
-```ts
-import { draftMode, cookies } from "next/headers";
-import { createFontdueFetch } from "fontdue-js/server";
-import { currentFontdueEndpoint } from "fontdue-js/next";
-import { PREVIEW_TOKEN_COOKIE, previewAuthHeaders } from "fontdue-js/preview";
-
-export async function fetchGraphql<Q>(name: string, query: string, variables?: unknown) {
-  const endpoint = currentFontdueEndpoint();
-  // draftMode()/cookies() are request-scoped — guard build-time static
-  // generation, where they throw, as "not preview".
-  const isPreview = (await draftMode()).isEnabled;
-  const token = isPreview ? (await cookies()).get(PREVIEW_TOKEN_COOKIE)?.value : undefined;
-
-  const fetchFontdue = createFontdueFetch({
-    url: endpoint.origin,
-    headers: { ...endpoint.headers, ...previewAuthHeaders(token) },
-    // Public renders are tagged + cached; preview renders pass no tags so they
-    // stay live and reveal hidden fonts.
-    cacheTags: isPreview ? [] : endpoint.tags,
-  });
-  return fetchFontdue<Q>(name, query, variables);
-}
-```
+That's the only preview-specific code. Mounting `<FontdueProvider>` registers a resolver that reads draft mode and the token cookie per server fetch, so the whole render forwards the token — **your own fetches and the embedded components' server preloads** alike — and hidden fonts show up everywhere, served live. No per-render call is needed (see [Your own GraphQL fetches](#your-own-graphql-fetches)).
 
-The example repos wire this up end to end for each framework.
+This includes the Fontdue React components. Rendered in a Server Component (the App Router default), `<TypeTester>`, `<CharacterViewer>` and friends preload their data on the server through that same resolver — even though you never call a `load*Query` helper yourself — so they reveal *their* hidden fonts too. The only embeds that don't depend on it are ones that fetch in the browser: a Fontdue component under a `"use client"` boundary, or the `<fontdue-*>` web components. Those reveal hidden fonts directly via the logged-in admin's session, so they need nothing either way. The example repos wire this up end to end for each framework.
 
 ## UI config
 

package/dist/__tests__/createFontdueFetch.test.js

@@ -219,4 +219,37 @@ describe('createFontdueFetch', () => {
       expect(init.next).toBeUndefined();
     });
   });
+  describe('fontdue-preview header', () => {
+    it('sends "false" by default so a public/session-only request never reveals hidden fonts', async () => {
+      const fetchMock = mockFetch(() => ({
+        status: 200,
+        json: async () => ({
+          data: {}
+        })
+      }));
+      const fetchGraphql = createFontdueFetch({
+        url: 'https://acme.fontdue.com'
+      });
+      await fetchGraphql('Q', 'query Q { __typename }');
+      const init = fetchMock.mock.calls[0][1];
+      expect(init.headers['fontdue-preview']).toBe('false');
+    });
+    it('sends "true" when bound with a preview Bearer token (reveal hidden fonts)', async () => {
+      const fetchMock = mockFetch(() => ({
+        status: 200,
+        json: async () => ({
+          data: {}
+        })
+      }));
+      const fetchGraphql = createFontdueFetch({
+        url: 'https://acme.fontdue.com',
+        headers: {
+          authorization: 'Bearer admin-tok'
+        }
+      });
+      await fetchGraphql('Q', 'query Q { __typename }');
+      const init = fetchMock.mock.calls[0][1];
+      expect(init.headers['fontdue-preview']).toBe('true');
+    });
+  });
 });

package/dist/__tests__/networkFetch.test.js

@@ -42,10 +42,11 @@ describe('createNetworkFetch (server)', () => {
     vi.stubGlobal('fetch', fetchMock);
 
     // React.cache doesn't memoize outside a React render, so the store is
-    // mocked rather than set through setFontdueServerConfig.
+    // mocked rather than set through setFontdueServerConfig. The network layer
+    // reads it through resolveFontdueServerConfig (awaited per fetch).
     vi.doMock('../relay/serverConfig', async importActual => ({
       ...(await importActual()),
-      getFontdueServerConfig: () => ({
+      resolveFontdueServerConfig: async () => ({
         url: 'http://app:4000',
         headers: {
           'x-forwarded-host': 'acme.fontdue.com'
@@ -85,4 +86,82 @@ describe('createNetworkFetch (server)', () => {
     const [, options] = fetchMock.mock.calls[0];
     expect(options.headers.authorization).toBe('Bearer preview-tok');
   });
+});
+function headersOf(fetchMock) {
+  return fetchMock.mock.calls[0][1].headers;
+}
+describe('createNetworkFetch (fontdue-preview header)', () => {
+  it('sends fontdue-preview: false on a public server fetch (no token)', async () => {
+    vi.stubEnv('FONTDUE_URL', 'https://acme.fontdue.com');
+    const fetchMock = vi.fn(async () => ({
+      json: async () => ({
+        data: {}
+      })
+    }));
+    vi.stubGlobal('fetch', fetchMock);
+    const {
+      createNetworkFetch
+    } = await import("../relay/environment.js");
+    await createNetworkFetch()(request, {});
+    expect(headersOf(fetchMock)['fontdue-preview']).toBe('false');
+  });
+  it('sends fontdue-preview: true when a preview Bearer token is forwarded (server)', async () => {
+    vi.stubEnv('FONTDUE_URL', 'https://acme.fontdue.com');
+    const fetchMock = vi.fn(async () => ({
+      json: async () => ({
+        data: {}
+      })
+    }));
+    vi.stubGlobal('fetch', fetchMock);
+    const {
+      createNetworkFetch
+    } = await import("../relay/environment.js");
+    await createNetworkFetch({
+      headers: {
+        authorization: 'Bearer tok'
+      }
+    })(request, {});
+    expect(headersOf(fetchMock)['fontdue-preview']).toBe('true');
+  });
+  it('on the client, sends true only when the preview marker cookie is set', async () => {
+    // typeof window must be defined at module load for IS_SERVER to be false.
+    vi.stubGlobal('window', {
+      addEventListener: () => {}
+    });
+    vi.stubGlobal('document', {
+      cookie: 'fontdue_preview=1'
+    });
+    vi.stubEnv('NEXT_PUBLIC_FONTDUE_URL', 'https://acme.fontdue.com');
+    const fetchMock = vi.fn(async () => ({
+      json: async () => ({
+        data: {}
+      })
+    }));
+    vi.stubGlobal('fetch', fetchMock);
+    const {
+      createNetworkFetch
+    } = await import("../relay/environment.js");
+    await createNetworkFetch()(request, {});
+    expect(headersOf(fetchMock)['fontdue-preview']).toBe('true');
+  });
+  it('on the client, sends false when the marker cookie is absent (logged-in admin browsing normally)', async () => {
+    vi.stubGlobal('window', {
+      addEventListener: () => {}
+    });
+    vi.stubGlobal('document', {
+      cookie: 'other=1'
+    });
+    vi.stubEnv('NEXT_PUBLIC_FONTDUE_URL', 'https://acme.fontdue.com');
+    const fetchMock = vi.fn(async () => ({
+      json: async () => ({
+        data: {}
+      })
+    }));
+    vi.stubGlobal('fetch', fetchMock);
+    const {
+      createNetworkFetch
+    } = await import("../relay/environment.js");
+    await createNetworkFetch()(request, {});
+    expect(headersOf(fetchMock)['fontdue-preview']).toBe('false');
+  });
 });