fontdue-js 3.0.0-alpha11 → 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

@@ -1,3 +1,17 @@
+## 3.0.0
+
+In alpha on the `alpha` dist-tag — install with `npm install fontdue-js@alpha`.
+
+- **Framework-agnostic.** fontdue-js now works in any React SSR or client-only environment — Astro, React Router 7, TanStack Start, Vike, Remix, and the existing Next.js App Router — not just Next.js. Each supported framework has a worked example repo (see the README "Examples"). The package is now ESM-only and ships an `exports` map, so TypeScript consumers need `moduleResolution` set to `bundler`, `node16`, or `nodenext`.
+- **Admin preview for every framework.** A preview toolbar — rendered by `<FontdueProvider>` and shown only to logged-in admins — reveals hidden (unpublished) fonts site-wide. New entry points implement a portable contract:
+  - `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.
+
+  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).
+
 ## 2.28.0
 
 - Checkout now captures the buyer's **analytics consent and ad attribution** on the order. When the cart or store-modal checkout opens, fontdue-js sends the consent-banner state, anonymous ID, Meta browser IDs (the `_fbp`/`_fbc` cookies), and the page URL to the server, where they're stored on the order. This lets Fontdue emit a server-side *purchase* conversion event (Facebook Conversions API, Google Ads) when the order completes — completion happens in a Stripe webhook, outside the browser — while respecting the buyer's cookie-consent choice: if consent was declined, no identifiers are sent and nothing is forwarded to ad platforms. The call is fire-and-forget and never affects checkout.

package/README.md

@@ -413,31 +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
 
-`currentFontdueEndpoint()` (from `fontdue-js/next`) describes the endpoint your own server-side [GraphQL](https://docs.fontdue.com/graphql-api) fetches should use — the base origin, required headers, and the cache tags that tie them into `/api/revalidate`:
+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
-import { currentFontdueEndpoint } from "fontdue-js/next";
+// src/lib/graphql.ts
+import { createFontdueFetch } from "fontdue-js/server";
 
-export async function fetchGraphql(query: string, variables?: unknown) {
-  const endpoint = currentFontdueEndpoint();
-  const response = await fetch(`${endpoint.origin}/graphql`, {
-    method: "POST",
-    body: JSON.stringify({ query, variables }),
-    headers: { "content-type": "application/json", ...endpoint.headers },
-    // Cache explicitly (Next 15 doesn't cache fetch by default), tagged so
-    // the deploy hook purges this too.
-    cache: "force-cache",
-    next: { tags: endpoint.tags },
-  });
-  return (await response.json()).data;
+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");
+  // …
 }
 ```
 
