fontdue-js 3.0.0-alpha10 → 3.0.0-alpha12

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.
+
+  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".
+- **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

@@ -417,27 +417,26 @@ fontdue-js's own server-side fetches opt into Next's data cache (and the `graphq
 
 ### 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, 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:
 
 ```ts
+import { createFontdueFetch } from "fontdue-js/server";
 import { currentFontdueEndpoint } from "fontdue-js/next";
 
-export async function fetchGraphql(query: string, variables?: unknown) {
+export async function fetchGraphql<Q>(name: string, 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 },
+  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 (await response.json()).data;
+  return fetchFontdue<Q>(name, query, variables);
 }
 ```
 
-The shape is exported as `type FontdueEndpoint`.
+`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).
 
 ## Migrating a Next.js site from v2
 
@@ -469,7 +468,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` and pass it `cacheTags: endpoint.tags` so caching and `/api/revalidate` are handled 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 +478,159 @@ 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 from the explicit option, then the per-render config (set by `runWithPreview` or the Next adapter), then the environment:
+
+- **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.
+- **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` — 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.
+
+## 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 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;
+}
+```
+
+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);
+}
+```
+
+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/__generated__/FontdueAdminToolbarQuery.graphql.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @generated SignedSource<<c46bd30612c05d6cd1c334c403aafb35>>
+ * @lightSyntaxTransform
+ * @nogrep
+ */
+import { ConcreteRequest } from 'relay-runtime';
+export type FontdueAdminToolbarQuery$variables = Record<PropertyKey, never>;
+export type FontdueAdminToolbarQuery$data = {
+    readonly viewer: {
+        readonly adminUser: {
+            readonly name: string | null;
+        } | null;
+    };
+};
+export type FontdueAdminToolbarQuery = {
+    response: FontdueAdminToolbarQuery$data;
+    variables: FontdueAdminToolbarQuery$variables;
+};
+declare const node: ConcreteRequest;
+export default node;

package/dist/__generated__/FontdueAdminToolbarQuery.graphql.js

@@ -0,0 +1,80 @@
+/**
+ * @generated SignedSource<<c46bd30612c05d6cd1c334c403aafb35>>
+ * @lightSyntaxTransform
+ * @nogrep
+ */
+
+/* tslint:disable */
+/* eslint-disable */
+// @ts-nocheck
+
+const node = function () {
+  var v0 = {
+    "alias": null,
+    "args": null,
+    "concreteType": "User",
+    "kind": "LinkedField",
+    "name": "adminUser",
+    "plural": false,
+    "selections": [{
+      "alias": null,
+      "args": null,
+      "kind": "ScalarField",
+      "name": "name",
+      "storageKey": null
+    }],
+    "storageKey": null
+  };
+  return {
+    "fragment": {
+      "argumentDefinitions": [],
+      "kind": "Fragment",
+      "metadata": null,
+      "name": "FontdueAdminToolbarQuery",
+      "selections": [{
+        "alias": null,
+        "args": null,
+        "concreteType": "Viewer",
+        "kind": "LinkedField",
+        "name": "viewer",
+        "plural": false,
+        "selections": [v0 /*: any*/],
+        "storageKey": null
+      }],
+      "type": "RootQueryType",
+      "abstractKey": null
+    },
+    "kind": "Request",
+    "operation": {
+      "argumentDefinitions": [],
+      "kind": "Operation",
+      "name": "FontdueAdminToolbarQuery",
+      "selections": [{
+        "alias": null,
+        "args": null,
+        "concreteType": "Viewer",
+        "kind": "LinkedField",
+        "name": "viewer",
+        "plural": false,
+        "selections": [v0 /*: any*/, {
+          "alias": null,
+          "args": null,
+          "kind": "ScalarField",
+          "name": "id",
+          "storageKey": null
+        }],
+        "storageKey": null
+      }]
+    },
+    "params": {
+      "cacheID": "a48946b192fea90930ffac67eff7b1b5",
+      "id": null,
+      "metadata": {},
+      "name": "FontdueAdminToolbarQuery",
+      "operationKind": "query",
+      "text": "query FontdueAdminToolbarQuery {\n  viewer {\n    adminUser {\n      name\n    }\n    id\n  }\n}\n"
+    }
+  };
+}();
+node.hash = "8660b45f086137d249eee82459ad648d";
+export default node;

