fontdue-js 3.0.6 → 3.2.0

package/dist/hooks/useFeatureTesterAutofit.d.ts

@@ -0,0 +1,17 @@
+export interface UseFeatureTesterAutofitProps {
+    enabled: boolean;
+    text: string;
+    fontFamily: string | null;
+    feature: string;
+    fontSize: number;
+    min?: number;
+    max?: number;
+    letterSpacing?: number;
+    fontVariationSettings?: string;
+    padding?: number;
+}
+export interface UseFeatureTesterAutofitResult {
+    ref: React.RefObject<HTMLDivElement | null>;
+    fontSize: number;
+}
+export default function useFeatureTesterAutofit({ enabled, text, fontFamily, feature, fontSize, min, max, letterSpacing, fontVariationSettings, padding, }: UseFeatureTesterAutofitProps): UseFeatureTesterAutofitResult;

package/dist/hooks/useFeatureTesterAutofit.js

@@ -0,0 +1,106 @@
+import { useRef, useState, useLayoutEffect } from 'react';
+import useResizeObserver from './useResizeObserver.js';
+
+// Autofit for the Feature Tester. Unlike the plain type-tester autofit, the
+// rendered width depends on the toggle state — an alternate glyph is wider or
+// narrower, a ligature collapses, a fraction shrinks. So we measure the sample
+// in BOTH states (feature off and on) and size to fit the WIDER one. The size
+// is then fixed across toggles, so the tester never reflows or overflows when
+// the feature is switched.
+//
+// Measurement must use the DOM (not canvas): canvas `measureText` can't apply
+// `font-feature-settings`, which is exactly the thing that changes the width.
+// Measuring the whole string with the feature applied is exact here, not an
+// over-estimate: a character the feature doesn't touch renders identically
+// whether the feature is on or off, so the two measurements are precisely the
+// tester's two real states.
+
+const REF_SIZE = 100;
+let measureEl = null;
+function getMeasureElement() {
+  if (!measureEl) {
+    measureEl = document.createElement('span');
+    measureEl.style.position = 'absolute';
+    measureEl.style.top = '-9999px';
+    measureEl.style.left = '-9999px';
+    measureEl.style.whiteSpace = 'pre';
+    measureEl.style.visibility = 'hidden';
+    document.body.appendChild(measureEl);
+  }
+  return measureEl;
+}
+function measure(text, fontFamily, letterSpacing, fontFeatureSettings, fontVariationSettings) {
+  const el = getMeasureElement();
+  el.style.fontFamily = fontFamily;
+  el.style.fontSize = `${REF_SIZE}px`;
+  el.style.letterSpacing = `${letterSpacing}em`;
+  el.style.fontFeatureSettings = fontFeatureSettings;
+  el.style.fontVariationSettings = fontVariationSettings;
+  el.textContent = text;
+  return el.getBoundingClientRect().width;
+}
+export default function useFeatureTesterAutofit(_ref) {
+  let {
+    enabled,
+    text,
+    fontFamily,
+    feature,
+    fontSize,
+    min = 8,
+    max = 999,
+    letterSpacing = 0,
+    fontVariationSettings = '',
+    padding = 0
+  } = _ref;
+  const ref = useRef(null);
+  const [size, setSize] = useState(fontSize);
+  const [containerWidth, setContainerWidth] = useState(0);
+  const [fontVersion, setFontVersion] = useState(0);
+  useResizeObserver(ref, entry => setContainerWidth(entry.contentRect.width));
+
+  // Re-measure once the webfont is available (measuring the fallback would size
+  // to the wrong metrics). The font is often already cached — other cards on the
+  // page load the same family — so `document.fonts.load` can resolve in a
+  // microtask *before* a freshly-measured element reflects the loaded font in
+  // layout. Re-measuring on the next animation frame, when layout is font-ready,
+  // avoids sizing to a stale fallback measurement that then never gets corrected.
+  // Re-measure until the sizing lands on the real webfont metrics. A fresh DOM
+  // measurement can lag the font becoming available — the family is often
+  // already cached (other cards on the page load it), so `fonts.load`/
+  // `fonts.ready` can settle a frame or two before a measured element actually
+  // reflects it. Sizing to that stale fallback measurement would then stick.
+  // Re-measuring across a short schedule lets the size settle onto the real
+  // metrics whenever they land; the extra `fonts.ready` bump covers slow loads
+  // beyond the schedule.
+  useLayoutEffect(() => {
+    if (!enabled || !fontFamily) return;
+    let cancelled = false;
+    const bump = () => {
+      if (!cancelled) setFontVersion(v => v + 1);
+    };
+    const timers = [0, 80, 200, 500, 1000].map(ms => window.setTimeout(bump, ms));
+    document.fonts.ready.then(bump);
+    return () => {
+      cancelled = true;
+      timers.forEach(clearTimeout);
+    };
+  }, [enabled, fontFamily]);
+  useLayoutEffect(() => {
+    if (!enabled || !fontFamily) return;
+    const available = containerWidth - padding;
+    if (available <= 0 || !text) return;
+    const off = `"${feature}" 0`;
+    const on = `"${feature}" 1`;
+    // Widest line across both states — samples can carry authored newlines.
+    const refWidth = Math.max(...text.split('\n').flatMap(line => [measure(line, fontFamily, letterSpacing, off, fontVariationSettings), measure(line, fontFamily, letterSpacing, on, fontVariationSettings)]));
+    if (refWidth <= 0) return;
+
+    // Width scales linearly with font-size; floor to avoid a sub-pixel wrap.
+    const next = Math.min(Math.max(min, Math.floor(available / (refWidth / REF_SIZE))), max);
+    setSize(next);
+  }, [enabled, text, fontFamily, feature, letterSpacing, fontVariationSettings, containerWidth, min, max, padding, fontVersion]);
+  return {
+    ref,
+    fontSize: enabled ? size : fontSize
+  };
+}

