@certrev/cert-block 1.2.0-canary.7 → 1.2.0

package/src/builder/cert-review-card.tsx

@@ -23,18 +23,29 @@ import { Suspense } from 'react'
 import { memoToggleFor, toggleMemo } from '../components/memo-toggle.js'
 import { type CertBlockMode, renderCertBlock } from '../components/render-cert-block.js'
 import { CERT_STRINGS_VERSION, type ResolvedBlockTheme } from '../components/render-def.js'
-import { READER_CSS } from '../reader/reader-css.generated.js'
+import { type CertPayload, renderVerdict } from '../contract/kernel.js'
 import {
 	type DesignPin,
 	getVerifiedDelivery,
 	parseDesignPin,
-	peekVerifiedDelivery,
+	readVerifiedDelivery,
 	type VerifiedDelivery,
 } from '../verify/get-verified-delivery.js'
-import type { BuilderCertChromeData } from './cert-chrome-data.js'
+import { CARD_READER_CSS } from './card-reader-css.js'
+import type { BuilderCertChromeData, CertChromeRenderDef } from './cert-chrome-data.js'
 import { BUILDER_CERT_CHROME_KEYS } from './cert-chrome-data.js'
 import { cardDeliveryRuntime } from './delivery-runtime.js'
 import { envelopeCardHtml, envelopeCardInput, isReaderFaceDef } from './envelope-face.js'
+import {
+	type FallbackFace,
+	pageHoldsServerHtml,
+	pageRecordFor,
+	SEED_ATTRIBUTE,
+	seedFor,
+	serializeFallback,
+	serializeSeed,
+	withoutPhotos,
+} from './ssr-seed.js'
 
 /**
  * The canonical Builder block name. A brand's registration + the portal
@@ -75,6 +86,14 @@ export interface CertReviewCardProps extends Partial<BuilderCertChromeData> {
 		readonly content?: { readonly id?: unknown } | null
 		readonly context?: { readonly certrevDesignPin?: unknown } | null
 	} | null
+	/**
+	 * 1.2.0: opt in to a Delivery read FROM THE BROWSER for a card the server did not render (a client-side navigation,
+	 * Builder's editor). Off by default: the card then never makes a request from the browser, so a brand's
+	 * Content-Security-Policy needs no CertREV origin, and such a card paints the block's own options face. Turning it
+	 * on needs the Delivery API's origin in the page's `connect-src`. Not a Builder input: a brand sets it in code, on
+	 * a wrapper of this component.
+	 */
+	clientRead?: boolean
 }
 
 /**
@@ -139,7 +158,7 @@ export function acceptedDeliveryMarker(value: unknown): { readonly baseUrl: stri
 /**
  * Suspend on a Delivery read. React 19 gets `use` with ONE promise per placement while it is in
  * flight; React 18 (no `use`) gets the promise thrown, the Suspense protocol it supports. Either
- * way the retry finds the settled read in the cache through `peekVerifiedDelivery`, so it never
+ * way the retry finds the settled read in the cache through `readVerifiedDelivery`, so it never
  * suspends on a second promise.
  */
 const inflightReads = new Map<string, Promise<VerifiedDelivery>>()