package/dist/__tests__/createFontdueFetch.test.js

@@ -0,0 +1,222 @@
+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);
+  return fetchMock;
+}
+describe('createFontdueFetch', () => {
+  it('posts the query to the configured URL and unwraps data', async () => {
+    const fetchMock = mockFetch(() => ({
+      status: 200,
+      json: async () => ({
+        data: {
+          viewer: {
+            id: '1'
+          }
+        }
+      })
+    }));
+    const fetchGraphql = createFontdueFetch({
+      url: 'https://acme.fontdue.com'
+    });
+    const data = await fetchGraphql('Index', 'query Index { viewer { id } }', {
+      a: 1
+    });
+    expect(data).toEqual({
+      viewer: {
+        id: '1'
+      }
+    });
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe('https://acme.fontdue.com/graphql?query=Index');
+    expect(init.method).toBe('POST');
+    expect(JSON.parse(init.body)).toEqual({
+      query: 'query Index { viewer { id } }',
+      variables: {
+        a: 1
+      }
+    });
+  });
+  it('forwards bound headers (the preview Bearer token) on every call', async () => {
+    const fetchMock = mockFetch(() => ({
+      status: 200,
+      json: async () => ({
+        data: {}
+      })
+    }));
+    const fetchGraphql = createFontdueFetch({
+      url: 'https://acme.fontdue.com',
+      headers: {
+        authorization: 'Bearer admin-tok'
+      }
+    });
+    await fetchGraphql('A', 'query A { __typename }');
+    await fetchGraphql('B', 'query B { __typename }');
+    for (const call of fetchMock.mock.calls) {
+      const init = call[1];
+      expect(init.headers.authorization).toBe('Bearer admin-tok');
+    }
+  });
+  it('throws FontdueNotFoundError on a 404 (host did not resolve)', async () => {
+    mockFetch(() => ({
+      status: 404,
+      json: async () => ({})
+    }));
+    const fetchGraphql = createFontdueFetch({
+      url: 'https://acme.fontdue.com'
+    });
+    await expect(fetchGraphql('X', 'query X { __typename }')).rejects.toBeInstanceOf(FontdueNotFoundError);
+  });
+  it('throws on GraphQL errors in a 200 response', async () => {
+    mockFetch(() => ({
+      status: 200,
+      json: async () => ({
+        errors: [{
+          message: 'boom'
+        }]
+      })
+    }));
+    const fetchGraphql = createFontdueFetch({
+      url: 'https://acme.fontdue.com'
+    });
+    await expect(fetchGraphql('X', 'query X { __typename }')).rejects.toThrow('boom');
+  });
+  it('resolves the URL from the environment when none is passed', async () => {
+    vi.stubEnv('FONTDUE_URL', 'https://env.fontdue.com');
+    const fetchMock = mockFetch(() => ({
+      status: 200,
+      json: async () => ({
+        data: {}
+      })
+    }));
+    const fetchGraphql = 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 (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();
+    });
+  });
+});

package/dist/__tests__/imageLoader.test.js

