fontdue-js 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 3.2.0
+
+- **Fixed password-protected collections crashing statically-rendered Next.js storefronts.** Locked slugs are excluded from `generateStaticParams`, so a visitor's first request for one triggers an on-demand static fill of the font page — and the unlock-cookie read during that fill crashed it with a 500 (digest `DYNAMIC_SERVER_USAGE`). A locked page's static fill now renders (and caches) the password form, and unlocking takes that visitor past the static cache instead — the same mechanism as admin preview:
+  - New route handler `fontdue-js/next/unlock`. Mount it in your app (`export { POST } from "fontdue-js/next/unlock"` in `app/api/unlock/route.ts`): on a successful unlock it enables Next draft mode, whose bypass cookie makes that one visitor's renders dynamic, so the unlock cookie is read and the collection resolves. Everyone else keeps the static pages.
+  - New `unlockEndpoint` prop on `NodePasswordForm` — the form POSTs the access token there before reloading. Pass `unlockEndpoint="/api/unlock"` on statically-rendered Next storefronts; omit it on frameworks that render per request (Astro, React Router 7, TanStack Start), where the cookie alone unlocks.
+  - `nodeAccessHeaders()` (`fontdue-js/next`) now reads the unlock cookie only during draft-mode renders, so a locked page's static fill is never flagged dynamic. See [Password-protected collections](https://www.fontdue.com/docs/develop/password-protected-collections).
+
 ## 3.1.0
 
 - **New `FeatureTesters` component** (`fontdue-js/FeatureTesters`) — renders a collection's *feature tester* cards, each showcasing an OpenType feature by toggling it on and off and tinting exactly the characters the feature changes. Pass `collectionId` or `collectionSlug`; in a React Server Component the server entry preloads its own query, and in a client tree (`preloadedQuery` or inside a `<FontdueProvider>`) it hydrates or lazy-loads like the other collection components. Collection-level props override the per-card dashboard settings: `highlightColor`, `toggle` (`'button'` or `'hover'`), and `autofit`. Requires a Fontdue backend that exposes `FontCollection.featureTesters` and the `FeatureTester` node. See [Feature Testers](https://www.fontdue.com/docs/reference/feature-testers).

package/dist/__tests__/nextAdapter.test.js

