@certrev/cert-block 1.3.0 → 2.0.0

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

@@ -32,9 +32,27 @@ import {
 	readVerifiedDelivery,
 	type VerifiedDelivery,
 } from '../verify/get-verified-delivery.js'
+import {
+	acceptedCardBinding,
+	type CardBinding,
+	type CardDocumentV1,
+	type CardPartName,
+	cardDigestFor,
+	cardDigestMatches,
+	cardMatchesPlacement,
+	cardPartsFor,
+	parseCardDocument,
+} from './card-contract.js'
 import { CARD_READER_CSS } from './card-reader-css.js'
+import {
+	type CardFallbackDetail,
+	type CardFallbackReason,
+	reportCardFallbackInBrowser,
+	reportCardFallbackOnServer,
+} from './card-report.js'
 import type { BuilderCertChromeData, CertChromeRenderDef } from './cert-chrome-data.js'
 import { BUILDER_CERT_CHROME_KEYS } from './cert-chrome-data.js'
+import { ContractCardFace } from './contract-card.js'
 import {
 	type DeliveredFaceHashes,
 	deliveredFaceDigest,
@@ -43,7 +61,7 @@ import {
 	faceHashesFor,
 	showsWholeCard,
 } from './delivered-face.js'
-import { cardDeliveryRuntime } from './delivery-runtime.js'
+import { cardDeliveryRuntime, cardResolveKidFor } from './delivery-runtime.js'
 import { envelopeCardHtml, envelopeCardInput, isReaderFaceDef } from './envelope-face.js'
 import {
 	type FallbackFace,
@@ -100,11 +118,13 @@ export interface CertReviewCardProps extends Partial<BuilderCertChromeData> {
 		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.
+	 * A Delivery read FROM THE BROWSER for a card the server did not render (a client-side navigation, Builder's editor).
+	 * 2.0.0: ON by default (absent or `true`): it is the only way CertREV's server-rendered card exists after an in-app
+	 * navigation, and it needs the Delivery API's origin (`https://portal.certrev.com`) in the page's `connect-src`, one
+	 * of the four CSP sources 2.0 asks for. A read the policy blocks is a read that did not reach CertREV: the block's
+	 * own options face, as 1.3.1 painted it (and a reported `delivery_unreachable`). `false` restores 1.2.0 to 1.3.1's
+	 * behaviour: no request from the browser, and such a card paints the block's options face. Not a Builder input: a
+	 * brand sets it in code, on a wrapper of this component.
 	 */
 	clientRead?: boolean
 }
@@ -308,9 +328,13 @@ function EnvelopeFace(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. */
+/**
+ * Whose avatar a broken photo is. The banner's two bylines take the same face (1.3.1; the author's was the small
+ * `.certrev-r-face.sm` before), so the person is read from the byline: the author's carries the plain "Written by"
+ * role, the reviewer's "Reviewed by" (`.on`), and the sidebar's and the memo's reviewer has no role at all.
+ */
 function photoPerson(img: HTMLImageElement): PhotoPerson {
-	return img.parentElement?.classList.contains('sm') ? 'author' : 'expert'
+	return img.closest('.certrev-r-by')?.querySelector('.certrev-r-role:not(.on)') ? 'author' : 'expert'
 }
 
 interface EnvelopeCardProps {
@@ -379,11 +403,14 @@ function deliveredFaceFor(
 	renderDef: CertChromeRenderDef | null,
 	face: DeliveredFace | undefined,
 	props: EnvelopeCardProps,
+	/** 2.0.0: the hashes the read computed (`VerifiedDelivery.faceHashes`): then nothing suspends here. */
+	hashed?: DeliveredFaceHashes | null,
 ): DeliveredFace | undefined {
 	if (!face || props.design || !showsWholeCard(props.part)) return undefined
 	const digest = deliveredFaceDigest(payload.content, renderDef, face)
 	if (!digest) return undefined
-	return deliveredFaceMatches(suspendOnFaceHashes(face), digest) ? face : undefined
+	const hashes = hashed !== undefined ? hashed : suspendOnFaceHashes(face)
+	return deliveredFaceMatches(hashes, digest) ? face : undefined
 }
 
 /**
@@ -475,9 +502,110 @@ 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
+/**
+ * 2.0.0: reports one fallback (`card-report.ts`) and renders nothing (no element, no marker: it changes no byte of the
+ * page). On a server it reports as it renders; in a browser, once it has mounted.
+ */
+function FallbackReport(props: { readonly detail: CardFallbackDetail; readonly server: boolean }) {
+	const { detail, server } = props
+	if (server) reportCardFallbackOnServer(detail)
+	React.useEffect(() => {
+		reportCardFallbackInBrowser(detail)
+	}, [detail])
+	return null
+}
+
+/** A face with its fallback report beside it. */
+function withReport(
+	face: React.ReactElement | null,
+	reason: CardFallbackReason,
+	props: EnvelopeCardProps,
+	server: boolean,
+	certId?: string,
+): React.ReactElement {
+	const detail: CardFallbackDetail = {
+		reason,
+		platform: 'builder',
+		externalId: props.externalId,
+		...(certId === undefined ? {} : { certId }),
+	}
+	return (
+		<>
+			{face}
+			<FallbackReport detail={detail} server={server} />
+		</>
+	)
+}
+
+/**
+ * 2.0.0: what a contract-1 (or unsupported-contract) placement prints, decided by the SIGNED binding (`card-contract.ts`):
+ * the card when the served document hashes to the signed digest and names this design version, certificate and
+ * placement; else nothing, and the reason. Suspends once while WebCrypto hashes a document it has not seen.
+ */
+type ContractOutcome =
+	| { readonly kind: 'card'; readonly card: CardDocumentV1; readonly names: CardPartName[] }
+	| { readonly kind: 'none'; readonly reason?: CardFallbackReason }
+
+function contractOutcome(
+	binding: CardBinding | 'unsupported',
+	rawCard: unknown,
+	payload: CertPayload,
+	props: EnvelopeCardProps,
+	/** The digest the read computed (`VerifiedDelivery.cardDigest`): then nothing suspends here. */
+	digested?: string | null,
+): ContractOutcome {
+	if (binding === 'unsupported') return { kind: 'none', reason: 'card_unsupported_contract' }
+	// CertREV's replica pin: the signed card was painted for one design version; another pin gets nothing.
+	if (props.design && props.design.version !== binding.defVersion) return { kind: 'none', reason: 'card_pin_mismatch' }
+	if (rawCard === undefined || rawCard === null) return { kind: 'none', reason: 'card_missing' }
+	const card = parseCardDocument(rawCard)
+	if (!card || !cardMatchesPlacement(card, binding, payload, props.externalId)) {
+		return { kind: 'none', reason: 'card_verify_failed' }
+	}
+	let digest: string | null
+	if (digested !== undefined) {
+		digest = digested
+	} else {
+		// A page's seed: the one suspension of this render (a render that read waits on nothing but its read).
+		const memo = cardDigestFor(card)
+		digest = memo.settled ? memo.settled.digest : suspendUntil(memo.pending)
+	}
+	if (!cardDigestMatches(digest, binding)) return { kind: 'none', reason: 'card_verify_failed' }
+	// A block with nothing of this design to print (a memo block of a memo-less card, or of a sidebar design) prints
+	// nothing, by design: not a fallback.
+	const names = cardPartsFor(card, props.part)
+	return names.length === 0 ? { kind: 'none' } : { kind: 'card', card, names }
+}
+
+/** The `'none'` record of a contract-1 placement, with its reason when it is a fallback. */
+function contractNone(
+	props: EnvelopeCardProps,
+	reason: CardFallbackReason | undefined,
+	server: boolean,
+	certId: string,
+): React.ReactElement {
+	const record = serializeFallback({
+		baseUrl: props.baseUrl,
+		externalId: props.externalId,
+		...(props.design ? { design: props.design } : {}),
+		face: 'none',
+		...(reason ? { reason } : {}),
+	})
+	const face = <NoFace record={record} />
+	return reason ? withReport(face, reason, props, server, certId) : face
+}
+
+/**
+ * What a card with no verified envelope paints: the options face when CertREV was not reached, else nothing. 2.0.0:
+ * the same faces and records as 1.3.1, and two of them are now reported: the options face painted because CertREV
+ * was not reached (`delivery_unreachable`), and nothing painted because the envelope's kid is unknown (`unknown_key`).
+ */
+function settleWithoutEnvelope(
+	props: EnvelopeCardProps,
+	verdict: { readonly unreachable: boolean; readonly reason?: string },
+	server: boolean,
+): React.ReactElement {
+	const html = verdict.unreachable ? fallbackFace(props) : null
 	const face: FallbackFace = html === null ? 'none' : 'options'
 	const record = serializeFallback({
 		baseUrl: props.baseUrl,
@@ -485,7 +613,18 @@ function settleWithoutEnvelope(props: EnvelopeCardProps, unreachable: boolean):
 		...(props.design ? { design: props.design } : {}),
 		face,
 	})
-	return html === null ? <NoFace record={record} /> : <OptionsFace block={props.block} html={html} record={record} />
+	if (html !== null) {
+		return withReport(
+			<OptionsFace block={props.block} html={html} record={record} />,
+			'delivery_unreachable',
+			props,
+			server,
+		)
+	}
+	const none = <NoFace record={record} />
+	// A block with no options to paint when CertREV was not reached is reported too (break-it B5).
+	if (verdict.unreachable) return withReport(none, 'delivery_unreachable', props, server)
+	return verdict.reason === 'unknown_key' ? withReport(none, 'unknown_key', props, server) : none
 }
 
 /**
@@ -506,9 +645,24 @@ function paintRecord(
 				return null
 			}
 		}
+		const { seed } = record
+		// 2.0.0: a seed whose signed binding names a contract prints the card it carries, only after the browser has
+		// checked it against that binding itself; otherwise nothing. Never a 1.3.1 face for such a placement.
+		const binding = acceptedCardBinding(seed.payload.content)
+		if (binding !== null) {
+			const outcome = contractOutcome(binding, seed.card, seed.payload, props)
+			if (outcome.kind === 'card')
+				return <ContractCardFace card={outcome.card} names={outcome.names} seed={record.raw} />
+			// Hydrating over the card the server printed, which the browser could not confirm (no WebCrypto): adopt the
+			// server's element; the render right after hydration prints nothing in its place.
+			if (!judge && outcome.reason === 'card_verify_failed' && seed.card !== undefined)
+				return <ServerFaceUntilHydrated />
+			// Nothing of this design for this block (a memo block of a sidebar card): nothing, and no record of its own.
+			if (outcome.reason === undefined) return null
+			return contractNone(props, outcome.reason, false, seed.payload.certId)
+		}
 		// 1.3.0: a seed that names a delivered face repaints it only after the browser hashes it against the seed
 		// payload's own digest; otherwise the seed paints what 1.2.1 paints for it.
-		const { seed } = record
 		const delivered = deliveredFaceFor(seed.payload, seed.renderDef, seed.face, props)
 		if (delivered && seed.renderDef) {
 			return <DeliveredEnvelopeFace face={delivered} defVersion={seed.renderDef.v} seed={record.raw} />
@@ -518,11 +672,31 @@ function paintRecord(
 		return paintEnvelope(seed.payload, seed.renderDef, props, record.raw)
 	}
 	const html = record.fallback.face === 'options' ? fallbackFace(props) : null
-	return html === null ? (
-		<NoFace record={record.raw} />
-	) : (
-		<OptionsFace block={props.block} html={html} record={record.raw} />
-	)
+	if (html !== null) {
+		return withReport(
+			<OptionsFace block={props.block} html={html} record={record.raw} />,
+			'delivery_unreachable',
+			props,
+			false,
+		)
+	}
+	const none = <NoFace record={record.raw} />
+	// 2.0.0: a contract-1 placement's record names why it printed nothing; the browser reports it too.
+	const reason = record.fallback.reason
+	return isFallbackReason(reason) ? withReport(none, reason, props, false) : none
+}
+
+const FALLBACK_REASONS: readonly string[] = [
+	'card_missing',
+	'card_verify_failed',
+	'card_unsupported_contract',
+	'card_pin_mismatch',
+	'unknown_key',
+	'delivery_unreachable',
+]
+
+function isFallbackReason(value: unknown): value is CardFallbackReason {
+	return typeof value === 'string' && FALLBACK_REASONS.includes(value)
 }
 
 /** What a card the client mounts with no record and no `clientRead` paints: the options face, or nothing. */
@@ -549,8 +723,9 @@ function StreamedRecordCard(props: EnvelopeCardProps) {
 		pendingRecord,
 	)
 	if (record === 'pending') return null
-	if (record === 'done') return clientMountFace(props)
 	const context = { platform: 'builder', externalId: props.externalId, now: new Date(rt.now()) }
+	// 2.0.0: the page loaded with no record for this placement: with `clientRead` (the default), the one read.
+	if (record === 'done') return props.clientRead ? readAndPaint(props, context, true) : clientMountFace(props)
 	return paintRecord(record, props, context, true)
 }
 
@@ -631,8 +806,9 @@ function EnvelopeCertReviewCard(props: EnvelopeCardProps) {
 	// 1.2.1, latched at mount: a client mount with no record and no `clientRead` while the page is still loading waits
 	// for a record the server may still be streaming, for the card's whole life (so it never swaps components when the
 	// record lands).
+	// 2.0.0: whatever `clientRead` says: a card that read instead of waiting would miss the record the server streams.
 	const [awaitsStream] = React.useState(
-		() => inBrowser && !hydrating && fromPage === undefined && !props.clientRead && document.readyState === 'loading',
+		() => inBrowser && !hydrating && fromPage === undefined && document.readyState === 'loading',
 	)
 	if (awaitsStream) return <StreamedRecordCard {...props} />
 	if (inBrowser) {
@@ -640,6 +816,19 @@ function EnvelopeCertReviewCard(props: EnvelopeCardProps) {
 		if (hydratedMount) return null
 		if (!props.clientRead) return clientMountFace(props)
 	}
+	return readAndPaint(props, context, inBrowser)
+}
+
+/**
+ * The Delivery read and its paint: a server render's, or a browser's (`clientRead`). Suspends on the read, and (1.3.0)
+ * on a delivered face's hashes or (2.0.0) on a card document's digest.
+ */
+function readAndPaint(
+	props: EnvelopeCardProps,
+	context: Parameters<typeof renderVerdict>[1],
+	inBrowser: boolean,
+): React.ReactElement | null {
+	const rt = cardDeliveryRuntime()
 	const { design } = props
 	const read = {
 		baseUrl: props.baseUrl,
@@ -648,7 +837,7 @@ function EnvelopeCertReviewCard(props: EnvelopeCardProps) {
 		context,
 		cache: rt.cache,
 		design,
-		resolveKid: rt.resolveKid,
+		resolveKid: cardResolveKidFor(rt, props.baseUrl),
 		fetchImpl: rt.fetchImpl(),
 		timeoutMs: rt.timeoutMs,
 	}
@@ -656,7 +845,13 @@ function EnvelopeCertReviewCard(props: EnvelopeCardProps) {
 		? `${props.baseUrl}|${props.externalId}|design=${design.version}|${design.brand ?? ''}`
 		: `${props.baseUrl}|${props.externalId}`
 	const settled = readVerifiedDelivery(read) ?? suspendOn(key, () => getVerifiedDelivery(read))
-	if (settled.verdict.decision !== 'render') return settleWithoutEnvelope(props, settled.unreachable === true)
+	if (settled.verdict.decision !== 'render') {
+		return settleWithoutEnvelope(
+			props,
+			{ unreachable: settled.unreachable === true, reason: settled.verdict.reason },
+			!inBrowser,
+		)
+	}
 	// 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({
@@ -667,9 +862,28 @@ function EnvelopeCertReviewCard(props: EnvelopeCardProps) {
 		signature: settled.signature,
 		renderDef: settled.renderDef,
 	})
+	// 2.0.0: a placement whose signed binding names a contract prints CertREV's card, or nothing; never a face of its own.
+	const binding = acceptedCardBinding(seed.payload.content)
+	if (binding !== null) {
+		const outcome = contractOutcome(binding, settled.card, seed.payload, props, settled.cardDigest)
+		if (outcome.kind === 'card') {
+			return (
+				<ContractCardFace
+					card={outcome.card}
+					names={outcome.names}
+					seed={serializeSeed({ ...seed, card: outcome.card as unknown as Readonly<Record<string, unknown>> })}
+				/>
+			)
+		}
+		// Nothing of this design for this block, by design: nothing at all, and NO record. A record here would sit under the
+		// same placement as the block that printed the card (a split header and memo pair) and, read last on hydration,
+		// would take that block's card down (break-it B2).
+		if (outcome.reason === undefined) return null
+		return contractNone(props, outcome.reason, !inBrowser, seed.payload.certId)
+	}
 	// 1.3.0: the server-rendered face the Delivery API served beside the envelope, when its bytes hash to the digest the
 	// verified payload signs; the seed then carries it, so the browser can repaint (and re-check) the same face.
-	const delivered = deliveredFaceFor(seed.payload, seed.renderDef, settled.face, props)
+	const delivered = deliveredFaceFor(seed.payload, seed.renderDef, settled.face, props, settled.faceHashes)
 	if (delivered && seed.renderDef) {
 		return (
 			<DeliveredEnvelopeFace
@@ -705,7 +919,7 @@ export function CertReviewCard(props: CertReviewCardProps) {
 					part={props.part}
 					design={design}
 					block={props}
-					clientRead={props.clientRead === true}
+					clientRead={props.clientRead !== false}
 				/>
 			</Suspense>
 		)

package/src/builder/contract-card.tsx

@@ -0,0 +1,159 @@
+/**
+ * The contract-1 card face (2.0.0): one Builder block printing CertREV's server-rendered card verbatim.
+ *
+ * The block's wrapper holds, as its `dangerouslySetInnerHTML`, exactly `cardHtml(card, names)`: the block's part hosts
+ * in page order and, in the block holding the document's first part, the head fragment, both CertREV dialog hosts and
+ * the runtime's tag (`card-contract.ts`).
+ * Each host is a `<certrev-card>` with a declarative shadow root (`<template shadowrootmode="open">`), which the
+ * browser's HTML parser attaches as it reads the server's page: the card is complete with JavaScript off, and no page
+ * rule reaches inside it. React never reconciles the hosts (they are not React children), so the hosted runtime may
+ * remove a revoked placement's hosts without React noticing.
+ *
+ * What the parser does not do, the card does once it has mounted (`useCardRoots`):
+ *  - ATTACH ROOTS the parser never saw. A card React inserts (an in-app navigation, Builder's editor, React's own
+ *    re-render after a hydration error) gets its HTML through `innerHTML`, which leaves a declarative template inert.
+ *    The wrapper is re-parsed with `setHTMLUnsafe`, which attaches declarative roots; a browser without it (or without
+ *    declarative shadow DOM at all) gets each root attached from its template (`attachShadow` with the template's mode
+ *    and options, then the template's content). A host that already has its root is left alone, so a hydrated card,
+ *    whose roots the parser attached, is not touched.
+ *  - LOAD THE RUNTIME a React-inserted `<script>` never runs: once per page, into `document.head`, with its SRI
+ *    integrity and `crossorigin="anonymous"`, unless the runtime is already running (its global guard) or already
+ *    injected. Only the block that prints the runtime's tag loads it (`cardCarriesAssets`). The server's HTML carries
+ *    the same tag in that block's wrapper, which the parser runs; the runtime's init is idempotent, so it starts once.
+ * Both run in a layout effect, before the browser paints the inserted card, so a client-mounted card never shows an
+ * empty frame.
+ *
+ * ONE BUILDER RULE, for the sidebar card only. The card's rail is a right float that the article's copy flows around
+ * (the Appearance preview's layout, and every other CMS's). On a Builder page the block sits in Builder's own wrapper,
+ * a flex item of the flex column that holds the entry's blocks, and a flex item contains its floats: the block spans
+ * the column at the rail's height and no copy sits beside it. `BUILDER_CARD_FLOW_CSS` lets the float out of Builder's
+ * wrappers, as 1.2.0-canary.6 did for the reader face: in a column that holds a printed rail, above the card's own
+ * 820px breakpoint (below it the rail stacks as a block), the column lays its blocks out as blocks and still contains
+ * the float, and the rail's block and the card wrapper become plain blocks. It reaches nothing inside the card (the
+ * shadow root is out of its reach) and nothing on a page without a rail, or in a browser without `:has()`.
+ */
+
+import * as React from 'react'
+import { type CardDocumentV1, type CardPartName, cardCarriesAssets, cardHtml } from './card-contract.js'
+import { SEED_ATTRIBUTE } from './ssr-seed.js'
+
+/** The global the hosted runtime sets once it has started (`Symbol.for('certrev.card-runtime')` on `document`). */
+const RUNTIME_GUARD = Symbol.for('certrev.card-runtime')
+/** Marks the runtime tag this package injected into `document.head`. */
+const INJECTED_RUNTIME_ATTRIBUTE = 'data-certrev-card-runtime'
+
+/** A layout effect in a browser; nothing on a server (where React would only warn about it). */
+const useBrowserLayoutEffect = typeof document === 'undefined' ? () => {} : React.useLayoutEffect
+
+/** Whether this host still holds an unattached declarative root. */
+function pendingTemplate(host: Element): HTMLTemplateElement | null {
+	if ((host as HTMLElement).shadowRoot) return null
+	for (const child of Array.from(host.children)) {
+		if (child instanceof HTMLTemplateElement && child.hasAttribute('shadowrootmode')) return child
+	}
+	return null
+}
+
+/** Attach one host's root from its template, as the parser would have: its mode, its options, its content. */
+function attachFromTemplate(host: HTMLElement, template: HTMLTemplateElement): void {
+	const mode = template.getAttribute('shadowrootmode') === 'closed' ? 'closed' : 'open'
+	const init: ShadowRootInit & { clonable?: boolean; serializable?: boolean } = {
+		mode,
+		delegatesFocus: template.hasAttribute('shadowrootdelegatesfocus'),
+		...(template.hasAttribute('shadowrootclonable') ? { clonable: true } : {}),
+		...(template.hasAttribute('shadowrootserializable') ? { serializable: true } : {}),
+	}
+	const root = host.attachShadow(init)
+	root.appendChild(template.content)
+	template.remove()
+}
+
+/**
+ * Give every host in `wrapper` its declarative root: a no-op where the parser attached them all; else the wrapper is
+ * re-parsed from `html` with `setHTMLUnsafe` where the browser has it, or each pending root is attached from its
+ * template. Returns how many hosts were pending (for tests and the replica's evidence).
+ */
+export function attachCardRoots(wrapper: Element, html: string): number {
+	const pending = Array.from(wrapper.querySelectorAll('certrev-card')).filter((host) => pendingTemplate(host) !== null)
+	if (pending.length === 0) return 0
+	const parse = (wrapper as Element & { setHTMLUnsafe?: (html: string) => void }).setHTMLUnsafe
+	if (typeof parse === 'function') {
+		parse.call(wrapper, html)
+		// A browser whose setHTMLUnsafe predates declarative roots leaves templates behind: attach those by hand.
+		for (const host of Array.from(wrapper.querySelectorAll('certrev-card'))) {
+			const template = pendingTemplate(host)
+			if (template) attachFromTemplate(host as HTMLElement, template)
+		}
+		return pending.length
+	}
+	for (const host of pending) {
+		const template = pendingTemplate(host)
+		if (template) attachFromTemplate(host as HTMLElement, template)
+	}
+	return pending.length
+}
+
+/** Load the document's runtime once per page: unless it already runs, or this package already injected it. */
+export function injectCardRuntime(card: CardDocumentV1): void {
+	const runtime = card.assets.runtime
+	if (!runtime || typeof document === 'undefined' || !document.head) return
+	if ((document as unknown as Record<symbol, unknown>)[RUNTIME_GUARD]) return
+	for (const script of Array.from(document.head.querySelectorAll(`script[${INJECTED_RUNTIME_ATTRIBUTE}]`))) {
+		if (script.getAttribute('src') === runtime.src) return
+	}
+	const script = document.createElement('script')
+	// Attributes, not IDL properties: the markup is then exactly the server's tag, wherever a property is not reflected.
+	script.setAttribute('src', runtime.src)
+	script.setAttribute('integrity', runtime.integrity)
+	script.setAttribute('crossorigin', 'anonymous')
+	script.defer = true
+	script.setAttribute(INJECTED_RUNTIME_ATTRIBUTE, '')
+	document.head.appendChild(script)
+}
+
+/** Builder's wrappers around a printed rail let its float out (the header comment). */
+export const BUILDER_CARD_FLOW_CSS =
+	'@media not all and (max-width: 820px){' +
+	'.builder-blocks:has(> .builder-block > [data-certrev-face="card"] > certrev-card[data-certrev-part="rail"]){display:flow-root !important}' +
+	'.builder-blocks > .builder-block:has(> [data-certrev-face="card"] > certrev-card[data-certrev-part="rail"]){display:block !important}' +
+	'.builder-blocks > .builder-block > [data-certrev-face="card"]:has(> certrev-card[data-certrev-part="rail"]){display:block !important}' +
+	'}'
+
+export function ContractCardFace(props: {
+	readonly card: CardDocumentV1
+	readonly names: readonly CardPartName[]
+	/** The record that names this card (`ssr-seed.ts`): the browser repaints it from here with no read. */
+	readonly seed: string
+}) {
+	const ref = React.useRef<HTMLDivElement>(null)
+	const html = cardHtml(props.card, props.names)
+	const { card } = props
+	const carriesAssets = cardCarriesAssets(card, props.names)
+	useBrowserLayoutEffect(() => {
+		const wrapper = ref.current
+		if (!wrapper) return
+		attachCardRoots(wrapper, html)
+		if (carriesAssets) injectCardRuntime(card)
+	}, [html, card, carriesAssets])
+	const wrapper = (
+		<div
+			ref={ref}
+			data-certrev-cert-chrome=""
+			data-certrev-delivery=""
+			data-certrev-face="card"
+			data-certrev-contract={String(props.card.contract)}
+			data-certrev-def-version={props.card.defVersion}
+			{...{ [SEED_ATTRIBUTE]: props.seed }}
+			// biome-ignore lint/security/noDangerouslySetInnerHtml: CertREV's card document, printed only after it hashes to the digest the verified envelope signs
+			dangerouslySetInnerHTML={{ __html: html }}
+		/>
+	)
+	if (!props.names.includes('rail')) return wrapper
+	return (
+		<>
+			{wrapper}
+			{/* biome-ignore lint/security/noDangerouslySetInnerHtml: a package constant; React would escape the `>` and `"` of its selectors */}
+			<style data-certrev-builder-flow="" dangerouslySetInnerHTML={{ __html: BUILDER_CARD_FLOW_CSS }} />
+		</>
+	)
+}

package/src/builder/delivered-face.ts

@@ -103,6 +103,22 @@ export function deliveredFaceHtml(face: DeliveredFace): string {
 	return `<style>${face.css}</style>${face.html}`
 }
 
+/**
+ * Make room in a memo of pending-then-settled work: drop the oldest SETTLED entry once the memo is full, never a pending
+ * one. A render suspends on a pending entry and, when React retries it, must find that entry again; evicting it would make
+ * every retry start (and suspend on) a new one, so a page with more documents than the memo holds would never finish
+ * (break-it B1). With nothing settled to drop, the memo grows past its bound until entries settle.
+ */
+export function evictOldestSettled<V extends { settled?: unknown }>(memo: Map<string, V>, max: number): void {
+	if (memo.size < max) return
+	for (const [key, entry] of memo) {
+		if (entry.settled !== undefined) {
+			memo.delete(key)
+			return
+		}
+	}
+}
+
 /** One face's hashing: the pending digest, and its answer once settled. */
 export interface FaceHashMemo {
 	readonly pending: Promise<DeliveredFaceHashes | null>
@@ -128,10 +144,8 @@ export function faceHashesFor(face: DeliveredFace): FaceHashMemo {
 			return hashes
 		}),
 	}
-	if (faceHashMemo.size >= FACE_HASH_MEMO_MAX) {
-		const oldest = faceHashMemo.keys().next().value
-		if (oldest !== undefined) faceHashMemo.delete(oldest)
-	}
+	// 2.0.0: never a pending entry (break-it B1: more faces than the memo holds made every retry suspend again).
+	evictOldestSettled(faceHashMemo, FACE_HASH_MEMO_MAX)
 	faceHashMemo.set(key, fresh)
 	return fresh
 }

package/src/builder/delivery-runtime.ts

@@ -13,11 +13,19 @@
  * 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.
+ *
+ * 2.0.0: the trust root is a key SET (`verify/key-set.ts`). `resolveKid` is still the baked set (today
+ * `cert-issuer-1`), and the card verifies with `resolveKidFor(baseUrl)`: a baked kid resolves as before, any other kid
+ * makes one read of the delivery origin's published key set, accepted only when a baked kid signs it. A rotation then
+ * needs no reinstall. The card's (2.0) contract-1 document digests are memoized with the delivered faces' hashes.
  */
 
 import type { ResolvePublicKeyByKid } from '../contract/kernel.js'
 import { TtlCache } from '../verify/cache.js'
 import type { CachedDelivery } from '../verify/get-verified-delivery.js'
+import { forgetKeySetsForTests, keySetResolver } from '../verify/key-set.js'
+import { forgetCardDigestsForTests } from './card-contract.js'
+import { forgetCardReportsForTests } from './card-report.js'
 import { forgetFaceHashesForTests } from './delivered-face.js'
 import { CERT_ISSUER_KID, CERT_ISSUER_PUBLIC_KEY_PEM } from './issuer-key.js'
 import { forgetPageSeedsForTests } from './ssr-seed.js'
@@ -28,7 +36,13 @@ export const CARD_DELIVERY_TIMEOUT_MS = 8_000
 export const CARD_DELIVERY_STALE_MS = 300_000
 
 export interface CardDeliveryRuntime {
+	/** The baked kids: the package's own trust root (and the only keys that may sign a published key set). */
 	readonly resolveKid: ResolvePublicKeyByKid
+	/**
+	 * 2.0.0: what the card verifies a read from `baseUrl` with: the baked kids, then that origin's signed published set.
+	 * Absent: derived from `resolveKid`, `fetchImpl` and `timeoutMs` (`keySetResolver`).
+	 */
+	readonly resolveKidFor?: (baseUrl: string) => ResolvePublicKeyByKid
 	readonly fetchImpl: () => typeof fetch
 	readonly cache: TtlCache<CachedDelivery>
 	readonly now: () => number
@@ -66,13 +80,28 @@ export function cardDeliveryRuntime(): CardDeliveryRuntime {
 	return runtime
 }
 
+/** 2.0.0: the resolver for a read from `baseUrl`: the runtime's own, else the baked kids plus the origin's key set. */
+export function cardResolveKidFor(rt: CardDeliveryRuntime, baseUrl: string): ResolvePublicKeyByKid {
+	if (rt.resolveKidFor) return rt.resolveKidFor(baseUrl)
+	return keySetResolver({
+		baseUrl,
+		bakedResolveKid: rt.resolveKid,
+		fetchImpl: rt.fetchImpl(),
+		...(rt.timeoutMs !== undefined ? { timeoutMs: rt.timeoutMs } : {}),
+	})
+}
+
 /**
  * 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) and (1.3.0) every delivered face's memoized hashes. Returns a restore.
+ * (a fresh runtime is a fresh page), (1.3.0) every delivered face's memoized hashes and (2.0.0) every card
+ * document's digest and every published key set. Returns a restore.
  */
 export function setCardDeliveryRuntimeForTests(overrides: Partial<CardDeliveryRuntime>): () => void {
 	forgetPageSeedsForTests()
 	forgetFaceHashesForTests()
+	forgetCardDigestsForTests()
+	forgetKeySetsForTests()
+	forgetCardReportsForTests()
 	const previous = runtime
 	const now = overrides.now ?? previous.now
 	runtime = {

package/src/builder/index.tsx

@@ -155,6 +155,17 @@ export const certRevAnchorComponent: CertRevBuilderRegistration = {
 // 1.2.0-canary.5: the design pin, for CertREV's own canary replica (`<Content context={{ certrevDesignPin }}>`).
 export { type DesignPin, designPinFromUrl, parseDesignPin } from '../verify/get-verified-delivery.js'
 
+// 2.0.0: the contract-1 card (CertREV's server-rendered card document), its fallback report and the Builder flow rule.
+export {
+	acceptedCardBinding,
+	type CardBinding,
+	type CardDocumentV1,
+	type CardPartName,
+	cardDocumentDigest,
+	cardPartsFor,
+	parseCardDocument,
+} from './card-contract.js'
+export { CARD_FALLBACK_EVENT, type CardFallbackDetail, type CardFallbackReason } from './card-report.js'
 // ── The Builder.io PUSH kit (CertReviewCard) + the single-sourced wire type ──
 export {
 	BUILDER_CERT_CHROME_KEYS,
@@ -176,6 +187,7 @@ export {
 	PLACEMENT_INPUTS,
 	WIRE_INPUTS,
 } from './cert-review-card.js'
+export { BUILDER_CARD_FLOW_CSS } from './contract-card.js'
 export {
 	CERT_FACE_FIELDS,
 	credentialLabel,