fontdue-js 3.0.0-alpha8 → 3.0.0

package/dist/next/image-loader.js

@@ -5,8 +5,10 @@
 // NEXT_PUBLIC_FONTDUE_IMAGE_HOST is set; see config.ts.
 //
 // NEXT_PUBLIC_FONTDUE_IMAGE_ORIGINS (comma-separated hostnames) should
-// mirror the transformation host's allowed-origins list. Sources on other
-// hosts — e.g. the /logo endpoint a site serves from its own (possibly
+// mirror the transformation host's allowed-origins list. A leading "*."
+// wildcard matches any subdomain ("*.fontdue.xyz" → "cdn.fontdue.xyz", not
+// the apex or a lookalike); a scheme/port on an entry is ignored. Sources on
+// other hosts — e.g. the /logo endpoint a site serves from its own (possibly
 // customer-owned) domain, which can't be allowlisted — are served as-is
 // rather than as transform URLs Cloudflare would refuse (ERROR 9401).
 //
@@ -14,6 +16,23 @@
 // reads at build time, so it must stay dependency-free, and the variables
 // have to be present when `next build` runs (not just at serve time).
 
+// Reduce an allowlist entry to a bare hostname (or "*."-prefixed wildcard),
+// tolerating an optional scheme, path, or port so "https://*.fontdue.xyz"
+// behaves like "*.fontdue.xyz".
+function originHostname(entry) {
+  return entry.trim().replace(/^https?:\/\//i, '').split('/')[0].split(':')[0];
+}
+function matchesOrigin(hostname, entry) {
+  const origin = originHostname(entry);
+  if (!origin) return false;
+  if (origin.startsWith('*.')) {
+    // ".fontdue.xyz" — endsWith plus the strict length check requires at
+    // least one label before the dot, so the apex and lookalikes don't match.
+    const suffix = origin.slice(1);
+    return hostname.endsWith(suffix) && hostname.length > suffix.length;
+  }
+  return origin === hostname;
+}
 function transformable(src) {
   const origins = process.env.NEXT_PUBLIC_FONTDUE_IMAGE_ORIGINS;
   if (!origins) return true;
@@ -23,7 +42,7 @@ function transformable(src) {
   } catch {
     return false;
   }
-  return origins.split(',').some(origin => origin.trim() === hostname);
+  return origins.split(',').some(entry => matchesOrigin(hostname, entry));
 }
 export default function fontdueImageLoader(_ref) {
   let {

package/dist/next/index.d.ts

@@ -1,2 +1 @@
-export { isMultiTenant, isValidDomain, fontdueEndpoint, fallbackSiteUrl, fontdueServerConfig, configureFontdueRender, type FontdueEndpoint, } from './tenant.js';
-export { setFontdueServerConfig, getFontdueServerConfig, type FontdueServerConfig, } from '../relay/serverConfig.js';
+export { __prepareFontdueRender, type FontdueEndpoint } from './tenant.js';

package/dist/next/index.js

@@ -2,9 +2,17 @@
 // The config-time wrapper lives in 'fontdue-js/next/config' and the deploy
 // hook route handler in 'fontdue-js/next/revalidate'.
 
-export { isMultiTenant, isValidDomain, fontdueEndpoint, fallbackSiteUrl, fontdueServerConfig, configureFontdueRender } from './tenant.js';
-
-// The per-render config store consumed by fontdue-js's own server-side
-// fetches. configureFontdueRender covers the common case; these are exported
-// for apps that need to set or inspect the config directly.
-export { setFontdueServerConfig, getFontdueServerConfig } from '../relay/serverConfig.js';
+// Single-tenant apps need NO per-render setup and nothing from this entrypoint:
+// mounting <FontdueProvider> registers the ambient resolver that configures
+// every server fetch — your own (createFontdueFetch) and the embedded
+// components' preloads, including the admin preview token (see
+// ../components/FontdueProvider/index.server.tsx -> registerSingleTenantResolver).
+//
+// __prepareFontdueRender is the internal multi-tenant API (double-underscored)
+// used only by the Fontdue-hosted next-template — not part of the foundry
+// surface — and FontdueEndpoint is its return type. The remaining tenant/config
+// helpers (isMultiTenant, isValidDomain, endpointForDomain, fontdueServerConfig,
+// configureFontdueRender, setFontdueServerConfig) are deliberately not
+// re-exported here; the modules that need them import them directly from
+// './tenant.js' / '../relay/serverConfig.js'.
+export { __prepareFontdueRender } from './tenant.js';

package/dist/next/registerSingleTenantResolver.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/next/registerSingleTenantResolver.js

@@ -0,0 +1,35 @@
+// Registers the single-tenant ambient config resolver (env URL +
+// draftMode()/cookies() preview token, resolved per fetch) so a single-tenant
+// foundry that mounts <FontdueProvider> never has to call a per-render setup
+// function. The FontdueProvider react-server entrypoint imports this module as
+// a side effect — in the call-free model the app no longer imports
+// 'fontdue-js/next' itself, so the provider mount is the only thing guaranteed
+// to wire the resolver up.
+//
+// Why this lives apart from ./tenant.ts: it statically imports ONLY the
+// browser-safe registerAmbientConfigResolver. The Next request APIs
+// (next/headers, next/navigation) the resolver needs sit behind a lazy
+// `import('./tenant.js')` in the resolver body, which runs only when a server
+// fetch actually resolves config — i.e. only under Next. That keeps next/* off
+// the provider entrypoint's eager import graph, so mounting <FontdueProvider>
+// stays safe for any non-Next RSC consumer. (Today only Next resolves the
+// react-server export condition, but the decoupling makes that a structural
+// invariant rather than an incidental one.)
+import { registerAmbientConfigResolver } from '../relay/serverConfig.js';
+registerAmbientConfigResolver(async () => {
+  // Loaded lazily so next/headers + next/navigation never enter the
+  // provider's static graph; config is read per fetch from Next's request
+  // context (draftMode()/cookies()), which also covers soft navigations that
+  // re-render only the page segment.
+  const {
+    isMultiTenant,
+    singleTenantUrl,
+    buildRenderConfig
+  } = await import('./tenant.js');
+  // Multi-tenant drives config through the React.cache slot
+  // (__prepareFontdueRender), which needs the per-request route param, so the
+  // resolver stays out of its way. The slot also wins the merge, so a
+  // multi-tenant __prepareFontdueRender call still overrides this when present.
+  if (isMultiTenant || !singleTenantUrl) return undefined;
+  return buildRenderConfig(new URL(singleTenantUrl).host);
+});

package/dist/next/revalidate.js

@@ -7,7 +7,7 @@
 // receive the tenant in the URL, e.g.
 //   POST /api/revalidate?domain=acme.fontdue.com
 // and only that tenant's cache is purged (pages and embed data share the
-// per-domain tag — see fontdueEndpoint/fontdueServerConfig in ./tenant).
+// per-domain tag — see endpointForDomain/fontdueServerConfig in ./tenant).
 // Single-tenant deployments use the parameterless form and purge everything
 // carrying the 'graphql' tag.
 

package/dist/next/tenant.d.ts

@@ -1,7 +1,10 @@
 import { type FontdueServerConfig } from '../relay/serverConfig.js';
 export declare const isMultiTenant: boolean;
+export declare const singleTenantUrl: string | undefined;
 export declare function isValidDomain(domain: string): boolean;
 export interface FontdueEndpoint {
+    /** The site domain this endpoint resolves. */
+    domain: string;
     /** Base URL the app's own GraphQL fetches should target. */
     origin: string;
     /** Headers the Fontdue server needs to resolve the tenant. */
@@ -12,7 +15,12 @@ export interface FontdueEndpoint {
      */
     tags: string[];
 }
-export declare function fontdueEndpoint(domain: string): FontdueEndpoint;
-export declare function fallbackSiteUrl(domain: string): string;
+export declare function endpointForDomain(domain: string): FontdueEndpoint;
 export declare function fontdueServerConfig(domain: string): FontdueServerConfig;
 export declare function configureFontdueRender(domain: string): FontdueEndpoint | null;
+interface RenderProps {
+    params: Promise<Record<string, string | string[] | undefined>>;
+}
+export declare function buildRenderConfig(domain: string): Promise<FontdueServerConfig>;
+export declare function __prepareFontdueRender(props: RenderProps): Promise<FontdueEndpoint>;
+export {};

package/dist/next/tenant.js

@@ -20,13 +20,17 @@
 //
 // The fontdue-js components embedded in pages fetch the same way: their
 // server-side preloads read the per-render config set by
-// configureFontdueRender, and in the browser they fetch the relative
-// /graphql on the page's own origin — so multi-tenant mode needs no
-// NEXT_PUBLIC_FONTDUE_URL at all.
+// __prepareFontdueRender (multi-tenant) or, in single-tenant apps, the ambient
+// resolver that <FontdueProvider> registers — no per-render setup call — and in
+// the browser they fetch the relative /graphql on the page's own origin, so
+// multi-tenant mode needs no NEXT_PUBLIC_FONTDUE_URL at all.
 
+import { notFound, unstable_rethrow } from 'next/navigation';
+import { cookies, draftMode } from 'next/headers';
 import { setFontdueServerConfig } from '../relay/serverConfig.js';
+import { PREVIEW_TOKEN_COOKIE, previewAuthHeaders } from '../preview/index.js';
 export const isMultiTenant = process.env.FONTDUE_MULTI_TENANT === '1';
-const singleTenantUrl = process.env.NEXT_PUBLIC_FONTDUE_URL;
+export const singleTenantUrl = process.env.NEXT_PUBLIC_FONTDUE_URL;
 const internalOrigin = process.env.FONTDUE_ORIGIN;
 const proxySecret = process.env.FONTDUE_PROXY_SECRET;
 
@@ -38,20 +42,19 @@ export function isValidDomain(domain) {
 }
 // Where to fetch GraphQL for a given tenant domain, plus any headers needed
 // for the Fontdue server to resolve that tenant.
-export function fontdueEndpoint(domain) {
+export function endpointForDomain(domain) {
   const tags = ['graphql', `graphql:${domain}`];
   if (!isMultiTenant) {
-    if (!singleTenantUrl) {
-      throw new Error('fontdue-js/next: set NEXT_PUBLIC_FONTDUE_URL (single-tenant) or FONTDUE_MULTI_TENANT=1 (multi-tenant).');
-    }
     return {
-      origin: singleTenantUrl,
+      domain,
+      origin: requireSingleTenantUrl(),
       headers: {},
       tags
     };
   }
   if (internalOrigin) {
     return {
+      domain,
       origin: internalOrigin,
       headers: {
         'x-forwarded-host': domain,
@@ -63,15 +66,17 @@ export function fontdueEndpoint(domain) {
     };
   }
   return {
+    domain,
     origin: `https://${domain}`,
     headers: {},
     tags
   };
 }
-
-// metadataBase / sitemap fallback when the site URL setting is empty.
-export function fallbackSiteUrl(domain) {
-  return isMultiTenant ? `https://${domain}` : 'http://localhost:3000';
+function requireSingleTenantUrl() {
+  if (!singleTenantUrl) {
+    throw new Error('fontdue-js/next: set NEXT_PUBLIC_FONTDUE_URL (single-tenant) or FONTDUE_MULTI_TENANT=1 (multi-tenant).');
+  }
+  return singleTenantUrl;
 }
 
 // Per-render config for fontdue-js's own server-side fetches: same endpoint
@@ -82,7 +87,7 @@ export function fontdueServerConfig(domain) {
   const {
     origin,
     headers
-  } = fontdueEndpoint(domain);
+  } = endpointForDomain(domain);
   return {
     url: origin,
     headers,
@@ -101,5 +106,95 @@ export function fontdueServerConfig(domain) {
 export function configureFontdueRender(domain) {
   if (!isValidDomain(domain)) return null;
   setFontdueServerConfig(fontdueServerConfig(domain));
-  return fontdueEndpoint(domain);
-}
+  return endpointForDomain(domain);
+}
+
+// The props every page, layout and generateMetadata receives. Any params
+// object is structurally compatible; only `domain` is read.
+
+// Build this render's server config for `domain` (origin, headers, per-site
+// cache tags) and install it for the rest of the pass. When a logged-in admin
+// is in preview (Next draft mode), fold the token into the headers and drop the
+// cache tags, so every server fetch in the render — the app's own and the
+// embedded components' preloads — reveals hidden fonts and stays live
+// (uncached, never landing in a shared cache).
+export async function buildRenderConfig(domain) {
+  const config = fontdueServerConfig(domain);
+  const previewHeaders = await readPreviewHeaders();
+  return previewHeaders ? {
+    ...config,
+    headers: {
+      ...config.headers,
+      ...previewHeaders
+    },
+    cacheTags: undefined
+  } : config;
+}
+async function applyRenderConfig(domain) {
+  setFontdueServerConfig(await buildRenderConfig(domain));
+}
+
+// Internal multi-tenant API (double-underscored, not part of the public
+// foundry surface): the one line at the top of every page, layout and
+// generateMetadata body in the multi-tenant [domain] route tree (the
+// Fontdue-hosted service):
+//
+//   await __prepareFontdueRender(props);
+//
+// Reads the request's site from the route param, 404s anything that isn't a
+// plain hostname, and configures the render (including preview) for that site.
+// It runs per entry point: a soft navigation re-renders only the page segment
+// with a fresh render store. Route handlers are not React renders — use the
+// returned endpoint explicitly there.
+export async function __prepareFontdueRender(props) {
+  const {
+    domain
+  } = await props.params;
+  if (typeof domain !== 'string' || !isValidDomain(domain)) notFound();
+  await applyRenderConfig(domain);
+  return endpointForDomain(domain);
+}
+
+// The admin preview token for this render, as Authorization headers, or
+// undefined when not previewing. Draft mode gates it: reading draftMode().
+// isEnabled is static-safe (it returns false during static generation and only
+// forces dynamic rendering when actually enabled), and the token cookie is only
+// read in the preview branch.
+//
+// The catch handles two very different throws, and the difference is load-
+// bearing for preview:
+//
+//   1. Next's dynamic-rendering bailout. When an admin is previewing, reading
+//      cookies() during a prerender/static pass throws a control-flow error
+//      (DynamicServerError / prerender interrupt) whose whole purpose is to
+//      tell Next "abandon the static render and go dynamic." This is the ONLY
+//      signal that takes a route in generateStaticParams off the full-route
+//      cache for the preview request. Swallowing it (as this used to) let Next
+//      serve the cached, token-less *public* render in preview, so the embedded
+//      components' own server preloads (createNetworkFetch) never saw the token
+//      — hidden fonts stayed hidden and @required(THROW) embeds like
+//      <BuyButton> crashed the server render (FD-712). unstable_rethrow re-
+//      throws exactly these control-flow errors so the route bails to a
+//      dynamic, token-bearing render. Public renders never hit this branch
+//      (draftMode().isEnabled is false → early return), so they stay static.
+//   2. A genuine "no request scope" throw (older runtimes calling
+//      draftMode()/cookies() with no request at all): not a control-flow error,
+//      so unstable_rethrow is a no-op and we fall through to "not previewing".
+async function readPreviewHeaders() {
+  try {
+    var _await$cookies$get;
+    if (!(await draftMode()).isEnabled) return undefined;
+    const token = (_await$cookies$get = (await cookies()).get(PREVIEW_TOKEN_COOKIE)) === null || _await$cookies$get === void 0 ? void 0 : _await$cookies$get.value;
+    return token ? previewAuthHeaders(token) : undefined;
+  } catch (error) {
+    unstable_rethrow(error);
+    return undefined;
+  }
+}
+
+// The single-tenant ambient resolver that lets a foundry skip per-render setup
+// is registered from ./registerSingleTenantResolver.ts (imported as a side
+// effect by the FontdueProvider react-server entrypoint), not here — so this
+// module's static next/* imports stay off that entrypoint's eager graph. The
+// resolver lazy-imports buildRenderConfig + singleTenantUrl + isMultiTenant
+// from this module at fetch time.

package/dist/preview/constants.d.ts

@@ -0,0 +1,9 @@
+export declare const PREVIEW_TOKEN_COOKIE = "fontdue_preview_token";
+export declare const PREVIEW_MARKER_COOKIE = "fontdue_preview";
+export declare const PREVIEW_ENDPOINT = "/api/preview";
+export declare const DEFAULT_PREVIEW_TTL_MS: number;
+export declare const PREVIEW_MARKER_GRACE_MS: number;
+export declare const PREVIEW_HEADER = "fontdue-preview";
+export declare function hasPreviewMarkerCookie(): boolean;
+export declare function getPreviewExpiry(): number | undefined;
+export declare function setPreviewMarkerCookie(on: boolean | number): void;

package/dist/preview/constants.js

@@ -0,0 +1,117 @@
+// Cookie + endpoint conventions for the admin preview contract.
+//
+// Kept in their own module (no Web/Node APIs) so the client-side toolbar can
+// import them without pulling in the server-only route handler — see ./index.
+
+// httpOnly cookie carrying the logged-in admin's short-lived admin token.
+// Only ever read server-side, where it's forwarded as
+// `Authorization: Bearer <token>` so GraphQL reveals hidden (unpublished) fonts.
+export const PREVIEW_TOKEN_COOKIE = 'fontdue_preview_token';
+
+// Readable twin of the token cookie. Lets the client toolbar tell preview is
+// on without exposing the token itself.
+export const PREVIEW_MARKER_COOKIE = 'fontdue_preview';
+
+// Default path the toolbar POSTs (enter) / DELETEs (exit) to. Relative, so it
+// hits the storefront's own origin. Override per app via
+// FontdueConfig.preview.endpoint (and mount the route to match).
+export const PREVIEW_ENDPOINT = '/api/preview';
+
+// Canonical preview-token lifetime, in ms. The token is a stateless
+// `Phoenix.Token` with a fixed 1-hour `max_age` (see the backend
+// `Fontage.Token` `:admin_token` `verify` — `max_age: 60 * 60`). It is the
+// source of truth; this constant only exists as a *fallback* for when the
+// `createAdminToken` mutation hasn't yet been taught to return its real
+// `expiresAt` (the backend half ships separately). Keep these two in lockstep.
+export const DEFAULT_PREVIEW_TTL_MS = 60 * 60 * 1000;
+
+// How long past the token's expiry the readable marker cookie should live.
+// The marker outlives the token on purpose: once the token lapses, the toolbar
+// must still find the marker so it can show the "preview expired" warning and
+// offer "re-enter" — rather than the cookie silently vanishing and the toolbar
+// snapping back to "not previewing" (which would hide the very problem from the
+// admin). A few hours of grace comfortably covers a backgrounded tab.
+export const PREVIEW_MARKER_GRACE_MS = 4 * 60 * 60 * 1000;
+
+// Request header storefront fetches send to declare preview intent explicitly.
+// The GraphQL server reveals hidden (unpublished) fonts only when this is
+// "true" AND the request is an authenticated admin — so merely *being* logged
+// in (an admin session cookie riding a storefront fetch) never leaks hidden
+// fonts outside preview. "false" forces the public view even for an admin; an
+// absent header (older fontdue-js clients) keeps the legacy "any admin sees
+// hidden" behavior, so older integrations are unaffected. See the matching
+// server logic in FontageWeb.Schema.Context.
+export const PREVIEW_HEADER = 'fontdue-preview';
+
+// The marker cookie's *value* now encodes the token's expiry as epoch-ms, e.g.
+// `fontdue_preview=1718640000000`. Previously it was a bare `1`; that legacy
+// value still parses (as 1ms after the epoch → always "expired"), so any stale
+// `=1` cookie left from an older client degrades safely to the warning state
+// rather than reading as a live preview. Empty / unset means "not previewing".
+
+// Raw value of the marker cookie on the current document, or undefined when the
+// cookie is absent or we're not in a browser. Browser-only and guarded so it
+// stays inert during server rendering.
+function readPreviewMarkerValue() {
+  if (typeof document === 'undefined') return undefined;
+  for (const part of document.cookie.split('; ')) {
+    const idx = part.indexOf('=');
+    if (idx === -1) continue;
+    if (part.slice(0, idx) !== PREVIEW_MARKER_COOKIE) continue;
+    const value = part.slice(idx + 1);
+    return value === '' ? undefined : value;
+  }
+  return undefined;
+}
+
+// Whether the readable preview marker cookie is present on the current
+// document. Lets the admin toolbar and the client-side Relay network layer tell
+// that an admin entered preview, so storefront fetches can send PREVIEW_HEADER
+// "true" while the marker is set and "false" otherwise. Presence — not
+// freshness — gates the header: a just-expired token still needs its render to
+// stay out of the public cache until the admin re-enters or exits, and the
+// server independently rejects a dead token, so a marker with a past expiry
+// never actually leaks hidden fonts.
+export function hasPreviewMarkerCookie() {
+  return readPreviewMarkerValue() !== undefined;
+}
+
+// Expiry (epoch-ms) stored in the marker cookie, or undefined when the marker
+// is absent or its value isn't a finite number. The toolbar compares this to
+// `Date.now()` to choose between the "previewing" and "preview expired" states.
+export function getPreviewExpiry() {
+  const value = readPreviewMarkerValue();
+  if (value === undefined) return undefined;
+  const expiry = Number(value);
+  return Number.isFinite(expiry) ? expiry : undefined;
+}
+
+// Set or clear the readable preview marker cookie directly in the browser.
+//
+// The script-tag (CDN) embed has no server preview route to broker an httpOnly
+// token through — and needs none: it is client-only, so its GraphQL fetches
+// carry the admin's Fontdue session cookie cross-origin (SameSite=None) and the
+// server reveals hidden fonts on `fontdue-preview: true` alone. This marker is
+// what flips the client-side Relay layer to send that header (see
+// hasPreviewMarkerCookie). It is NOT a credential — the admin session still
+// gates the reveal, so a non-admin setting it just sees the public view.
+//
+// When entering (`on` truthy), `on` is the token's expiry as epoch-ms; the
+// cookie stores it and is given a Max-Age that outlives the token by
+// PREVIEW_MARKER_GRACE_MS so the toolbar can reach the "expired" warning state.
+// Passing `false` clears the cookie. (A bare `true` keeps older call sites
+// working by falling back to now + DEFAULT_PREVIEW_TTL_MS.)
+//
+// Secure is set on https (the marker stays JS-readable; Secure only restricts
+// the transport) and omitted on http so it still persists in local dev.
+export function setPreviewMarkerCookie(on) {
+  if (typeof document === 'undefined') return;
+  const secure = typeof location !== 'undefined' && location.protocol === 'https:' ? '; Secure' : '';
+  if (on === false) {
+    document.cookie = `${PREVIEW_MARKER_COOKIE}=; Path=/; SameSite=Lax${secure}; Max-Age=0`;
+    return;
+  }
+  const expiresAt = typeof on === 'number' ? on : Date.now() + DEFAULT_PREVIEW_TTL_MS;
+  const maxAgeSeconds = Math.max(0, Math.ceil((expiresAt - Date.now() + PREVIEW_MARKER_GRACE_MS) / 1000));
+  document.cookie = `${PREVIEW_MARKER_COOKIE}=${expiresAt}; Path=/; SameSite=Lax${secure}; Max-Age=${maxAgeSeconds}`;
+}

package/dist/preview/index.d.ts

@@ -0,0 +1,53 @@
+import { PREVIEW_TOKEN_COOKIE, PREVIEW_MARKER_COOKIE, PREVIEW_ENDPOINT, DEFAULT_PREVIEW_TTL_MS, PREVIEW_MARKER_GRACE_MS } from './constants.js';
+export { PREVIEW_TOKEN_COOKIE, PREVIEW_MARKER_COOKIE, PREVIEW_ENDPOINT, DEFAULT_PREVIEW_TTL_MS, PREVIEW_MARKER_GRACE_MS, };
+export interface PreviewCookieOptions {
+    /**
+     * Whether to set the cookies' Secure attribute. Defaults to true on https
+     * requests and false otherwise, so cookies work over http in local dev.
+     */
+    secure?: boolean;
+    /** SameSite attribute. Defaults to 'lax' — the toolbar is same-site. */
+    sameSite?: 'lax' | 'strict' | 'none';
+    /** Cookie path. Defaults to '/'. */
+    path?: string;
+}
+/**
+ * Web-standard route handler implementing the portable preview contract. Wire
+ * it into your framework's route at the path the toolbar targets
+ * (`/api/preview` by default):
+ *
+ *   // Astro: src/pages/api/preview.ts
+ *   import { handlePreviewRequest } from 'fontdue-js/preview';
+ *   export const ALL: APIRoute = ({ request }) => handlePreviewRequest(request);
+ *
+ *   // React Router 7: app/routes/api.preview.ts
+ *   import { handlePreviewRequest } from 'fontdue-js/preview';
+ *   export const action = ({ request }: Route.ActionArgs) =>
+ *     handlePreviewRequest(request);
+ *
+ * POST expects a JSON body `{ token: string, expiresAt?: string | number }`;
+ * DELETE takes no body. `expiresAt` (ISO-8601 or epoch-ms) is the token's
+ * expiry; it's stored in the readable marker cookie so the toolbar can warn
+ * when preview has lapsed, and defaults to now + DEFAULT_PREVIEW_TTL_MS when
+ * omitted. The token is opaque here — the Fontdue GraphQL server validates it
+ * on each request, so a forged token simply reveals nothing. Frameworks that
+ * cache HTML should also bypass their shared/CDN cache when
+ * PREVIEW_MARKER_COOKIE is present, so an admin preview is never served to the
+ * public.
+ */
+export declare function handlePreviewRequest(request: Request, options?: PreviewCookieOptions): Promise<Response>;
+/**
+ * Extract the preview token from a Cookie header string, e.g.
+ * `readPreviewToken(request.headers.get('cookie'))`. This is the canonical
+ * reader — it reverses the encoding `handlePreviewRequest` applies, so the
+ * token comes back verbatim. Returns undefined when not in preview.
+ */
+export declare function readPreviewToken(cookieHeader: string | null | undefined): string | undefined;
+/**
+ * Headers to merge into a server-side GraphQL fetch so the request reveals
+ * hidden fonts. Spread the result into your app's fetch headers, into
+ * fontdue-js's per-render `serverConfig.headers`, or into the `headers` option
+ * of a preload helper (loadFontdueProviderQuery, loadTypeTesterQuery, …).
+ * Returns {} when there is no token, so it's safe to spread unconditionally.
+ */
+export declare function previewAuthHeaders(token: string | null | undefined): Record<string, string>;