fontdue-js 3.0.0-alpha11 → 3.0.0-alpha13

package/dist/relay/serverConfig.js

@@ -25,33 +25,70 @@
 // and the environment variables remain the configuration source.
 
 import * as React from 'react';
-const getSlot = typeof React.cache === 'function' ? React.cache(() => ({
-  current: undefined
-})) : () => ({
-  current: undefined
-});
+
+// This module owns two pieces of cross-cutting state — the render-scoped slot
+// and the ambient resolver — and both must be shared by every server-side
+// fetch in a render. The catch: a Next.js server build can bundle this same
+// file into more than one server chunk (e.g. the app/provider chunk and a
+// separate per-embed chunk), and those copies do NOT share module-level state.
+// That split is silent until it bites: the ambient resolver is registered once
+// (when <FontdueProvider> mounts) but an embedded component's own preload runs
+// from the OTHER chunk's copy — so it never sees the resolver, fetches without
+// the preview token, and a hidden-font reveal fails (a <BuyButton> node(id)
+// @required(THROW) preload then crashes the server render — FD-712).
+//
+// Anchor both on globalThis so every duplicate instance shares one slot factory
+// and one resolver. Same reasoning as the global Relay-environment singleton —
+// see components/FontdueContextProvider.
+
+const STORE_KEY = '__fontdueServerConfigStore__';
+function store() {
+  const g = globalThis;
+  let s = g[STORE_KEY];
+  if (!s) {
+    // React.cache() scopes the slot to one server render pass (and so isolates
+    // concurrent requests from each other). Creating it once and sharing the
+    // single instance keeps that per-render isolation while defeating the
+    // chunk duplication. Outside an RSC render React.cache is unavailable, so
+    // the slot degrades to a throwaway object: writes no-op and the
+    // environment variables remain the configuration source.
+    s = {
+      getSlot: typeof React.cache === 'function' ? React.cache(() => ({
+        current: undefined
+      })) : () => ({
+        current: undefined
+      }),
+      ambientResolver: undefined
+    };
+    g[STORE_KEY] = s;
+  }
+  return s;
+}
 export function setFontdueServerConfig(config) {
-  getSlot().current = config;
+  store().getSlot().current = config;
 }
 
 // Ambient config resolver — the seam that lets a request-scoped store outside
-// RSC (e.g. fontdue-js/preview/server's AsyncLocalStorage) feed config into
-// server fetches without this browser-safe module importing a Node builtin.
-// The server-only module registers a resolver on import; if nothing registers,
-// resolution is unchanged. The RSC render slot still wins, so Next is
-// unaffected (it never registers a resolver).
-
-let ambientResolver;
+// the RSC slot feed config into server fetches without this browser-safe module
+// importing a Node builtin. Two registrants today:
+//   - fontdue-js/preview/server (Astro/RR7): a synchronous resolver reading an
+//     AsyncLocalStorage store set by runWithPreview.
+//   - fontdue-js/next (single-tenant): an asynchronous resolver that reads the
+//     env URL plus Next's draftMode()/cookies() per fetch — so a single-tenant
+//     foundry never calls a per-render setup function.
+// A server-only module registers a resolver on import; if nothing registers,
+// resolution is unchanged. The RSC slot still wins on merge, so multi-tenant
+// Next (which drives config through the slot via __prepareFontdueRender) is
+// unaffected.
 export function registerAmbientConfigResolver(resolver) {
-  ambientResolver = resolver;
+  store().ambientResolver = resolver;
 }
