fontdue-js 3.0.0-alpha9 → 3.0.1

package/dist/metricFallback.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Per-family metric-matched fallback fonts.
+ *
+ * The generic `Fallback` font renders a dot for every codepoint but has fixed
+ * metrics, so while a real font loads (or for glyphs it lacks) the dots don't
+ * match the real font's line height or average width — the text reflows when
+ * the real font swaps in.
+ *
+ * This builds, per family, a fallback `FontFace` from the *same* dot-font bytes
+ * but with `size-adjust` + ascent/descent/line-gap overrides derived from that
+ * font's metrics, so the placeholder dots already occupy the right box. One
+ * shared buffer backs every face. The maths is the capsize / `next/font`
+ * formulation: with `size-adjust: S`, the override percentages are the target
+ * ratios divided by S (a metric overridden as a % of font-size is then scaled
+ * by `size-adjust`, so we pre-divide to land back on the target ratio).
+ */
+declare global {
+    interface FontFaceDescriptors {
+        sizeAdjust?: string;
+    }
+}
+export interface TargetMetrics {
+    readonly unitsPerEm: number;
+    readonly ascender: number;
+    readonly descender: number;
+    readonly lineGap: number | null;
+    readonly avgCharWidth?: number | null;
+}
+/** The font-family name of the metric-matched fallback for `family`. */
+export declare function metricFallbackFamily(family: string): string;
+/**
+ * The FontFace descriptors that make the dot font match `metrics`, or `null`
+ * if the metrics are unusable. `size-adjust` matches the average character
+ * width; the overrides are the target ratios divided by `size-adjust` (it
+ * scales overridden metrics, so we pre-divide). Without `avgCharWidth` there's
+ * no `size-adjust` and the overrides are the raw target ratios.
+ *
+ * Pure (no FontFace/DOM) so the maths is unit-testable.
+ */
+export declare function fallbackDescriptors(metrics: TargetMetrics | null | undefined): FontFaceDescriptors | null;
+/**
+ * Register (once) a metric-matched fallback face for `family`, derived from the
+ * dot font + `metrics`. Safe to call repeatedly and on every render. Returns
+ * the family name to put in the CSS stack, or `null` when it can't be built
+ * (no metrics, or no FontFace API / SSR) so the caller uses the generic
+ * `Fallback`.
+ */
+export declare function ensureMetricFallback(family: string, metrics: TargetMetrics | null | undefined): string | null;

package/dist/metricFallback.js

@@ -0,0 +1,98 @@
+import { FALLBACK_FONT_WOFF2_BASE64, FALLBACK_ADVANCE_PER_EM } from './fallbackFontData.js';
+
+/**
+ * Per-family metric-matched fallback fonts.
+ *
+ * The generic `Fallback` font renders a dot for every codepoint but has fixed
+ * metrics, so while a real font loads (or for glyphs it lacks) the dots don't
+ * match the real font's line height or average width — the text reflows when
+ * the real font swaps in.
+ *
+ * This builds, per family, a fallback `FontFace` from the *same* dot-font bytes
+ * but with `size-adjust` + ascent/descent/line-gap overrides derived from that
+ * font's metrics, so the placeholder dots already occupy the right box. One
+ * shared buffer backs every face. The maths is the capsize / `next/font`
+ * formulation: with `size-adjust: S`, the override percentages are the target
+ * ratios divided by S (a metric overridden as a % of font-size is then scaled
+ * by `size-adjust`, so we pre-divide to land back on the target ratio).
+ */
+
+// `sizeAdjust` is a real FontFace descriptor (Chrome 92+, Firefox 92+,
+// Safari 17+) but is missing from the bundled lib.dom.d.ts FontFaceDescriptors.
+
+/** The font-family name of the metric-matched fallback for `family`. */
+export function metricFallbackFamily(family) {
+  return `${family} fallback`;
+}
+let sharedBuffer = null;
+const registered = new Set();
+function getBuffer() {
+  if (!sharedBuffer) {
+    const binary = atob(FALLBACK_FONT_WOFF2_BASE64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    sharedBuffer = bytes.buffer;
+  }
+  return sharedBuffer;
+}
+function pct(value) {
+  return `${value * 100}%`;
+}
+
+/**
+ * The FontFace descriptors that make the dot font match `metrics`, or `null`
+ * if the metrics are unusable. `size-adjust` matches the average character
+ * width; the overrides are the target ratios divided by `size-adjust` (it
+ * scales overridden metrics, so we pre-divide). Without `avgCharWidth` there's
+ * no `size-adjust` and the overrides are the raw target ratios.
+ *
+ * Pure (no FontFace/DOM) so the maths is unit-testable.
+ */
+export function fallbackDescriptors(metrics) {
+  if (!metrics || !(metrics.unitsPerEm > 0)) return null;
+  const {
+    unitsPerEm: upem,
+    ascender,
+    descender,
+    lineGap,
+    avgCharWidth
+  } = metrics;
+  const descriptors = {
+    display: 'block'
+  };
+  let sizeAdjust = 1;
+  if (avgCharWidth && avgCharWidth > 0) {
+    sizeAdjust = avgCharWidth / upem / FALLBACK_ADVANCE_PER_EM;
+    descriptors.sizeAdjust = pct(sizeAdjust);
+  }
+  descriptors.ascentOverride = pct(ascender / upem / sizeAdjust);
+  descriptors.descentOverride = pct(Math.abs(descender) / upem / sizeAdjust);
+  descriptors.lineGapOverride = pct((lineGap ?? 0) / upem / sizeAdjust);
+  return descriptors;
+}
+
+/**
+ * Register (once) a metric-matched fallback face for `family`, derived from the
+ * dot font + `metrics`. Safe to call repeatedly and on every render. Returns
+ * the family name to put in the CSS stack, or `null` when it can't be built
+ * (no metrics, or no FontFace API / SSR) so the caller uses the generic
+ * `Fallback`.
+ */
+export function ensureMetricFallback(family, metrics) {
+  const descriptors = fallbackDescriptors(metrics);
+  if (!descriptors) return null;
+  if (typeof FontFace === 'undefined' || typeof document === 'undefined') {
+    return null;
+  }
+  const name = metricFallbackFamily(family);
+  if (registered.has(name)) return name;
+  registered.add(name);
+  try {
+    const face = new FontFace(name, getBuffer(), descriptors);
+    face.load().then(() => document.fonts.add(face)).catch(() => registered.delete(name));
+  } catch {
+    registered.delete(name);
+    return null;
+  }
+  return name;
+}

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, fontdueServerConfig, configureFontdueRender, prepareFontdueRender, currentFontdueEndpoint, generateStaticParams, 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, fontdueServerConfig, configureFontdueRender, prepareFontdueRender, currentFontdueEndpoint, generateStaticParams } 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,5 +1,6 @@
 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. */