package/dist/next/index.d.ts

@@ -1 +1,3 @@
 export { __prepareFontdueRender, type FontdueEndpoint } from './tenant.js';
+import { nodeAccessHeaders } from './tenant.js';
+export { nodeAccessHeaders };

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
@@ -15,4 +16,19 @@
 // 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';
+export { __prepareFontdueRender } from './tenant.js';
+import { registerNodeAccessRecovery } from '../relay/serverConfig.js';
+import { nodeAccessHeaders } from './tenant.js';
+
+// Wire up automatic node-access recovery: when a server fetch comes back
+// `password_protected`, createFontdueFetch calls this to read the visitor's
+// node-access cookie and (if they've unlocked the collection) fold the token
+// into the per-render config + retry — so the page fetch and the embedded server
+// components' preloads resolve, with no per-fetch plumbing in the app. Importing
+// this entry (the next-template does, via __prepareFontdueRender) registers it.
+registerNodeAccessRecovery(() => nodeAccessHeaders());
+
+// Escape hatch (rarely needed now recovery is automatic): the visitor's
+// per-collection node-access header for this request, or {} when none. See the
+// password-protected-collections guide.
+export { nodeAccessHeaders };

package/dist/next/registerSingleTenantResolver.js

@@ -15,7 +15,19 @@
 // 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';
+import { registerAmbientConfigResolver, registerNodeAccessRecovery } from '../relay/serverConfig.js';
+
+// Automatic node-access recovery for single-tenant Next apps (the same hook the
+// multi-tenant entry registers). createFontdueFetch calls this when a fetch
+// comes back `password_protected`; it reads the visitor's node-access cookie via
+// Next's request APIs. Lazy-imported, for the same reason as the resolver below:
+// keep next/headers off this module's static graph.
+registerNodeAccessRecovery(async () => {
+  const {
+    nodeAccessHeaders
+  } = await import('./tenant.js');
+  return nodeAccessHeaders();
+});
 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

package/dist/next/tenant.d.ts

@@ -23,4 +23,5 @@ interface RenderProps {
 }
 export declare function buildRenderConfig(domain: string): Promise<FontdueServerConfig>;
 export declare function __prepareFontdueRender(props: RenderProps): Promise<FontdueEndpoint>;