@@ -202,8 +221,13 @@ function EnvelopeFace(props: {
 	readonly html: string
 	readonly defVersion: number | undefined
 	readonly reader?: boolean
+	/** The envelope seed (`ssr-seed.ts`): what a browser hydrating this face paints from, with no read of its own. */
+	readonly seed: string
+	/** 1.2.0, reader faces: told which person's photo the browser could not load (`ReaderEnvelopeFace`). */
+	readonly onBrokenPhoto?: (person: PhotoPerson) => void
 }) {
 	const ref = React.useRef<HTMLDivElement>(null)
+	const { onBrokenPhoto } = props
 	React.useEffect(() => {
 		const el = ref.current
 		if (!el) return
@@ -214,6 +238,23 @@ function EnvelopeFace(props: {
 		el.addEventListener('click', onClick)
 		return () => el.removeEventListener('click', onClick)
 	}, [])
+	React.useEffect(() => {
+		const el = ref.current
+		if (!el || !onBrokenPhoto) return
+		// A photo that failed before this effect ran (during hydration) has no error event left to hear.
+		for (const img of Array.from(el.querySelectorAll('.certrev-r-face > img'))) {
+			if (img instanceof HTMLImageElement && img.complete && img.naturalWidth === 0) onBrokenPhoto(photoPerson(img))
+		}
+		// An image's `error` does not bubble, so it is heard in the capture phase.
+		const onError = (e: Event) => {
+			const img = e.target
+			if (img instanceof HTMLImageElement && img.parentElement?.classList.contains('certrev-r-face')) {
+				onBrokenPhoto(photoPerson(img))
+			}
+		}
+		el.addEventListener('error', onError, true)
+		return () => el.removeEventListener('error', onError, true)
+	}, [onBrokenPhoto])
 	return withSidebarFlow(
 		props.reader,
 		<div
@@ -224,6 +265,7 @@ function EnvelopeFace(props: {
 			data-certrev-delivery=""
 			data-certrev-strings-version={CERT_STRINGS_VERSION}
 			data-certrev-def-version={props.defVersion}
+			{...{ [SEED_ATTRIBUTE]: props.seed }}
 			{...(props.reader ? { 'data-certrev-face': 'reader', style: { display: 'flow-root' } } : {})}
 			// biome-ignore lint/security/noDangerouslySetInnerHtml: renderCertBlock is the escaping-safe SSR string renderer
 			dangerouslySetInnerHTML={{ __html: props.html }}
@@ -231,17 +273,243 @@ function EnvelopeFace(props: {
 	)
 }
 
-function EnvelopeCertReviewCard(props: {
+type PhotoPerson = 'expert' | 'author'
+
+/** The reader face paints the author's avatar small (`.certrev-r-face.sm`); every other avatar is the expert's. */
+function photoPerson(img: HTMLImageElement): PhotoPerson {
+	return img.parentElement?.classList.contains('sm') ? 'author' : 'expert'
+}
+
+interface EnvelopeCardProps {
 	readonly baseUrl: string
 	readonly externalId: string
 	readonly mode: unknown
 	readonly part: unknown
 	readonly design?: DesignPin
+	/** The block's own options: the face painted when CertREV could not be reached, or with no server render. */
+	readonly block: CertReviewCardProps
+	readonly clientRead: boolean
+}
+
+/**
+ * 1.2.0-canary.5: a pinned read paints only the design it pinned, a reader def at exactly that version. A def served
+ * for anything else (none, another face, another version) paints nothing, never the live design in its place.
+ */
+function pinnedDefHolds(design: DesignPin | undefined, renderDef: CertChromeRenderDef | null): boolean {
+	return !design || (isReaderFaceDef(renderDef) && renderDef?.v === design.version)
+}
+
+/**
+ * 1.2.0: the reader face, repainted with the reviewer's (or the author's) initials when the browser cannot load their
+ * photo: a brand's CSP `img-src` that does not name the photo's host, a 404. The first paint is the server's, photo
+ * included, so hydration matches; a photo that fails is dropped from the payload this face paints
+ * (`withoutPhotos`), and the face's own avatar rule paints the initials in its place. The seed is not touched.
+ */
+function ReaderEnvelopeFace(props: {
+	readonly payload: CertPayload
+	readonly renderDef: CertChromeRenderDef
+	readonly card: EnvelopeCardProps
+	readonly seed: string
 }) {
+	const [broken, setBroken] = React.useState<readonly PhotoPerson[]>([])
+	const onBrokenPhoto = React.useCallback(
+		(person: PhotoPerson) => setBroken((was) => (was.includes(person) ? was : [...was, person])),
+		[],
+	)
+	const payload = broken.length > 0 ? withoutPhotos(props.payload, broken) : props.payload
+	const reader = envelopeCardHtml(payload.content, props.renderDef, {
+		mode: props.card.mode,
+		part: props.card.part,
+		certId: payload.certId,
+	})
+	if (!reader) return null
+	return (
+		<EnvelopeFace
+			reader
+			// The stylesheet rides inside the face, once per card: the portal's reader CSS less its remote font
+			// faces (card-reader-css.ts), so the card asks the page's CSP for nothing.
+			html={`<style data-certrev-reader-css>${CARD_READER_CSS}</style>${reader}`}
+			defVersion={props.renderDef.v}
+			seed={props.seed}
+			onBrokenPhoto={onBrokenPhoto}
+		/>
+	)
+}
+
+/** Paint a verified payload with its def; null when the def and content give no face. */
+function paintEnvelope(
+	payload: CertPayload,
+	renderDef: CertChromeRenderDef | null,
+	props: EnvelopeCardProps,
+	seed: string,
+): React.ReactElement | null {
+	if (!pinnedDefHolds(props.design, renderDef)) return null
+	const defVersion = renderDef ? renderDef.v : undefined
+	// The reader face is opt-in by the def's own `face` and is chosen HERE and nowhere else on this path; every other
+	// def (no face, an unknown face) falls through to the legacy lines below, untouched since 1.1.1.
+	if (isReaderFaceDef(renderDef) && renderDef) {
+		// Without a face there is nothing to repaint; checked here so the null stays this function's answer.
+		if (!envelopeCardHtml(payload.content, renderDef, { mode: props.mode, part: props.part, certId: payload.certId }))
+			return null
+		return <ReaderEnvelopeFace payload={payload} renderDef={renderDef} card={props} seed={seed} />
+	}
+	const input = envelopeCardInput(payload.content, renderDef, { mode: props.mode, part: props.part })
+	if (!input) return null
+	return <EnvelopeFace html={renderCertBlock(input)} defVersion={defVersion} seed={seed} />
+}
+
+const FALLBACK_LAYOUTS: readonly string[] = ['banner', 'sidebar', 'floating']
+
+/**
+ * The options face a block with the delivery marker paints in place of the envelope (1.2.0), or null. Its placement is
+ * the block's own `mode`, else its def's layout, as the envelope face's is, else the banner bridge. A pinned card (the
+ * canary replica) paints it too, so the replica shows what a brand's page shows when CertREV is not reached; its
+ * record names the pin and says `'options'`, so a capture can never take it for the pinned design.
+ */
+function fallbackFace(props: EnvelopeCardProps): string | null {
+	const { block } = props
+	const layout = block.renderDef?.layout
+	const mode =
+		typeof block.mode === 'string' && FALLBACK_LAYOUTS.includes(block.mode)
+			? block.mode
+			: typeof layout === 'string' && FALLBACK_LAYOUTS.includes(layout)
+				? (layout as CertBlockMode)
+				: undefined
+	return optionsFaceHtml(block, mode)
+}
+
+/** The block's options face, stamped with a fallback record when the server wrote one (`ssr-seed.ts`). */
+function OptionsFace(props: { readonly block: CertReviewCardProps; readonly html: string; readonly record?: string }) {
+	return (
+		<div
+			data-certrev-cert-chrome=""
+			// The two provenance stamps the crawl monitor reads — emitted ONLY when the delivery
+			// carried the right type, so a mistyped option leaves the attribute off instead of
+			// stamping "[object Object]" as a version.
+			data-certrev-strings-version={optionalText(props.block.stringsVersion)}
+			data-certrev-def-version={typeof props.block.renderDef?.v === 'number' ? props.block.renderDef.v : undefined}
+			{...(props.record === undefined ? {} : { [SEED_ATTRIBUTE]: props.record })}
+			// biome-ignore lint/security/noDangerouslySetInnerHtml: renderCertBlock is the escaping-safe SSR string renderer
+			dangerouslySetInnerHTML={{ __html: props.html }}
+		/>
+	)
+}
+
+/** Where the server painted no face, an empty hidden element carries the record that says so. */
+function NoFace(props: { readonly record: string }) {
+	return <div hidden {...{ [SEED_ATTRIBUTE]: props.record }} />
+}
+
+/** What a card with no verified envelope paints: the options face when CertREV was not reached, else nothing. */
+function settleWithoutEnvelope(props: EnvelopeCardProps, unreachable: boolean): React.ReactElement {
+	const html = unreachable ? fallbackFace(props) : null
+	const face: FallbackFace = html === null ? 'none' : 'options'
+	const record = serializeFallback({
+		baseUrl: props.baseUrl,
+		externalId: props.externalId,
+		...(props.design ? { design: props.design } : {}),
+		face,
+	})
+	return html === null ? <NoFace record={record} /> : <OptionsFace block={props.block} html={html} record={record} />
+}
+
+const subscribeNever = () => () => {}
+
+/**
+ * True on a server and while a browser hydrates server HTML; false once the client has committed, and from the first
+ * render of a card mounted on the client. React re-renders a hydrated card when this flips, so the card can paint
+ * the server's tree first (no mismatch) and judge it at the browser's clock right after.
+ *
+ * It is true in BOTH of the first two cases and React gives a component no public way to tell them apart, so the card
+ * does not ask React: see `EnvelopeCertReviewCard`.
+ */
+function useHydrating(): boolean {
+	return React.useSyncExternalStore(
+		subscribeNever,
+		() => false,
+		() => true,
+	)
+}
+
+/**
+ * 1.2.0: the card never reads the Delivery API from the browser unless the brand opts in (`clientRead`), so a
+ * storefront whose CSP `connect-src` does not name CertREV (e.l.f.'s live policy) never sees a request or a violation
+ * from it, and a page never loses its card for want of one.
+ *
+ *  - Server: read (up to `CARD_DELIVERY_TIMEOUT_MS`, a fresh or stale-while-revalidating cache first), verify and paint
+ *    as through 1.1.1, and write a record of what it painted (`ssr-seed.ts`):
+ *     - a verified envelope: its face and the envelope seed (less the fields the def hides, and with no signature if
+ *       it hid any);
+ *     - CertREV not reached (a timeout, a network error, a 5xx, a body that is not JSON): the block's own options face,
+ *       as 0.5.x painted it, and an `'options'` record (a pinned card too: the record names its pin);
+ *     - a definitive no (revoked, expired, unverifiable, for another entry, not found): nothing, and a `'none'` record
+ *       on an empty hidden element.
+ *  - Browser, the page carries this placement's record: paint what it says. A seed paints its envelope; while
+ *    hydrating the server's verdict stands (the tree is the server's, byte for byte), and once hydrated the lifecycle
+ *    and subject are judged at the browser's clock, so a card that expired since the server render is taken down. An
+ *    `'options'` record paints the options face, a `'none'` record nothing. This holds when React renders the card
+ *    again on the client after a hydration error elsewhere on the page: the record is still in the document (or in
+ *    the page's memory of it), so the browser repaints the server's answer and reads nothing.
+ *  - Browser, hydrating with no record: server HTML from before 1.2.0 painted nothing here, so nothing.
+ *  - Browser, a card mounted on the client with no record (a client-side navigation to an article this page never
+ *    server-rendered, Builder's editor): the block's options face, pinned or not. With `clientRead`, instead, the
+ *    one read, settled exactly as on the server.
+ *
+ * WHICH OF THE TWO FIRST CASES THIS RENDER IS (server or browser) is decided from what the render can observe, with
+ * no switch a test could set. A server render and a hydration are both "hydrating" to React and both see a `document`
+ * under jsdom, so `typeof document` alone calls a jsdom server render a browser, which is what 1.2.0-canary.5 got
+ * wrong (its SSR painted `<!--$--><!--/$-->`). What differs between them is the one thing a hydration has and a server
+ * render cannot: server-rendered HTML IN the document, in front of it. So:
+ *  1. no `document`: a server (every real server render: Node, Workers, Oxygen, Bun);
+ *  2. not hydrating: a browser (a client mount, or a card past its hydration);
+ *  3. hydrating with a `document`: a browser only when the live document holds this placement's record, or any React
+ *     Suspense boundary marker (`pageHoldsServerHtml`; the card's own Suspense leaves one). Otherwise it is a server
+ *     render running beside a `document` (jsdom, a DOM shim): it reads and records as a server does, and never consults
+ *     a record or the page's memory, so a long-lived shim process cannot paint one page's record into another's render.
+ * The one case this cannot see is a server render that runs while the document still holds server-rendered React HTML
+ * (a test or shim that hydrates a page and then renders another into the same document without clearing it): that
+ * render is taken for a hydration. Clear the document between pages in such a harness.
+ */
+function EnvelopeCertReviewCard(props: EnvelopeCardProps) {
 	const rt = cardDeliveryRuntime()
-	const { design } = props
+	const hydrating = useHydrating()
+	// Latched at mount: this instance hydrated server HTML (as opposed to a client mount).
+	const [hydratedMount] = React.useState(hydrating)
 	// The clock is read per render, so the lifecycle is judged NOW, not when the envelope was fetched.
 	const context = { platform: 'builder', externalId: props.externalId, now: new Date(rt.now()) }
+	// Hydrating: the live document decides (the memory of an earlier page must not). Past hydration: the memory is the
+	// record the hydration used, which the document still carries as well.
+	const fromPage =
+		typeof document === 'undefined'
+			? undefined
+			: pageRecordFor(props.baseUrl, props.externalId, props.design, { live: hydrating })
+	const inBrowser = typeof document !== 'undefined' && (!hydrating || fromPage !== undefined || pageHoldsServerHtml())
+	if (inBrowser) {
+		if (fromPage && 'seed' in fromPage) {
+			if (!hydrating) {
+				try {
+					if (renderVerdict(fromPage.seed.payload, context).decision !== 'render') return null
+				} catch {
+					return null
+				}
+			}
+			return paintEnvelope(fromPage.seed.payload, fromPage.seed.renderDef, props, fromPage.raw)
+		}
+		if (fromPage) {
+			const html = fromPage.fallback.face === 'options' ? fallbackFace(props) : null
+			return html === null ? (
+				<NoFace record={fromPage.raw} />
+			) : (
+				<OptionsFace block={props.block} html={html} record={fromPage.raw} />
+			)
+		}
+		if (hydratedMount) return null
+		if (!props.clientRead) {
+			const html = fallbackFace(props)
+			return html === null ? null : <OptionsFace block={props.block} html={html} />
+		}
+	}
+	const { design } = props
 	const read = {
 		baseUrl: props.baseUrl,
 		platform: 'builder',
@@ -249,44 +517,26 @@ function EnvelopeCertReviewCard(props: {
 		context,
 		cache: rt.cache,
 		design,
+		resolveKid: rt.resolveKid,
+		fetchImpl: rt.fetchImpl(),
+		timeoutMs: rt.timeoutMs,
 	}
 	const key = design
 		? `${props.baseUrl}|${props.externalId}|design=${design.version}|${design.brand ?? ''}`
 		: `${props.baseUrl}|${props.externalId}`
-	const settled =
-		peekVerifiedDelivery(read) ??
-		suspendOn(key, () =>
-			getVerifiedDelivery({ ...read, resolveKid: rt.resolveKid, fetchImpl: rt.fetchImpl(), timeoutMs: rt.timeoutMs }),
-		)
-	// Revoked, expired, unverifiable, for another entry, or unreachable: nothing at all.
-	if (settled.verdict.decision !== 'render') return null
-	// A pinned read paints only the design it pinned: a reader def at exactly that version. A def the API served for
-	// anything else (none, another face, another version) paints nothing, never the live design in its place.
-	if (design && !(isReaderFaceDef(settled.renderDef) && settled.renderDef?.v === design.version)) return null
-	// The reader face is opt-in by the def's own `face` and is chosen HERE and nowhere else on this path; every other
-	// def (no face, an unknown face) falls through to the legacy lines below, untouched since 1.1.1.
-	if (isReaderFaceDef(settled.renderDef)) {
-		const reader = envelopeCardHtml(settled.verdict.payload.content, settled.renderDef, {
-			mode: props.mode,
-			part: props.part,
-			certId: settled.verdict.payload.certId,
-		})
-		if (!reader) return null
-		return (
-			<EnvelopeFace
-				reader
-				// The stylesheet rides inside the face, once per card; it is the portal's reader CSS byte for byte.
-				html={`<style data-certrev-reader-css>${READER_CSS}</style>${reader}`}
-				defVersion={settled.renderDef ? settled.renderDef.v : undefined}
-			/>
-		)
-	}
-	const input = envelopeCardInput(settled.verdict.payload.content, settled.renderDef, {
-		mode: props.mode,
-		part: props.part,
+	const settled = readVerifiedDelivery(read) ?? suspendOn(key, () => getVerifiedDelivery(read))
+	if (settled.verdict.decision !== 'render') return settleWithoutEnvelope(props, settled.unreachable === true)
+	// The face is painted from the seed's payload (what the def hides is already out of it), so the server's HTML and
+	// the browser's, which paints from the seed, are the same bytes and neither holds a hidden field.
+	const seed = seedFor({
+		baseUrl: props.baseUrl,
+		externalId: props.externalId,
+		design,
+		payload: settled.verdict.payload,
+		signature: settled.signature,
+		renderDef: settled.renderDef,
 	})
-	if (!input) return null
-	return <EnvelopeFace html={renderCertBlock(input)} defVersion={settled.renderDef ? settled.renderDef.v : undefined} />
+	return paintEnvelope(seed.payload, seed.renderDef, props, serializeSeed(seed))
 }
 
 export function CertReviewCard(props: CertReviewCardProps) {
@@ -295,6 +545,8 @@ export function CertReviewCard(props: CertReviewCardProps) {
 	// takes the options path below, unchanged from 1.0.3.
 	// 1.2.0-canary.5: a design pin (CertREV's canary replica only) fails closed. One that cannot be read renders
 	// nothing, and so does one on a block without the delivery marker: the options face is never the pinned design.
+	// 1.2.0: where the envelope cannot be had (CertREV not reached, or no server render and no `clientRead`), a block
+	// with the marker paints this options face too, pinned or not: see `EnvelopeCertReviewCard`.
 	const design = parseDesignPin(props.builderContext?.context?.certrevDesignPin)
 	if (design === 'invalid') return null
 	if (props.delivery != null) {
@@ -309,15 +561,28 @@ export function CertReviewCard(props: CertReviewCardProps) {
 					mode={props.mode}
 					part={props.part}
 					design={design}
+					block={props}
+					clientRead={props.clientRead === true}
 				/>
 			</Suspense>
 		)
 	}
 	if (design) return null
 
+	const html = optionsFaceHtml(props, 'banner')
+	if (html === null) return null // no chrome pre-cert (or an unreadable delivery)
+	return <OptionsFace block={props} html={html} />
+}
+
+/**
+ * The options face's HTML (1.0.3's, unchanged), or null when the block lacks a reviewer or a certificate link. `bridge`
+ * is the placement a block with no `mode` gets: `'banner'` for a block without the delivery marker (the bridge below);
+ * the def's layout for a marked block's fallback (`fallbackFace`).
+ */
+function optionsFaceHtml(props: CertReviewCardProps, bridge: CertBlockMode | undefined): string | null {
 	const reviewerName = text(props.reviewerName)
 	const verifyUrl = text(props.verifyUrl)
-	if (!reviewerName || !verifyUrl) return null // no chrome pre-cert (or an unreadable delivery)
+	if (!reviewerName || !verifyUrl) return null
 
 	// Name-only face when the pair is unreadable, or when the brand set showCredentials:false.
 	const showCred = props.display?.showCredentials !== false
@@ -336,7 +601,7 @@ export function CertReviewCard(props: CertReviewCardProps) {
 			}
 		: undefined
 
-	const html = renderCertBlock({
+	return renderCertBlock({
 		// COMPATIBILITY BRIDGE, NOT THE DESIGN. Delete this fallback once the exporter emits an
 		// explicit `mode` and existing entries have been backfilled; until then it must stay.
 		//
@@ -358,7 +623,7 @@ export function CertReviewCard(props: CertReviewCardProps) {
 		// still fixed: the helper text and the wire type's doc comment no longer name a default,
 		// and this line names one only for input the renderer can no longer distinguish from a
 		// deliberate choice. The exporter writing `mode` is what retires it.
-		mode: props.mode ?? 'banner',
+		mode: props.mode ?? bridge ?? 'banner',
 		theme,
 		// First-class banner memo split — renderCertBlock composes the requested
 		// part directly; no string-splitting. Ignored outside banner mode, and an unrecognised
@@ -385,19 +650,6 @@ export function CertReviewCard(props: CertReviewCardProps) {
 			compensationCue: props.compensationCue === null ? null : undefined,
 		},
 	})
-
-	return (
-		<div
-			data-certrev-cert-chrome=""
-			// The two provenance stamps the crawl monitor reads — emitted ONLY when the delivery
-			// carried the right type, so a mistyped option leaves the attribute off instead of
-			// stamping "[object Object]" as a version.
-			data-certrev-strings-version={optionalText(props.stringsVersion)}
-			data-certrev-def-version={typeof props.renderDef?.v === 'number' ? props.renderDef.v : undefined}
-			// biome-ignore lint/security/noDangerouslySetInnerHtml: renderCertBlock is the escaping-safe SSR string renderer
-			dangerouslySetInnerHTML={{ __html: html }}
-		/>
-	)
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -470,7 +722,7 @@ const WIRE_INPUT_HELPER_TEXT: Partial<Record<(typeof BUILDER_CERT_CHROME_KEYS)[n
 	scopeLine:
 		'System-populated by CertREV. The FTC scope line renders byte-verbatim from a locked constant: editing this text changes nothing on the page.',
 	delivery:
-		'System-populated by CertREV. When set, the card shows the certificate CertREV serves for this entry, verified, and ignores the other fields; if CertREV revokes it or it expires, the card shows nothing. Do not edit.',
+		'System-populated by CertREV. When set, the card shows the certificate CertREV serves for this entry, verified, in place of the other fields; if CertREV revokes it or it expires, the card shows nothing. If CertREV cannot be reached, or the page was not rendered on the server, the card shows the other fields. Do not edit.',
 }
 
 /**

package/src/builder/delivery-runtime.ts

@@ -6,12 +6,25 @@
  * swap the trust root through the published API: the card verifies against the baked
  * `cert-issuer-1` key, the same key the storefront badge bundle ships. The package's own tests
  * reach the setter by relative import to run the real kernel against fixture-signed envelopes.
+ *
+ * 1.2.0: the card's server read waits up to `CARD_DELIVERY_TIMEOUT_MS` (8s, against the
+ * verifier's 3s default), and its cache serves a certificate up to `CARD_DELIVERY_STALE_MS` past
+ * its TTL while one background refresh runs, or while CertREV cannot be reached. A cold or slow
+ * read on a brand's server then misses at most once per placement, and a warm one never waits.
+ * A revocation still lands on the first render after its refresh does. The tests' runtime gets
+ * the same cache shape, so they exercise what production runs.
  */
 
 import type { ResolvePublicKeyByKid } from '../contract/kernel.js'
 import { TtlCache } from '../verify/cache.js'
 import type { CachedDelivery } from '../verify/get-verified-delivery.js'
 import { CERT_ISSUER_KID, CERT_ISSUER_PUBLIC_KEY_PEM } from './issuer-key.js'
+import { forgetPageSeedsForTests } from './ssr-seed.js'
+
+/** The card's server read deadline. A brand's server waits this long once per cold placement. */
+export const CARD_DELIVERY_TIMEOUT_MS = 8_000
+/** How long past its 60s TTL a certificate may still paint while it is refreshed or CertREV is down. */
+export const CARD_DELIVERY_STALE_MS = 300_000
 
 export interface CardDeliveryRuntime {
 	readonly resolveKid: ResolvePublicKeyByKid
@@ -24,12 +37,25 @@ export interface CardDeliveryRuntime {
 const bakedResolveKid: ResolvePublicKeyByKid = (kid) =>
 	kid === CERT_ISSUER_KID ? { format: 'pem', pem: CERT_ISSUER_PUBLIC_KEY_PEM } : null
 
+function newCardCache(now?: () => number): TtlCache<CachedDelivery> {
+	return new TtlCache<CachedDelivery>({
+		ttlMs: 60_000,
+		negativeTtlMs: 5_000,
+		staleMs: CARD_DELIVERY_STALE_MS,
+		// A refresh the host runtime abandoned (workerd cancels a finished request's I/O) never
+		// settles; after the deadline plus a margin, the next render starts a new one.
+		inflightMaxMs: CARD_DELIVERY_TIMEOUT_MS + 2_000,
+		...(now ? { now } : {}),
+	})
+}
+
 function defaultRuntime(): CardDeliveryRuntime {
 	return {
 		resolveKid: bakedResolveKid,
 		fetchImpl: () => globalThis.fetch,
-		cache: new TtlCache<CachedDelivery>({ ttlMs: 60_000, negativeTtlMs: 5_000 }),
+		cache: newCardCache(),
 		now: Date.now,
+		timeoutMs: CARD_DELIVERY_TIMEOUT_MS,
 	}
 }
 
@@ -39,13 +65,17 @@ export function cardDeliveryRuntime(): CardDeliveryRuntime {
 	return runtime
 }
 
-/** Test seam: replace parts of the runtime (a fresh cache unless one is given). Returns a restore. */
+/**
+ * Test seam: replace parts of the runtime (a fresh cache unless one is given) and forget the page's envelope seeds
+ * (a fresh runtime is a fresh page). Returns a restore.
+ */
 export function setCardDeliveryRuntimeForTests(overrides: Partial<CardDeliveryRuntime>): () => void {
+	forgetPageSeedsForTests()
 	const previous = runtime
 	const now = overrides.now ?? previous.now
 	runtime = {
 		...previous,
-		cache: new TtlCache<CachedDelivery>({ ttlMs: 60_000, negativeTtlMs: 5_000, now }),
+		cache: newCardCache(now),
 		...overrides,
 	}
 	return () => {