-The shape is exported as `type FontdueEndpoint`.
+`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
 
@@ -469,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. Your app's own GraphQL fetches should pass `cache: "force-cache"` and `next: { tags: endpoint.tags }` explicitly — 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.
 
@@ -479,6 +480,132 @@ What you get for it: server components now render the embeds' full HTML on the s
 
 If you're starting fresh instead of migrating, fork the example repo — it ships in this shape already.
 
+## Server-side GraphQL fetches
+
+Beyond the preload helpers, you'll often run your own [GraphQL](https://docs.fontdue.com/graphql-api) queries server-side — page chrome, metadata, custom sections. `fontdue-js/server` exports a ready-made fetcher so you don't hand-roll the transport:
+
+```ts
+import { createFontdueFetch } from "fontdue-js/server";
+
+// One fetcher for the whole app. Resolves the Fontdue URL from the environment
+// (FONTDUE_URL / PUBLIC_FONTDUE_URL / VITE_FONTDUE_URL).
+export const fetchGraphql = createFontdueFetch();
+
+// In a loader / frontmatter / server component:
+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:
+
+- **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:
+
+```ts
+// Before — hand-rolled.
+async function fetchGraphql(name, query, variables) {
+  const res = await fetch(`${import.meta.env.PUBLIC_FONTDUE_URL}/graphql`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ query, variables }),
+  });
+  const json = await res.json();
+  if (json.errors) throw new Error(json.errors[0].message);
+  return json.data;
+}
+```
+
+replace it with:
+
+```ts
+// After.
+import { createFontdueFetch } from "fontdue-js/server";
+export const fetchGraphql = createFontdueFetch();
+```
+
+You get URL resolution, error handling, `FontdueNotFoundError`, and automatic preview-token forwarding for free.
+
+> **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
+
+Logged-in Fontdue admins get a preview toolbar — rendered automatically by `<FontdueProvider>`, hidden for everyone else — that reveals **hidden (unpublished) fonts** across the whole site. The toolbar brokers a short-lived admin token and POSTs it to a small preview route on your own origin; from then on, server renders forward the token so GraphQL returns the unpublished content. The public never has the cookie, so their renders stay sessionless and cacheable.
+
+Two entry points cover this: `fontdue-js/preview` (the portable cookie contract) and `fontdue-js/preview/server` (the ambient wiring).
+
+**1. Add the preview route** at `/api/preview` — the toolbar POSTs to enter preview and DELETEs to exit. `handlePreviewRequest` is a Web-standard `Request → Response` handler, so it drops into any Fetch-API framework:
+
+```ts
+// Astro — src/pages/api/preview.ts
+import { handlePreviewRequest } from "fontdue-js/preview";
+export const ALL = ({ request }) => handlePreviewRequest(request);
+export const prerender = false;
+```
+
+```ts
+// React Router 7 — app/routes/api.preview.ts
+import { handlePreviewRequest } from "fontdue-js/preview";
+export const action = ({ request }) => handlePreviewRequest(request);
+```
+
+The path is configurable via `config.preview.endpoint` on `<FontdueProvider>` (default `/api/preview`) — mount the route to match.
+
+**2. Forward the token on server renders.** The recommended way is ambient: wrap each request in `runWithPreview` (from `fontdue-js/preview/server`) in your framework's middleware. While it's active, every `createFontdueFetch` call and every `load*Query()` preload forwards the token automatically — no per-call plumbing — and preview responses are forced out of any shared/CDN cache so an admin's render is never served to the public.
+
+```ts
+// Astro — src/middleware.ts
+import { runWithPreview } from "fontdue-js/preview/server";
+export const onRequest = (ctx, next) => runWithPreview(ctx.request, next);
+```
+
+```ts
+// React Router 7 — root route (with future.v8_middleware enabled)
+import { runWithPreview } from "fontdue-js/preview/server";
+export const middleware = [({ request }, next) => runWithPreview(request, next)];
+```
+
+`runWithPreview` uses `AsyncLocalStorage`, so it works wherever middleware shares a runtime with the render — Node (the default SSR target on Netlify/Vercel), Deno, Bun.
+
+**Explicit alternative.** Where the ambient context can't propagate (e.g. middleware running in a separate runtime from the render, such as Astro's `edgeMiddleware: true`), read the token yourself and pass it as the `{ headers }` option, which always overrides the ambient context:
+
+```ts
+import { readPreviewToken, previewAuthHeaders } from "fontdue-js/preview";
+
+const headers = previewAuthHeaders(readPreviewToken(request.headers.get("cookie")));
+const fetchGraphql = createFontdueFetch({ headers });
+const preload = await loadTypeTesterQuery(vars, { headers });
+```
+
+`previewAuthHeaders` returns `{}` when there's no token, so it's always safe to pass.
+
+### Next.js
+
+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
+import { draftMode } from "next/headers";
+import { handlePreviewRequest } from "fontdue-js/preview";
+
+export async function POST(request: Request) {
+  const response = await handlePreviewRequest(request);
+  if (response.ok) (await draftMode()).enable();
+  return response;
+}
+
+export async function DELETE(request: Request) {
+  const response = await handlePreviewRequest(request);
+  (await draftMode()).disable();
+  return response;
+}
+```
+
+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)).
+
+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
 
 Most components accept a `config` object that controls UI behavior — type-tester options (`selectable`, `priceBar`, size ranges, OpenType-feature UI…), store-modal layout, form styling, analytics tracking, and more. See the [full config reference](https://docs.fontdue.com/fontduejs#b3dec49aa08240bba2b4c71a67c08333).

package/dist/__tests__/createFontdueFetch.test.js

@@ -1,9 +1,19 @@
-import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { createFontdueFetch, FontdueNotFoundError } from '../server/index.js';
+import { registerAmbientConfigResolver } from '../relay/serverConfig.js';
 beforeEach(() => {
   vi.unstubAllEnvs();
   vi.unstubAllGlobals();
 });
+
+// Several tests inject a per-render config through the ambient resolver seam
+// (the same seam runWithPreview and the Next slot use). Always clear it.
+afterEach(() => {
+  registerAmbientConfigResolver(() => undefined);
+});
+function withConfig(config) {
+  registerAmbientConfigResolver(() => config);
+}
 function mockFetch(impl) {
   const fetchMock = vi.fn(async (url, init) => impl(url, init));
   vi.stubGlobal('fetch', fetchMock);
@@ -98,7 +108,148 @@ describe('createFontdueFetch', () => {
     await fetchGraphql('Q', 'query Q { __typename }');
     expect(fetchMock.mock.calls[0][0]).toBe('https://env.fontdue.com/graphql?query=Q');
   });
-  it('throws a helpful error when no URL is configured', () => {
-    expect(() => createFontdueFetch()).toThrow(/no Fontdue URL configured/);
+  it('throws a helpful error when no URL is configured (resolved per call)', async () => {
+    mockFetch(() => ({
+      status: 200,
+      json: async () => ({
+        data: {}
+      })
+    }));
+    const fetchGraphql = createFontdueFetch();
+    await expect(fetchGraphql('Q', 'query Q { __typename }')).rejects.toThrow(/no Fontdue URL configured/);
+  });
+  describe('Next data cache tags', () => {
+    it('opts into force-cache + tags when cacheTags are given', async () => {
+      var _init$next;
+      const fetchMock = mockFetch(() => ({
+        status: 200,
+        json: async () => ({
+          data: {}
+        })
+      }));
+      const fetchGraphql = createFontdueFetch({
+        url: 'https://acme.fontdue.com',
+        cacheTags: ['graphql:acme.fontdue.com']
+      });
+      await fetchGraphql('Q', 'query Q { __typename }');
+      const init = fetchMock.mock.calls[0][1];
+      expect(init.cache).toBe('force-cache');
+      // The global `graphql` tag is prepended automatically.
+      expect((_init$next = init.next) === null || _init$next === void 0 ? void 0 : _init$next.tags).toEqual(['graphql', 'graphql:acme.fontdue.com']);
+    });
+    it('leaves the fetch uncached when no cacheTags are given', 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.cache).toBeUndefined();
+      expect(init.next).toBeUndefined();
+    });
+    it('treats an empty cacheTags list as uncached (preview renders)', async () => {
+      const fetchMock = mockFetch(() => ({
+        status: 200,
+        json: async () => ({
+          data: {}
+        })
+      }));
+      const fetchGraphql = createFontdueFetch({
+        url: 'https://acme.fontdue.com',
+        cacheTags: []
+      });
+      await fetchGraphql('Q', 'query Q { __typename }');
+      const init = fetchMock.mock.calls[0][1];
+      expect(init.cache).toBeUndefined();
+      expect(init.next).toBeUndefined();
+    });
+  });
+  describe('per-render config (the Next slot / ambient resolver)', () => {
+    it('resolves url, headers and cacheTags from the config', async () => {
+      var _init$next2;
+      const fetchMock = mockFetch(() => ({
+        status: 200,
+        json: async () => ({
+          data: {}
+        })
+      }));
+      withConfig({
+        url: 'https://tenant.fontdue.com',
+        headers: {
+          'x-forwarded-host': 'tenant.fontdue.com'
+        },
+        cacheTags: ['graphql:tenant.fontdue.com']
+      });
+
+      // No options: a module-level fetcher picks up the current render's config.
+      const fetchGraphql = createFontdueFetch();
+      await fetchGraphql('Q', 'query Q { __typename }');
+      const [url, init] = fetchMock.mock.calls[0];
+      expect(url).toBe('https://tenant.fontdue.com/graphql?query=Q');
+      expect(init.headers['x-forwarded-host']).toBe('tenant.fontdue.com');
+      expect(init.cache).toBe('force-cache');
+      expect((_init$next2 = init.next) === null || _init$next2 === void 0 ? void 0 : _init$next2.tags).toEqual(['graphql', 'graphql:tenant.fontdue.com']);
+    });
+    it('explicit options override the config (url and cacheTags)', async () => {
+      const fetchMock = mockFetch(() => ({
+        status: 200,
+        json: async () => ({
+          data: {}
+        })
+      }));
+      withConfig({
+        url: 'https://tenant.fontdue.com',
+        cacheTags: ['graphql:tenant.fontdue.com']
+      });
+
+      // Explicit url + empty cacheTags (e.g. a preview render) win.
+      const fetchGraphql = createFontdueFetch({
+        url: 'https://explicit.fontdue.com',
+        cacheTags: []
+      });
+      await fetchGraphql('Q', 'query Q { __typename }');
+      const [url, init] = fetchMock.mock.calls[0];
+      expect(url).toBe('https://explicit.fontdue.com/graphql?query=Q');
+      expect(init.cache).toBeUndefined();
+      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');
+  });
 });