@@ -0,0 +1,62 @@
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import fontdueImageLoader from '../next/image-loader.js';
+
+// The loader reads NEXT_PUBLIC_FONTDUE_IMAGE_HOST / _ORIGINS at call time, so
+// each test stubs them and we clear stubs afterwards.
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+function load(src) {
+  let origins = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : '';
+  let host = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 'img.fontdue.xyz';
+  vi.stubEnv('NEXT_PUBLIC_FONTDUE_IMAGE_HOST', host);
+  vi.stubEnv('NEXT_PUBLIC_FONTDUE_IMAGE_ORIGINS', origins);
+  return fontdueImageLoader({
+    src,
+    width: 800,
+    quality: 75
+  });
+}
+const transformed = src => `https://img.fontdue.xyz/cdn-cgi/image/width=800,quality=75,format=auto/${src}`;
+describe('fontdueImageLoader', () => {
+  it('transforms any absolute src when no allowlist is set', () => {
+    const src = 'https://anywhere.example/a.jpg';
+    expect(load(src)).toBe(transformed(src));
+  });
+  it('serves relative srcs as-is', () => {
+    expect(load('/logo.svg', 'cdn.fontdue.xyz')).toBe('/logo.svg');
+  });
+  it('serves srcs as-is when no transform host is configured', () => {
+    const src = 'https://cdn.fontdue.xyz/a.jpg';
+    expect(load(src, 'cdn.fontdue.xyz', '')).toBe(src);
+  });
+  describe('origins allowlist', () => {
+    it('transforms an exact hostname match and skips a non-match', () => {
+      const ok = 'https://cdn.fontdue.xyz/a.jpg';
+      const no = 'https://other.example/a.jpg';
+      expect(load(ok, 'cdn.fontdue.xyz')).toBe(transformed(ok));
+      expect(load(no, 'cdn.fontdue.xyz')).toBe(no);
+    });
+    it('matches a "*." wildcard against any subdomain', () => {
+      const cdn = 'https://cdn.fontdue.xyz/a.jpg';
+      const assets = 'https://assets.fontdue.xyz/a.jpg';
+      expect(load(cdn, '*.fontdue.xyz')).toBe(transformed(cdn));
+      expect(load(assets, '*.fontdue.xyz')).toBe(transformed(assets));
+    });
+    it('does not let a wildcard match the apex or a lookalike domain', () => {
+      const apex = 'https://fontdue.xyz/a.jpg';
+      const lookalike = 'https://evilfontdue.xyz/a.jpg';
+      expect(load(apex, '*.fontdue.xyz')).toBe(apex);
+      expect(load(lookalike, '*.fontdue.xyz')).toBe(lookalike);
+    });
+    it('ignores an optional scheme on allowlist entries', () => {
+      const src = 'https://cdn.fontdue.xyz/a.jpg';
+      expect(load(src, 'https://cdn.fontdue.xyz')).toBe(transformed(src));
+      expect(load(src, 'https://*.fontdue.xyz')).toBe(transformed(src));
+    });
+    it('supports a comma-separated list', () => {
+      const src = 'https://assets.fontdue.xyz/a.jpg';
+      expect(load(src, 'cdn.fontdue.xyz, assets.fontdue.xyz')).toBe(transformed(src));
+    });
+  });
+});

package/dist/__tests__/networkFetch.test.js

@@ -63,4 +63,26 @@ describe('createNetworkFetch (server)', () => {
     expect(options.headers['x-forwarded-host']).toBe('acme.fontdue.com');
     expect(options.next.tags).toContain('graphql:acme.fontdue.com');
   });
+  it('forwards per-call options.headers (e.g. a preview Bearer token)', async () => {
+    vi.stubEnv('FONTDUE_URL', 'https://acme.fontdue.com');
+    const fetchMock = vi.fn(async () => ({
+      json: async () => ({
+        data: {}
+      })
+    }));
+    vi.stubGlobal('fetch', fetchMock);
+
+    // This is the non-RSC path: the render-scoped serverConfig store is a
+    // no-op outside an RSC render, so apps forward the token per call instead.
+    const {
+      createNetworkFetch
+    } = await import("../relay/environment.js");
+    await createNetworkFetch({
+      headers: {
+        authorization: 'Bearer preview-tok'
+      }
+    })(request, {});
+    const [, options] = fetchMock.mock.calls[0];
+    expect(options.headers.authorization).toBe('Bearer preview-tok');
+  });
 });