-export function getFontdueServerConfig() {
-  var _ambientResolver;
-  const slot = getSlot().current;
-  const ambient = (_ambientResolver = ambientResolver) === null || _ambientResolver === void 0 ? void 0 : _ambientResolver();
+
+// Merge an ambient config under the RSC slot: the slot wins for scalar fields;
+// headers merge with the slot overriding.
+function mergeServerConfig(ambient, slot) {
   if (!ambient) return slot;
   if (!slot) return ambient;
-  // RSC slot wins for scalar fields; headers merge with the slot overriding.
   return {
     ...ambient,
     ...slot,
@@ -60,4 +97,29 @@ export function getFontdueServerConfig() {
       ...slot.headers
     }
   };
+}
+
+// Slot-only read of the render-scoped config. It deliberately does NOT run the
+// ambient resolver: the single-tenant Next resolver is async (it awaits
+// draftMode()/cookies()), so a synchronous read could never reflect it without
+// silently dropping the preview token. Anything that needs the resolved
+// url/headers — every server-side fetch — must use resolveFontdueServerConfig()
+// instead. This exists only to recover the multi-tenant `domain` the slot
+// carries (set by __prepareFontdueRender), which fontdueEndpoint() reads from a
+// synchronous path.
+export function getFontdueSlotConfig() {
+  return store().getSlot().current;
+}
+
+// Asynchronous read used by the server-side fetch paths (the Relay network
+// layer and createFontdueFetch). Awaits the ambient resolver so a resolver that
+// reads request-scoped async APIs (Next's draftMode()/cookies()) can feed
+// config into every server fetch with no per-render call, then merges it under
+// the slot.
+export async function resolveFontdueServerConfig() {
+  var _s$ambientResolver;
+  const s = store();
+  const slot = s.getSlot().current;
+  const ambient = await ((_s$ambientResolver = s.ambientResolver) === null || _s$ambientResolver === void 0 ? void 0 : _s$ambientResolver.call(s));
+  return mergeServerConfig(ambient, slot);
 }

package/dist/server/index.d.ts

@@ -5,16 +5,28 @@ export declare class FontdueNotFoundError extends Error {
 export interface CreateFontdueFetchOptions {
     /**
      * GraphQL base URL (without the trailing /graphql), e.g.
-     * https://acme.fontdue.com. Defaults to FONTDUE_URL / PUBLIC_FONTDUE_URL /
-     * VITE_FONTDUE_URL from the environment.
+     * https://acme.fontdue.com. Falls back to the per-render config
+     * (resolveFontdueServerConfig().url, set by the Next adapter for the current
+     * tenant) and then to FONTDUE_URL / PUBLIC_FONTDUE_URL / VITE_FONTDUE_URL
+     * from the environment.
      */
     url?: string;
     /**
-     * Extra headers sent with every fetch from this fetcher. Pass
+     * Extra headers sent with every fetch from this fetcher, merged over the
+     * ambient per-render headers (explicit winning). Pass
      * `previewAuthHeaders(token)` (from fontdue-js/preview) to reveal hidden
      * fonts while an admin is in preview.
      */
     headers?: Record<string, string>;
+    /**
+    * Next.js data-cache tags. When present — passed here or via the per-render
+    * config — the fetch is opted into Next's data cache so the revalidate
+    * handler can purge it. The global `graphql` tag is always included (and
+    * deduped), so pass the per-site tags alone or the full `endpoint.tags`.
+    * Omit (or pass `[]`) to leave the fetch uncached, which is what preview
+    * renders want. Inert outside Next.
+    */
+    cacheTags?: string[];
 }
 export type FontdueFetch = <Q, V = void>(queryName: string, query: string, variables?: V) => Promise<Q>;
 /**

package/dist/server/index.js

@@ -2,34 +2,50 @@
 //
 // Every framework example ships a near-identical `fetchGraphql` — resolve the
 // Fontdue URL, POST the query, unwrap `data`, throw on errors. This exports
-// that transport once so apps don't re-implement it, and so the preview
-// Authorization header is forwarded in one place instead of being wired into
-// each app's data layer.
+// that transport once so apps don't re-implement it, so the preview
+// Authorization header is forwarded in one place, and so the same fetcher
+// works in every server runtime. It is the sibling of the Relay network layer
+// (relay/environment.ts) that powers the embedded components: both read the
+// per-render config from resolveFontdueServerConfig() and apply it the same way.
 //
-// The per-request input — the admin preview token — can come from two places,
-// resolved per call:
+// All three per-request inputs — the base URL, the admin preview token, and
+// the Next cache tags — are resolved per call from two sources, so a single
+// module-level fetcher serves every render:
 //
-//   1. Ambient context: wrap requests in runWithPreview (fontdue-js/preview/
-//      server) and a single module-level fetcher forwards the token
-//      automatically — no binding, no per-call plumbing:
+//   1. Ambient context (preferred): whatever set the per-render config.
+//      - Astro / React Router etc.: runWithPreview (fontdue-js/preview/server)
+//        rides the token through AsyncLocalStorage.
+//      - Next: configureFontduePreview / __prepareFontdueRender
+//        (fontdue-js/next) write the site URL, cache tags, and preview token
+//        into the render-scoped slot.
+//      Either way:
 //
 //        const fetchGraphql = createFontdueFetch();           // once, at module scope
 //        const data = await fetchGraphql('Index', indexQuery, vars);
 //
-//   2. Explicit headers: bind a fetcher per request, for frameworks/runtimes
-//      where ambient context can't propagate (see runWithPreview's notes):
+//   2. Explicit options: bind a fetcher with a url/headers/cacheTags, for
+//      runtimes where the ambient context can't propagate (route handlers,
+//      Astro edgeMiddleware — see runWithPreview's notes):
 //
 //        const fetchGraphql = createFontdueFetch({
+//          url: endpoint.origin,
 //          headers: previewAuthHeaders(token),                // from fontdue-js/preview
+//          cacheTags: [`graphql:${endpoint.domain}`],
 //        });
 //
-// Explicit `headers` override the ambient context, so the two compose.
+// Explicit options override the ambient context (headers merge, explicit
+// winning), so the two compose.
 //
-// Caching is intentionally left to the host: these frameworks cache HTML at
-// the CDN/response-header layer, not on the fetch. (The Next adapter layers
-// its own force-cache + tag handling on top of the same idea.)
+// Caching: when the resolved config carries cacheTags (the Next adapter sets
+// them per render; supply them explicitly elsewhere) the fetch is opted into
+// Next's data cache (`force-cache` + tags) so /api/revalidate can purge it.
+// With no tags the fetch is left uncached, which is what preview renders and
+// the CDN-cached frameworks (Astro/RR7 cache HTML at the response layer) want.
+// The Next fetch hints are inert in other runtimes: Node's fetch accepts and
+// ignores the cache mode, and `next` is just an unknown init property.
 
-import { getFontdueServerConfig } from '../relay/serverConfig.js';
+import { resolveFontdueServerConfig } from '../relay/serverConfig.js';
+import { PREVIEW_HEADER } from '../preview/constants.js';
 function readEnv(name) {
   if (typeof process !== 'undefined' && process.env) {
     const v = process.env[name];
@@ -65,28 +81,58 @@ export class FontdueNotFoundError extends Error {
  */
 export function createFontdueFetch() {
   let options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
-  const base = options.url ?? resolveFontdueUrl();
-  if (!base) {
-    throw new Error('fontdue-js: no Fontdue URL configured. Set FONTDUE_URL / ' + 'PUBLIC_FONTDUE_URL / VITE_FONTDUE_URL, or pass { url } to ' + 'createFontdueFetch.');
-  }
   return async function fetchGraphql(queryName, query, variables) {
-    var _getFontdueServerConf, _json$errors, _json$errors$;
-    // Ambient preview headers (from a runWithPreview context), overridden by any
-    // explicit per-fetcher headers. Resolved per call so a module-level fetcher
-    // still picks up the current request's preview token.
-    const ambientHeaders = (_getFontdueServerConf = getFontdueServerConfig()) === null || _getFontdueServerConf === void 0 ? void 0 : _getFontdueServerConf.headers;
-    const response = await fetch(`${base}/graphql?query=${queryName}`, {
+    var _json$errors, _json$errors$;
+    // Per-render config (a runWithPreview AsyncLocalStorage store, the Next
+    // render-scoped slot, or the Next single-tenant ambient resolver). Awaited
+    // per call so a single module-level fetcher picks up the current request's
+    // tenant URL, preview token, and cache tags.
+    const config = await resolveFontdueServerConfig();
+
+    // URL: explicit option, then the per-render tenant URL, then the env.
+    const base = options.url ?? (config === null || config === void 0 ? void 0 : config.url) ?? resolveFontdueUrl();
+    if (!base) {
+      throw new Error('fontdue-js: no Fontdue URL configured. Set FONTDUE_URL / ' + 'PUBLIC_FONTDUE_URL / VITE_FONTDUE_URL, pass { url } to ' + 'createFontdueFetch, or set it on the per-render config.');
+    }
+
+    // Cache tags: explicit option wins, else the per-render config's. A
+    // non-empty list opts the fetch into Next's data cache (inert elsewhere);
+    // an empty/absent list leaves it uncached (preview + CDN-cached frameworks).
+    const cacheTags = options.cacheTags ?? (config === null || config === void 0 ? void 0 : config.cacheTags);
+
+    // Ambient headers (e.g. tenant + preview token), overridden by any explicit
+    // per-fetcher headers.
+    const headers = {
+      'content-type': 'application/json',
+      ...(config === null || config === void 0 ? void 0 : config.headers),
+      ...options.headers
+    };
+
+    // Declare preview intent explicitly: a forwarded admin token means this is a
+    // preview render → reveal hidden fonts; otherwise "false" so a public (or
+    // merely session-authenticated) request never gets the hidden-fonts view.
+    // Older clients omit the header and keep the legacy behavior. Mirrors the
+    // Relay network layer (relay/environment.ts) and FontageWeb.Schema.Context.
+    headers[PREVIEW_HEADER] = headers.authorization != null || headers.Authorization != null ? 'true' : 'false';
+
+    // `next` is a Next.js-only fetch extension, ignored by other runtimes.
+    const init = {
       method: 'POST',
       body: JSON.stringify({
         query,
         variables
       }),
-      headers: {
-        'content-type': 'application/json',
-        ...ambientHeaders,
-        ...options.headers
-      }
-    });
+      headers
+    };
+    if (Array.isArray(cacheTags) && cacheTags.length > 0) {
+      init.cache = 'force-cache';
+      // The global `graphql` tag is always present; dedupe so callers can pass
+      // the per-site tags alone or the full `endpoint.tags` (which include it).
+      init.next = {
+        tags: Array.from(new Set(['graphql', ...cacheTags]))
+      };
+    }
+    const response = await fetch(`${base}/graphql?query=${queryName}`, init);
     if (response.status === 404) throw new FontdueNotFoundError(queryName);
     if (response.status !== 200) {
       throw new Error(`Fontdue request failed: ${response.status}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fontdue-js",
-  "version": "3.0.0-alpha11",
+  "version": "3.0.0-alpha13",
   "type": "module",
   "scripts": {
     "build": "npm run relay && run-p build-js build-css build-ts",

package/types/next-headers.d.ts

@@ -0,0 +1,9 @@
+// Minimal declaration so src/next/tenant.ts type-checks without `next`
+// installed (it's the host app's dependency; this package only ever runs the
+// import inside a Next.js server).
+declare module 'next/headers' {
+  export function draftMode(): Promise<{ isEnabled: boolean }>;
+  export function cookies(): Promise<{
+    get(name: string): { value: string } | undefined;
+  }>;
+}

package/types/next-navigation.d.ts

@@ -3,4 +3,8 @@
 // import inside a Next.js server).
 declare module 'next/navigation' {
   export function notFound(): never;
+  // Re-throws Next's internal control-flow errors (dynamic-rendering bailout,
+  // notFound, redirect) and is a no-op for everything else. Used so the preview
+  // resolver doesn't swallow the bailout that forces a dynamic render.
+  export function unstable_rethrow(error: unknown): void;
 }

package/vitest.config.ts

@@ -7,6 +7,11 @@ export default defineConfig({
     __FONTDUE_JS_VERSION__: JSON.stringify('0.0.0-test'),
   },
   test: {
+    // Only the TypeScript sources are the tests of record. Without this, a
+    // prior `npm run build` leaves compiled copies in dist/__tests__ that
+    // vitest also picks up — running each suite twice and racing on
+    // module-level singletons (e.g. the ambient config resolver).
+    include: ['src/**/*.test.{ts,tsx}'],
     alias: {
       '__generated__': path.resolve(__dirname, 'src/__generated__'),
     },