@@ -48,17 +48,23 @@ vi.mock('next/navigation', () => ({
 const draft = vi.hoisted(() => ({
   enabled: false,
   token: undefined,
+  nodeAccess: undefined,
   cookiesError: undefined
 }));
 vi.mock('next/headers', () => ({
   draftMode: async () => ({
-    isEnabled: draft.enabled
+    isEnabled: draft.enabled,
+    enable: () => {
+      draft.enabled = true;
+    }
   }),
   cookies: async () => {
     if (draft.cookiesError) throw draft.cookiesError;
     return {
       get: name => name === 'fontdue_preview_token' && draft.token ? {
         value: draft.token
+      } : name === 'fontdue_node_access' && draft.nodeAccess ? {
+        value: draft.nodeAccess
       } : undefined
     };
   }
@@ -74,6 +80,7 @@ beforeEach(() => {
   vi.restoreAllMocks();
   draft.enabled = false;
   draft.token = undefined;
+  draft.nodeAccess = undefined;
   draft.cookiesError = undefined;
 });
 function stubSingleTenant() {
@@ -360,6 +367,113 @@ describe('single-tenant ambient resolver (no per-render call)', () => {
     expect(config === null || config === void 0 ? void 0 : (_config$headers5 = config.headers) === null || _config$headers5 === void 0 ? void 0 : _config$headers5.authorization).toBeUndefined();
   });
 });
+describe('nodeAccessHeaders', () => {
+  it('draft-mode bypass render: returns the forwarding header', async () => {
+    stubSingleTenant();
+    draft.enabled = true;
+    draft.nodeAccess = 'na-tok';
+    const {
+      nodeAccessHeaders
+    } = await importTenant();
+    expect(await nodeAccessHeaders()).toEqual({
+      'fontdue-node-access': 'na-tok'
+    });
+  });
+  it('draft-mode bypass render without the cookie: returns {}', async () => {
+    stubSingleTenant();
+    draft.enabled = true;
+    const {
+      nodeAccessHeaders
+    } = await importTenant();
+    expect(await nodeAccessHeaders()).toEqual({});
+  });
+
+  // Regression for FD-773: locked slugs are excluded from generateStaticParams,
+  // so a visitor's first request is an on-demand STATIC fill of the SSG route.
+  // Merely calling cookies() there flags the render as dynamic and Next 15
+  // 500s ("Page changed from static to dynamic at runtime") — catching the
+  // throw doesn't unpoison it. Off draft mode the hook must return "no token"
+  // WITHOUT touching cookies(), so the fill can prerender the password form.
+  // cookiesError guards the "without touching" half: any cookies() call would
+  // reject.
+  it('runtime static fill (no draft mode): no token, and cookies() is never called', async () => {
+    stubSingleTenant();
+    draft.cookiesError = Object.assign(new Error('Dynamic server usage'), {
+      digest: 'DYNAMIC_SERVER_USAGE'
+    });
+    const {
+      nodeAccessHeaders
+    } = await importTenant();
+    expect(await nodeAccessHeaders()).toEqual({});
+  });
+
+  // At build time the gate is skipped and the bailout keeps propagating: a
+  // static route whose own fetch touches a locked collection bails out to
+  // dynamic at build today, and the fix must not change build classification.
+  it('build-time prerender: still propagates the dynamic bailout', async () => {
+    stubSingleTenant();
+    vi.stubEnv('NEXT_PHASE', 'phase-production-build');
+    draft.cookiesError = Object.assign(new Error('Dynamic server usage'), {
+      digest: 'DYNAMIC_SERVER_USAGE'
+    });
+    const {
+      nodeAccessHeaders
+    } = await importTenant();
+    await expect(nodeAccessHeaders()).rejects.toBe(draft.cookiesError);
+  });
+  it('swallows a non-control-flow throw (no request scope)', async () => {
+    stubSingleTenant();
+    draft.enabled = true;
+    draft.cookiesError = new Error('no request scope');
+    const {
+      nodeAccessHeaders
+    } = await importTenant();
+    expect(await nodeAccessHeaders()).toEqual({});
+  });
+});
+describe('unlock route handler', () => {
+  async function importUnlock() {
+    return await import("../next/unlock.js");
+  }
+  function unlockRequest(body) {
+    return new Request('https://storefront.example/api/unlock', {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json'
+      },
+      body
+    });
+  }
+  it('POST with a token enables the draft-mode bypass', async () => {
+    const {
+      POST
+    } = await importUnlock();
+    const response = await POST(unlockRequest(JSON.stringify({
+      token: 'na-tok'
+    })));
+    expect(response.status).toBe(200);
+    expect(await response.json()).toEqual({
+      ok: true
+    });
+    expect(draft.enabled).toBe(true);
+  });
+  it('rejects a missing token without enabling the bypass', async () => {
+    const {
+      POST
+    } = await importUnlock();
+    const response = await POST(unlockRequest(JSON.stringify({})));
+    expect(response.status).toBe(400);
+    expect(draft.enabled).toBe(false);
+  });
+  it('rejects a malformed body without enabling the bypass', async () => {
+    const {
+      POST
+    } = await importUnlock();
+    const response = await POST(unlockRequest('not json'));
+    expect(response.status).toBe(400);
+    expect(draft.enabled).toBe(false);
+  });
+});
 
 // withFontdue detects the route-tree shape from the working directory; give
 // it one with or without src/app/[domain].

package/dist/components/NodePasswordForm/index.d.ts

@@ -2,6 +2,17 @@ import React from 'react';
 export interface NodePasswordForm_props {
     collectionId?: string | null;
     collectionSlug?: string | null;
+    /**
+     * Path of the storefront's unlock route (see fontdue-js/next/unlock), e.g.
+     * "/api/unlock". On a successful unlock the form POSTs `{ token }` there
+     * before reloading. Required on statically-rendered Next storefronts: the
+     * route enables the draft-mode bypass that takes this visitor off the
+     * full-route cache, so the reload can actually render the unlocked
+     * collection instead of re-serving the cached password form. Omit on
+     * frameworks that render server responses per request (Astro, React Router,
+     * TanStack Start) — there the cookie alone is enough.
+     */
+    unlockEndpoint?: string | null;
 }
 /**
  * Password form for a collection you already know is locked. Render it when a

package/dist/components/NodePasswordForm/index.js

@@ -25,6 +25,29 @@ const accessNodeMutation = (_NodePasswordFormAccessNodeMutation.hash && _NodePas
 export default function NodePasswordForm(props) {
   return /*#__PURE__*/React.createElement(EnsureFontdueContext, null, /*#__PURE__*/React.createElement(NodePasswordFormFields, props));
 }
+
+// Tell the storefront's unlock route (fontdue-js/next/unlock) about a
+// successful unlock so it can enable Next's draft-mode bypass — without it, a
+// statically-cached font page would keep serving this visitor the password
+// form after they unlocked (the full-route cache is visitor-blind). Always
+// resolves: the reload must happen even if the endpoint is absent or errors,
+// because on per-request-rendered frameworks the cookie alone unlocks.
+async function notifyUnlockEndpoint(endpoint, token) {
+  if (!endpoint || !token) return;
+  try {
+    await fetch(endpoint, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json'
+      },
+      body: JSON.stringify({
+        token
+      })
+    });
+  } catch {
+    // Ignore: reload regardless, the cookie may still be enough.
+  }
+}
 function NodePasswordFormFields(props) {
   const [password, setPassword] = useState('');
   const [error, setError] = useState(null);
@@ -49,7 +72,7 @@ function NodePasswordFormFields(props) {
           // ride a proxied or cross-origin server fetch, so we forward this
           // token as a header instead (see fontdue-js nodeAccess).
           rememberNodeAccessToken(res.accessNode.token);
-          location.reload();
+          notifyUnlockEndpoint(props.unlockEndpoint, res.accessNode.token).then(() => location.reload());
         } else {
           setError('Incorrect password');
         }

package/dist/next/index.js

@@ -1,6 +1,7 @@
 // Server-side entrypoint for Next.js apps (the App Router / RSC adapter).
-// The config-time wrapper lives in 'fontdue-js/next/config' and the deploy
-// hook route handler in 'fontdue-js/next/revalidate'.
+// The config-time wrapper lives in 'fontdue-js/next/config', the deploy
+// hook route handler in 'fontdue-js/next/revalidate', and the
+// password-unlock route handler in 'fontdue-js/next/unlock'.
 
 // Single-tenant apps need NO per-render setup and nothing from this entrypoint:
 // mounting <FontdueProvider> registers the ambient resolver that configures

package/dist/next/tenant.js

@@ -163,13 +163,41 @@ export async function __prepareFontdueRender(props) {
 //
 // Reading cookies() opts the route into dynamic rendering, so call this only
 // when it's actually needed — after a public fetch comes back
-// password-protected — to keep non-protected font pages static/cacheable. The
-// catch mirrors readPreviewHeaders: re-throw Next's control-flow bailout so a
-// protected page renders dynamically instead of being prerendered cookie-blind
-// (which would serve the locked form to a visitor who has unlocked it).
+// password-protected — to keep non-protected font pages static/cacheable.
+//
+// The draft-mode gate is where the caching architecture for locked
+// collections lives, so spelling it out: locked slugs are excluded from
+// generateStaticParams, so a visitor's first request for one is an on-demand
+// STATIC fill of an SSG route. Merely CALLING cookies() there flags the
+// render as dynamic, and Next 15 cannot take a runtime fill dynamic the way a
+// build-time pass can — it 500s ("Page changed from static to dynamic at
+// runtime", or DYNAMIC_SERVER_USAGE; FD-773). Catching the throw doesn't
+// help: the render is already poisoned by the call. So the cookie must not be
+// read at all unless this render is a draft-mode one — draftMode().isEnabled
+// is static-safe (readPreviewHeaders below leans on the same property), false
+// during any static pass.
+//
+// Gating on draft mode is not just crash avoidance, it IS the design: with
+// the gate, a locked slug's static fill renders (and caches) the password
+// form — the correct public view. The full-route cache is visitor-blind, so
+// no cookie could ever change what it serves anyway; the only way a visitor
+// sees unlocked content is off the static cache entirely. That's what the
+// unlock route handler (see ./unlock) provides: on a successful unlock the
+// form POSTs there, draft mode's bypass cookie takes this visitor's requests
+// to dynamic renders, the gate opens, and the token folds in here. (Exactly
+// the admin-preview model, with the password standing in for the admin
+// session.)
+//
+// At build time (NEXT_PHASE=phase-production-build) the gate is skipped and
+// the cookies() read trips Next's dynamic bailout, which unstable_rethrow
+// propagates: a build-time render whose own fetch touches a locked collection
+// bails that route out to dynamic today, and baking a cookie-blind form into
+// such a page is a behavior change we don't need for this fix. Non-bailout
+// throws (no request scope at all) still fall through to "no token".
 export async function nodeAccessHeaders() {
   try {
     var _await$cookies$get;
+    if (!isBuildPhase() && !(await draftMode()).isEnabled) return {};
     const value = (_await$cookies$get = (await cookies()).get(NODE_ACCESS_COOKIE)) === null || _await$cookies$get === void 0 ? void 0 : _await$cookies$get.value;
     return value ? {
       [NODE_ACCESS_HEADER]: value
@@ -179,6 +207,9 @@ export async function nodeAccessHeaders() {
     return {};
   }
 }
+function isBuildPhase() {
+  return typeof process !== 'undefined' && process.env.NEXT_PHASE === 'phase-production-build';
+}
 
 // The admin preview token for this render, as Authorization headers, or
 // undefined when not previewing. Draft mode gates it: reading draftMode().

package/dist/next/unlock.d.ts

@@ -0,0 +1,3 @@
+/** Default path the templates mount the handler at. */
+export declare const UNLOCK_ENDPOINT = "/api/unlock";
+export declare function POST(request: Request): Promise<Response>;

package/dist/next/unlock.js

@@ -0,0 +1,49 @@
+// Route handler that lets a visitor who unlocked a password-protected
+// collection actually see it on a statically-served Next storefront.
+// Re-export it from app/api/unlock/route.ts:
+//
+//   export { POST } from 'fontdue-js/next/unlock';
+//
+// and pass the route's path to the form: <NodePasswordForm
+// unlockEndpoint="/api/unlock" …/>. On a successful unlock the form POSTs the
+// access token here before reloading.
+//
+// Why this exists (FD-773): font pages are SSG, and Next's full-route cache is
+// visitor-blind — once a locked collection's page is (correctly) cached as the
+// password form, no cookie the form sets can change what the cache serves.
+// Enabling Next draft mode sets the __prerender_bypass cookie, which is the
+// one sanctioned way to take a single visitor off the full-route cache: their
+// subsequent requests render dynamically, nodeAccessHeaders() (fontdue-js/next)
+// reads the node-access cookie, and the collection resolves. Everyone else
+// keeps getting the static pages. This mirrors the admin-preview route
+// (/api/preview in the templates), which layers the same draft-mode bypass on
+// the preview cookie contract — including its trust model: the token is opaque
+// here and validated by the Fontdue GraphQL server on every request, so a
+// forged POST reveals nothing and buys the caller only their own dynamic
+// renders, exactly like a forged preview POST.
+//
+// The bypass cookie is a session cookie, while the node-access cookie lasts ~30
+// days. A returning visitor whose bypass lapsed sees the static form again and
+// re-enters the password; re-unlocking re-enables the bypass. There is no
+// DELETE: draft mode is shared with admin preview, so an unlock exit must not
+// tear down an active preview — the bypass simply expires with the session.
+
+import { draftMode } from 'next/headers';
+
+/** Default path the templates mount the handler at. */
+export const UNLOCK_ENDPOINT = '/api/unlock';
+export async function POST(request) {
+  const body = await request.json().catch(() => ({}));
+  if (typeof body.token !== 'string' || body.token === '') {
+    return Response.json({
+      ok: false,
+      error: 'Missing access token'
+    }, {
+      status: 400
+    });
+  }
+  (await draftMode()).enable();
+  return Response.json({
+    ok: true
+  });
+}

package/dist/relay/environment.js

@@ -8,7 +8,7 @@ import { NODE_ACCESS_HEADER } from '../nodeAccess.js';
 // (defineVersionPlugin in .babelrc.cjs) with the literal package.json#version.
 // Exported so UI (the admin toolbar) can surface it without re-reading the
 // build-time global in a 'use client' module.
-export const version = "3.1.0";
+export const version = "3.2.0";
 const IS_SERVER = typeof window === typeof undefined;
 
 // Opt server fetches into Next's data cache only in production; dev stays

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fontdue-js",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "type": "module",
   "scripts": {
     "build": "npm run relay && run-p build-js build-css build-ts",
@@ -90,6 +90,7 @@
     "./next": "./dist/next/index.js",
     "./next/config": "./dist/next/config.js",
     "./next/revalidate": "./dist/next/revalidate.js",
+    "./next/unlock": "./dist/next/unlock.js",
     "./next/image-loader": "./dist/next/image-loader.js",
     "./fontdue.css": "./dist/fontdue.css",
     "./BuyButton": {

package/types/next-headers.d.ts

@@ -2,7 +2,11 @@
 // 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 draftMode(): Promise<{
+    isEnabled: boolean;
+    enable(): void;
+    disable(): void;
+  }>;
   export function cookies(): Promise<{
     get(name: string): { value: string } | undefined;
   }>;