+export declare function nodeAccessHeaders(): Promise<Record<string, string>>;
 export {};

package/dist/next/tenant.js

@@ -29,6 +29,7 @@ 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';
+import { NODE_ACCESS_COOKIE, NODE_ACCESS_HEADER } from '../nodeAccess.js';
 export const isMultiTenant = process.env.FONTDUE_MULTI_TENANT === '1';
 export const singleTenantUrl = process.env.NEXT_PUBLIC_FONTDUE_URL;
 const internalOrigin = process.env.FONTDUE_ORIGIN;
@@ -155,6 +156,61 @@ export async function __prepareFontdueRender(props) {
   return endpointForDomain(domain);
 }
 
+// The visitor's per-collection node-access header for the current request, or {}
+// when they haven't unlocked anything. Reads the first-party cookie the password
+// form set and returns it as `{ 'fontdue-node-access': <tokens> }`, ready to
+// spread into a GraphQL fetch's headers so the unlocked collection resolves.
+//
+// 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 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
+    } : {};
+  } catch (error) {
+    unstable_rethrow(error);
+    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().
 // isEnabled is static-safe (it returns false during static generation and only
@@ -182,9 +238,9 @@ export async function __prepareFontdueRender(props) {
 //      so unstable_rethrow is a no-op and we fall through to "not previewing".
 async function readPreviewHeaders() {
   try {
-    var _await$cookies$get;
+    var _await$cookies$get2;
     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;
+    const token = (_await$cookies$get2 = (await cookies()).get(PREVIEW_TOKEN_COOKIE)) === null || _await$cookies$get2 === void 0 ? void 0 : _await$cookies$get2.value;
     return token ? previewAuthHeaders(token) : undefined;
   } catch (error) {
     unstable_rethrow(error);

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/nodeAccess.d.ts

@@ -0,0 +1,18 @@
+export declare const NODE_ACCESS_COOKIE = "fontdue_node_access";
+export declare const NODE_ACCESS_HEADER = "fontdue-node-access";
+/** The node-access cookie value from a Cookie header string, or undefined. */
+export declare function readNodeAccessCookie(cookieHeader: string | null | undefined): string | undefined;
+/**
+ * The node-access forwarding header for a Cookie header string, or {} when the
+ * cookie is absent. Spread into a server-side GraphQL fetch's headers so a
+ * collection the visitor unlocked resolves for them. Returns {} for public
+ * (no-cookie) requests, leaving them untouched and cacheable.
+ */
+export declare function nodeAccessHeadersFromCookie(cookieHeader: string | null | undefined): Record<string, string>;
+/**
+ * Remember a freshly minted access token in the browser's node-access cookie,
+ * preserving any collections already unlocked. First-party and JS-readable on
+ * purpose (see the module note); SameSite=Lax so it rides top-level navigations,
+ * Secure only on https so it still persists in local dev. No-op off the browser.
+ */
+export declare function rememberNodeAccessToken(token: string | null | undefined): void;

package/dist/nodeAccess.js

@@ -0,0 +1,84 @@
+// Per-collection node-access contract.
+//
+// When a visitor unlocks a password-protected collection (the `accessNode`
+// mutation), the server returns a signed token. The browser remembers it in a
+// first-party cookie, and a server-rendered storefront forwards that cookie to
+// GraphQL as a request header so the collection keeps resolving for this visitor.
+//
+// This mirrors the admin-preview token contract (see ./preview/constants), with
+// one deliberate difference: the node-access token is low sensitivity — it only
+// re-grants access the visitor already earned by entering the password — so it is
+// a plain, JS-readable first-party cookie the form sets directly in the browser,
+// not an httpOnly cookie brokered through a server route. That keeps the
+// template surface tiny: no `/api/...` route to mount, just the form plus the
+// transport every framework already runs for preview.
+//
+// Kept free of Web/Node APIs (only `document`, behind a guard) so it can be
+// imported from both server transport and the client component.
+
+// First-party cookie the browser carries after unlocking. Value is a
+// comma-separated list of signed tokens, one per unlocked collection.
+export const NODE_ACCESS_COOKIE = 'fontdue_node_access';
+
+// Request header a server-rendered storefront forwards the cookie value as, read
+// back by the Fontdue GraphQL server (see FontageWeb.Schema.Context).
+export const NODE_ACCESS_HEADER = 'fontdue-node-access';
+
+// ~30 days, matching the token's `max_age` on the server (Fontage.Token
+// `:node_access`). The cookie and the token expire together.
+const NODE_ACCESS_MAX_AGE_SECONDS = 60 * 60 * 24 * 30;
+
+// Cap on how many unlock tokens the cookie carries. The value is a
+// comma-separated list of ~150-byte signed tokens, so an unbounded list would
+// eventually pass the browser's ~4 KB per-cookie limit and be dropped whole —
+// silently losing every unlock. We keep the most recent few (oldest are also
+// the closest to their 30-day expiry, so the server would drop them anyway) and
+// evict from the front. A visitor unlocking more than this many collections is
+// well outside the intended "share a handful of drafts" use.
+const MAX_NODE_ACCESS_TOKENS = 16;
+
+/** The node-access cookie value from a Cookie header string, or undefined. */
+export function readNodeAccessCookie(cookieHeader) {
+  if (!cookieHeader) return undefined;
+  for (const part of cookieHeader.split(';')) {
+    const idx = part.indexOf('=');
+    if (idx === -1) continue;
+    if (part.slice(0, idx).trim() !== NODE_ACCESS_COOKIE) continue;
+    const value = part.slice(idx + 1).trim();
+    return value === '' ? undefined : value;
+  }
+  return undefined;
+}
+
+/**
+ * The node-access forwarding header for a Cookie header string, or {} when the
+ * cookie is absent. Spread into a server-side GraphQL fetch's headers so a
+ * collection the visitor unlocked resolves for them. Returns {} for public
+ * (no-cookie) requests, leaving them untouched and cacheable.
+ */
+export function nodeAccessHeadersFromCookie(cookieHeader) {
+  const value = readNodeAccessCookie(cookieHeader);
+  return value ? {
+    [NODE_ACCESS_HEADER]: value
+  } : {};
+}
+
+/**
+ * Remember a freshly minted access token in the browser's node-access cookie,
+ * preserving any collections already unlocked. First-party and JS-readable on
+ * purpose (see the module note); SameSite=Lax so it rides top-level navigations,
+ * Secure only on https so it still persists in local dev. No-op off the browser.
+ */
+export function rememberNodeAccessToken(token) {
+  if (typeof document === 'undefined' || !token) return;
+  const existing = readNodeAccessCookie(document.cookie);
+  const tokens = existing ? existing.split(',').filter(Boolean) : [];
+  if (!tokens.includes(token)) tokens.push(token);
+  // Keep the list bounded so it can't grow past the browser's cookie-size limit
+  // and get dropped wholesale; the newest unlock is always retained.
+  if (tokens.length > MAX_NODE_ACCESS_TOKENS) {
+    tokens.splice(0, tokens.length - MAX_NODE_ACCESS_TOKENS);
+  }
+  const secure = typeof location !== 'undefined' && location.protocol === 'https:' ? '; Secure' : '';
+  document.cookie = `${NODE_ACCESS_COOKIE}=${tokens.join(',')}; Path=/; SameSite=Lax${secure}; Max-Age=${NODE_ACCESS_MAX_AGE_SECONDS}`;
+}

package/dist/preview/server.d.ts

@@ -1,20 +1 @@
-/** Whether the current async context is an admin preview. */
-export declare function isPreviewing(): boolean;
-/**
- * Preview auth headers for the current async context, or {} when not previewing.
- * Spread into a hand-rolled fetch you make inside `runWithPreview`; the
- * fontdue-js fetch/preload helpers pick these up automatically and don't need
- * it.
- */
-export declare function ambientPreviewHeaders(): Record<string, string>;
-/**
- * Run `next` (your framework's render/loader chain) with the request's preview
- * token in ambient context, then return its Response. When the request is
- * previewing, the response's cache headers are rewritten so it is never stored
- * in a shared/CDN cache. Public (no-token) requests pass through untouched and
- * stay fully cacheable.
- *
- * `next` is your middleware's continuation — `next` in Astro, `next` in a React
- * Router 7 middleware. It must return (a promise of) the Response.
- */
-export declare function runWithPreview(request: Request, next: () => Response | Promise<Response>): Promise<Response>;
+export { runWithPreview, isPreviewing, ambientHeaders as ambientPreviewHeaders, } from '../server/middleware.js';

package/dist/preview/server.js

@@ -1,89 +1,20 @@
-// Ambient (request-scoped) preview for non-RSC server frameworks.
+// Ambient (request-scoped) admin preview for non-RSC server frameworks.
 //
-// fontdue-js/preview gives you the cookie contract and an explicit option:
-// read the token per request and thread `previewAuthHeaders(token)` into every
-// GraphQL fetch and preload helper. That's portable but easy to get wrong — miss
-// one preload and that island silently renders the public view.
+// The ambient-context machinery moved to ../server/middleware, because it is
+// shared by admin preview and the per-collection password unlock (and a
+// storefront usually wants both). This module re-exports the preview-facing
+// pieces so existing `fontdue-js/preview/server` imports keep working:
 //
-// This module removes the threading. `runWithPreview` establishes an
-// AsyncLocalStorage context for the duration of a request; while it's active,
-// every fontdue-js server fetch (createFontdueFetch and all the preload helpers)
-// automatically forwards the admin preview token, with no per-call plumbing —
-// the same ergonomics RSC gets from React.cache, and the same mechanism Next's
-// own headers()/draftMode() use under the hood. Install it once in your
-// framework's middleware:
+//   - runWithPreview — forward only the admin preview token (reveals
+//     unpublished fonts). Mount it in your framework's request middleware.
+//   - isPreviewing / ambientPreviewHeaders — read the current ambient state.
 //
-//   // Astro: src/middleware.ts
-//   export const onRequest = (ctx, next) => runWithPreview(ctx.request, next);
-//
-//   // React Router 7 (root route, with future.v8_middleware):
-//   export const middleware = [({ request }, next) => runWithPreview(request, next)];
-//
-// runWithPreview also binds the cache guarantee to the same call: when a request
-// is previewing, the response is forced out of any shared/CDN cache. Because the
-// context and the no-cache rule are set in one place, you can't be ambiently
-// previewing without the response being uncacheable — so an admin render is never
-// served to the public.
-//
-// Requirements & fallback: AsyncLocalStorage must propagate from the install
-// point into the render. That holds for in-process middleware — Node (Netlify
-// Functions, the default SSR target), Deno (Netlify Edge), Bun. It does NOT hold
-// when middleware runs in a separate runtime from the render (e.g. Astro with
-// `edgeMiddleware: true`, where locals cross the boundary as a serialized
-// header). In that case fall back to the explicit path: read the token in
-// middleware and thread `previewAuthHeaders(token)` via the `headers` option on
-// fetches/preloads. The explicit `headers` option always overrides the ambient
-// context, so the two compose.
-
-import { AsyncLocalStorage } from 'node:async_hooks';
-import { readPreviewToken, previewAuthHeaders } from './index.js';
-import { registerAmbientConfigResolver } from '../relay/serverConfig.js';
-const previewStore = new AsyncLocalStorage();
-
-// Feed the ambient token into fontdue-js's server config resolution. Returns
-// undefined outside a preview context, so non-preview requests are untouched.
-registerAmbientConfigResolver(() => {
-  const store = previewStore.getStore();
-  return store ? {
-    headers: store.headers
-  } : undefined;
-});
-
-/** Whether the current async context is an admin preview. */
-export function isPreviewing() {
-  return previewStore.getStore() != null;
-}
-
-/**
- * Preview auth headers for the current async context, or {} when not previewing.
- * Spread into a hand-rolled fetch you make inside `runWithPreview`; the
- * fontdue-js fetch/preload helpers pick these up automatically and don't need
- * it.
- */
-export function ambientPreviewHeaders() {
-  var _previewStore$getStor;
-  return ((_previewStore$getStor = previewStore.getStore()) === null || _previewStore$getStor === void 0 ? void 0 : _previewStore$getStor.headers) ?? {};
-}
-const NO_STORE = 'private, no-store';
+// To also forward a visitor's password-unlock token, mount the precomposed
+// `runWithFontdue` from `fontdue-js/server/middleware` in place of
+// runWithPreview (or compose runWithPreview with runWithNodeAccess yourself).
+// See the password-protected collections guide.
 
-/**
- * Run `next` (your framework's render/loader chain) with the request's preview
- * token in ambient context, then return its Response. When the request is
- * previewing, the response's cache headers are rewritten so it is never stored
- * in a shared/CDN cache. Public (no-token) requests pass through untouched and
- * stay fully cacheable.
- *
- * `next` is your middleware's continuation — `next` in Astro, `next` in a React
- * Router 7 middleware. It must return (a promise of) the Response.
- */
-export async function runWithPreview(request, next) {
-  const token = readPreviewToken(request.headers.get('cookie'));
-  if (!token) return next();
-  const response = await previewStore.run({
-    headers: previewAuthHeaders(token)
-  }, next);
-  response.headers.set('Cache-Control', NO_STORE);
-  response.headers.delete('Netlify-CDN-Cache-Control');
-  response.headers.delete('CDN-Cache-Control');
-  return response;
-}
+export { runWithPreview, isPreviewing,
+// Historical name kept for back-compat; returns the full ambient header set
+// (preview and/or node-access), so it works under runWithFontdue too.
+ambientHeaders as ambientPreviewHeaders } from '../server/middleware.js';

package/dist/relay/environment.js

@@ -2,12 +2,13 @@ import { Environment, Network, RecordSource, Store, QueryResponseCache } from 'r
 import { handlePossibleCorsError } from '../corsError.js';
 import { resolveFontdueServerConfig } from './serverConfig.js';
 import { PREVIEW_HEADER, hasPreviewMarkerCookie } from '../preview/constants.js';
+import { NODE_ACCESS_HEADER } from '../nodeAccess.js';
 
 // `__FONTDUE_JS_VERSION__` is replaced by an inline babel plugin
 // (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.0.6";
+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
@@ -91,6 +92,11 @@ export function createNetworkFetch(options) {
     const previewing = IS_SERVER ? headers.authorization != null || headers.Authorization != null : hasPreviewMarkerCookie();
     headers[PREVIEW_HEADER] = previewing ? 'true' : 'false';
 
+    // A forwarded node-access token (a collection this visitor unlocked) makes
+    // the server response per-visitor just like preview, so it must never be
+    // written to or served from the shared data cache.
+    const perVisitor = previewing || IS_SERVER && headers[NODE_ACCESS_HEADER] != null;
+
     // Public server fetches are all site content (per-session data is fetched
     // client-side only), so opt them into Next's data cache — without this,
     // Next 15 treats them as no-store and silently makes every page fully
@@ -113,7 +119,7 @@ export function createNetworkFetch(options) {
         variables
       })
     };
-    if (IS_SERVER && (previewing || !cacheInProduction())) {
+    if (IS_SERVER && (perVisitor || !cacheInProduction())) {
       init.cache = 'no-store';
     } else if (IS_SERVER) {
       init.cache = 'force-cache';

package/dist/relay/serverConfig.d.ts

@@ -8,7 +8,10 @@ export interface FontdueServerConfig {
 }
 type MaybePromise<T> = T | Promise<T>;
 type AmbientConfigResolver = () => MaybePromise<FontdueServerConfig | undefined>;
+type NodeAccessRecovery = () => MaybePromise<Record<string, string>>;
 export declare function setFontdueServerConfig(config: FontdueServerConfig): void;
 export declare function registerAmbientConfigResolver(resolver: AmbientConfigResolver): void;
+export declare function registerNodeAccessRecovery(recovery: NodeAccessRecovery): void;
+export declare function resolveNodeAccessRecovery(): NodeAccessRecovery | undefined;
 export declare function resolveFontdueServerConfig(): Promise<FontdueServerConfig | undefined>;
 export {};