@certrev/cert-block 1.2.1 → 2.0.0

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

@@ -25,16 +25,43 @@ import { type CertBlockMode, renderCertBlock } from '../components/render-cert-b
 import { CERT_STRINGS_VERSION, type ResolvedBlockTheme } from '../components/render-def.js'
 import { type CertPayload, renderVerdict } from '../contract/kernel.js'
 import {
+	type DeliveredFace,
 	type DesignPin,
 	getVerifiedDelivery,
 	parseDesignPin,
 	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 { cardDeliveryRuntime } from './delivery-runtime.js'
+import { ContractCardFace } from './contract-card.js'
+import {
+	type DeliveredFaceHashes,
+	deliveredFaceDigest,
+	deliveredFaceHtml,
+	deliveredFaceMatches,
+	faceHashesFor,
+	showsWholeCard,
+} from './delivered-face.js'
+import { cardDeliveryRuntime, cardResolveKidFor } from './delivery-runtime.js'
 import { envelopeCardHtml, envelopeCardInput, isReaderFaceDef } from './envelope-face.js'
 import {
 	type FallbackFace,
@@ -91,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
 }
@@ -172,11 +201,25 @@ function suspendOn(key: string, start: () => Promise<VerifiedDelivery>): Verifie
 		pending = start().finally(() => inflightReads.delete(key))
 		inflightReads.set(key, pending)
 	}
-	const use = (React as unknown as { use?: <T>(p: Promise<T>) => T }).use
+	return suspendUntil(pending)
+}
+
+/** `use` where React has it (19), else the thrown promise (18). */
+function suspendUntil<T>(pending: Promise<T>): T {
+	const use = (React as unknown as { use?: <U>(p: Promise<U>) => U }).use
 	if (typeof use === 'function') return use(pending)
 	throw pending
 }
 
+/**
+ * 1.3.0: a delivered face's two digests, suspending once while WebCrypto computes them (`faceHashesFor` memoizes them
+ * by the face's content, so every later render of the same face, server or browser, reads them at once).
+ */
+function suspendOnFaceHashes(face: DeliveredFace): DeliveredFaceHashes | null {
+	const memo = faceHashesFor(face)
+	return memo.settled ? memo.settled.hashes : suspendUntil(memo.pending)
+}
+
 /**
  * 1.2.0-canary.6: the reader sidebar card is a right float that the article's copy flows around, as it does on a
  * WordPress or Shopify page. On a Builder page the card sits in its own block, a flex item of the flex column that holds
@@ -225,6 +268,8 @@ function EnvelopeFace(props: {
 	readonly html: string
 	readonly defVersion: number | undefined
 	readonly reader?: boolean
+	/** 1.3.0: the server-rendered face the signed digest binds (`DeliveredEnvelopeFace`); never with `reader`. */
+	readonly delivered?: 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`). */
@@ -270,8 +315,12 @@ function EnvelopeFace(props: {
 			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
+			{...(props.reader
+				? { 'data-certrev-face': 'reader', style: { display: 'flow-root' } }
+				: props.delivered
+					? { 'data-certrev-face': 'delivered' }
+					: {})}
+			// biome-ignore lint/security/noDangerouslySetInnerHtml: renderCertBlock is the escaping-safe SSR string renderer; a delivered face paints only when its bytes hash to the signed faceDigest
 			dangerouslySetInnerHTML={{ __html: props.html }}
 		/>,
 	)
@@ -279,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 {
@@ -340,6 +393,51 @@ function ReaderEnvelopeFace(props: {
 	)
 }
 
+/**
+ * 1.3.0: the delivered face this paint may use, or undefined (paint what 1.2.1 paints). Only for an unpinned card on a
+ * block that shows the whole card, a digest the verified content signs for the def's version, and a face whose UTF-8
+ * bytes hash to it (`delivered-face.ts`). Suspends once while WebCrypto hashes a face it has not seen.
+ */
+function deliveredFaceFor(
+	payload: CertPayload,
+	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
+	const hashes = hashed !== undefined ? hashed : suspendOnFaceHashes(face)
+	return deliveredFaceMatches(hashes, digest) ? face : undefined
+}
+
+/**
+ * 1.3.0: the delivered face, in the card's own wrapper (the same attributes as any envelope face, and
+ * `data-certrev-face="delivered"`): the server's stylesheet, then its markup. `seed` is the record that names it.
+ */
+function DeliveredEnvelopeFace(props: {
+	readonly face: DeliveredFace
+	readonly defVersion: number
+	readonly seed: string
+}) {
+	return <EnvelopeFace delivered html={deliveredFaceHtml(props.face)} defVersion={props.defVersion} seed={props.seed} />
+}
+
+/**
+ * 1.3.0: what a card hydrating a seed that names a delivered face renders when the browser's own check of that face
+ * fails (no WebCrypto: an insecure context; or bytes that do not hash to the seed's digest). The server painted the
+ * delivered face there, and the browser must not render that markup, so this adopts the server's element as it stands
+ * (no attribute or innerHTML compared: `suppressHydrationWarning`; no children hydrated: `dangerouslySetInnerHTML`)
+ * and paints nothing of its own. The render right after hydration (at the browser's clock) is another component, so
+ * React replaces this element with the face 1.2.1 paints for the seed.
+ */
+function ServerFaceUntilHydrated() {
+	// biome-ignore lint/security/noDangerouslySetInnerHtml: an empty string; it only stops React hydrating the server's children
+	return <div suppressHydrationWarning dangerouslySetInnerHTML={{ __html: '' }} />
+}
+
 /** Paint a verified payload with its def; null when the def and content give no face. */
 function paintEnvelope(
 	payload: CertPayload,
@@ -404,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,
@@ -414,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
 }
 
 /**
@@ -435,14 +645,58 @@ function paintRecord(
 				return null
 			}
 		}
-		return paintEnvelope(record.seed.payload, record.seed.renderDef, props, record.raw)
+		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 delivered = deliveredFaceFor(seed.payload, seed.renderDef, seed.face, props)
+		if (delivered && seed.renderDef) {
+			return <DeliveredEnvelopeFace face={delivered} defVersion={seed.renderDef.v} seed={record.raw} />
+		}
+		// Hydrating (not `judge`) over the delivered face the server painted, which the browser could not confirm.
+		if (seed.face && !judge) return <ServerFaceUntilHydrated />
+		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. */
@@ -469,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)
 }
 
@@ -551,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) {
@@ -560,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,
@@ -568,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,
 	}
@@ -576,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({
@@ -587,6 +862,37 @@ 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, settled.faceHashes)
+	if (delivered && seed.renderDef) {
+		return (
+			<DeliveredEnvelopeFace
+				face={delivered}
+				defVersion={seed.renderDef.v}
+				seed={serializeSeed({ ...seed, face: delivered })}
+			/>
+		)
+	}
 	return paintEnvelope(seed.payload, seed.renderDef, props, serializeSeed(seed))
 }
 
@@ -613,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 }} />
+		</>
+	)
+}