@@ -14,13 +15,12 @@ export interface FontdueEndpoint {
      */
     tags: string[];
 }
-export declare function fontdueEndpoint(domain: string): FontdueEndpoint;
+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 prepareFontdueRender(props: RenderProps): Promise<FontdueEndpoint>;
-export declare function currentFontdueEndpoint(): FontdueEndpoint;
-export declare function generateStaticParams(): Promise<never[]>;
+export declare function buildRenderConfig(domain: string): Promise<FontdueServerConfig>;
+export declare function __prepareFontdueRender(props: RenderProps): Promise<FontdueEndpoint>;
 export {};

package/dist/next/tenant.js

@@ -20,14 +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 } from 'next/navigation';
-import { setFontdueServerConfig, getFontdueServerConfig } from '../relay/serverConfig.js';
+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;
 
@@ -39,7 +42,7 @@ 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) {
     return {
@@ -84,12 +87,11 @@ export function fontdueServerConfig(domain) {
   const {
     origin,
     headers
-  } = fontdueEndpoint(domain);
+  } = endpointForDomain(domain);
   return {
     url: origin,
     headers,
-    cacheTags: [`graphql:${domain}`],
-    domain
+    cacheTags: [`graphql:${domain}`]
   };
 }
 
@@ -104,66 +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.
 
-// The one line at the top of every page, layout and generateMetadata body
-// in the [domain] route tree:
-//
-//   await prepareFontdueRender(props);
-//
-// Reads the request's site from the [domain] route param, 404s anything
-// that isn't a plain hostname (stray paths can reach the catch-all route
-// with their first segment as the "domain"), and points every Fontdue fetch
-// in the rest of this render pass — the app's fetches via
-// currentFontdueEndpoint and fontdue-js's embedded-component preloads — at
-// that site.
+// 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):
 //
-// It must run per entry point, not only in the layout: a soft navigation
-// re-renders just the page segment, and the per-render store starts empty
-// on every pass. Forgetting it is loud, not subtle: currentFontdueEndpoint
-// throws in multi-tenant mode when no render config was set.
+//   await __prepareFontdueRender(props);
 //
-// Route handlers are not React renders — the render-scoped store doesn't
-// exist there, so use the returned endpoint explicitly instead of relying
-// on currentFontdueEndpoint.
-export async function 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;
-  const endpoint = typeof domain === 'string' ? configureFontdueRender(domain) : null;
-  if (!endpoint) notFound();
-  return endpoint;
+  if (typeof domain !== 'string' || !isValidDomain(domain)) notFound();
+  await applyRenderConfig(domain);
+  return endpointForDomain(domain);
 }
 
-// Endpoint for the app's own GraphQL fetches in this render pass: whatever
-// prepareFontdueRender configured, or — in a single-tenant app without the
-// [domain] tree, where prepareFontdueRender is never called — the
-// NEXT_PUBLIC_FONTDUE_URL site. Throwing rather than guessing in
-// multi-tenant mode turns a forgotten prepareFontdueRender into an
-// unmissable error instead of a silent wrong-site fetch on soft
-// navigations.
-export function currentFontdueEndpoint() {
-  var _getFontdueServerConf;
-  const domain = (_getFontdueServerConf = getFontdueServerConfig()) === null || _getFontdueServerConf === void 0 ? void 0 : _getFontdueServerConf.domain;
-  if (domain) return fontdueEndpoint(domain);
-  if (isMultiTenant) {
-    throw new Error('fontdue-js/next: no render config set — call prepareFontdueRender(props) at the top of every page, layout and generateMetadata that fetches.');
+// 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;
   }
-  return fontdueEndpoint(new URL(requireSingleTenantUrl()).host);
 }
 
-// Re-export from routes in the [domain] tree:
-//
-//   export { generateStaticParams } from 'fontdue-js/next';
-//
-// Domains aren't known at build time, so nothing is prerendered — but
-// providing generateStaticParams is what opts a dynamic route into
-// static-on-demand rendering (generated on first request, then cached until
-// revalidated) instead of fully dynamic rendering.
-export async function generateStaticParams() {
-  return [];
-}
+// 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}`;
+}