@certrev/cert-block 1.3.0 → 2.0.1

package/src/builder/contract-card.tsx

@@ -0,0 +1,216 @@
+/**
+ * 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; the roots are checked after every commit of the block, whatever React wrote. React writes the card only
+ * when its HTML changes: the `dangerouslySetInnerHTML` object is kept per string, since React 19 rewrites `innerHTML`
+ * for every new object (2.0.0 on React 19 rebuilt the card on each re-render, and the hosted runtime re-attached it).
+ *
+ * NO CONSOLE NOISE (2.0.1). In a browser that parses declarative roots, the HTML React itself writes names each
+ * template's mode `data-certrev-shadowrootmode` instead of `shadowrootmode` (`clientCardHtml`): Chrome warns ("Found
+ * declarative shadowrootmode attribute on a template, but declarative Shadow DOM is not being parsed") for every such
+ * template `innerHTML` meets, and the layout effect re-parses the card's exact bytes anyway. The wrapper carries
+ * `suppressHydrationWarning` (React never prints it): the server's wrapper holds attached roots where React expects
+ * templates, which React's development build reported as a hydration mismatch on every page. React does not patch a
+ * hydrated element's HTML, so the server's card stays as the parser built it. A server, and a DOM without declarative
+ * roots (jsdom, an old browser), print the card's bytes unchanged.
+ *
+ * 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 { maybeSendBrowserHealth } from './card-beacon.js'
+import { type CardDocumentV1, type CardPartName, cardCarriesAssets, cardHtml } from './card-contract.js'
+import { afterPageSettles, applyCardPlacement } from './card-placement.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
+
+/** What a client render prints in place of a template's `shadowrootmode` (the header comment). */
+export const INERT_MODE_ATTRIBUTE = 'data-certrev-shadowrootmode'
+
+/** Whether this DOM parses declarative shadow roots (a browser does; a server and jsdom do not). */
+function parsesDeclarativeRoots(): boolean {
+	return typeof HTMLTemplateElement === 'function' && 'shadowRootMode' in HTMLTemplateElement.prototype
+}
+
+/** The card's HTML as React writes it in such a browser: each template's mode under `INERT_MODE_ATTRIBUTE`. */
+export function clientCardHtml(html: string): string {
+	return html.replace(/<template\b([^>]*?)\sshadowrootmode=/gi, `<template$1 ${INERT_MODE_ATTRIBUTE}=`)
+}
+
+/** The template's declared mode, under either name. */
+function declaredMode(template: Element): string | null {
+	return template.getAttribute('shadowrootmode') ?? template.getAttribute(INERT_MODE_ATTRIBUTE)
+}
+
+/** 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 && declaredMode(child) !== null) 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 = declaredMode(template) === '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}' +
+	'}'
+
+/** One object for the flow rule's element, so React 19 never rewrites it on a re-render. */
+const BUILDER_CARD_FLOW_HTML = { __html: BUILDER_CARD_FLOW_CSS }
+
+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
+	/** 2.0.1: the delivery origin the block read, where its sampled health beacon goes (`card-beacon.ts`). */
+	readonly origin?: string
+}) {
+	const ref = React.useRef<HTMLDivElement>(null)
+	const html = cardHtml(props.card, props.names)
+	const printed = typeof document !== 'undefined' && parsesDeclarativeRoots() ? clientCardHtml(html) : html
+	// One object per printed string: React 19 rewrites `innerHTML` whenever this prop is a new object (React 18 compared
+	// the strings), which would replace the attached card on every re-render.
+	const inner = React.useMemo(() => ({ __html: printed }), [printed])
+	const { card } = props
+	const carriesAssets = cardCarriesAssets(card, props.names)
+	// After every commit of this block (a no-op while every root is attached): whatever React wrote, the card has its roots
+	// before the browser paints.
+	useBrowserLayoutEffect(() => {
+		if (ref.current) attachCardRoots(ref.current, html)
+	})
+	useBrowserLayoutEffect(() => {
+		if (ref.current && carriesAssets) injectCardRuntime(card)
+	}, [card, carriesAssets])
+	const { origin } = props
+	React.useEffect(() => {
+		maybeSendBrowserHealth(origin, card.subject.externalId)
+	}, [origin, card])
+	// 2.0.1: the document's placement hints, once the page has settled (`card-placement.ts`). Keyed on the printed HTML,
+	// which the document and the parts decide, so a re-render that prints the same card moves nothing again.
+	const placing = React.useRef({ card, names: props.names })
+	placing.current = { card, names: props.names }
+	// biome-ignore lint/correctness/useExhaustiveDependencies: `html` is the trigger on purpose; the document and parts are read from the ref
+	React.useEffect(() => {
+		const wrapper = ref.current
+		if (!wrapper) return
+		return afterPageSettles(() => applyCardPlacement(wrapper, placing.current.card, placing.current.names))
+	}, [html])
+	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 }}
+			suppressHydrationWarning
+			// biome-ignore lint/security/noDangerouslySetInnerHtml: CertREV's card document, printed only after it hashes to the digest the verified envelope signs
+			dangerouslySetInnerHTML={inner}
+		/>
+	)
+	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={BUILDER_CARD_FLOW_HTML} />
+		</>
+	)
+}

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,22 +13,46 @@
  * 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 { setCardBeaconForTests } from './card-beacon.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'
 
 /** 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
+/**
+ * 2.0.1: how long a verified answer is fresh. With the stale window below, a card adds at most one minute to the Delivery
+ * API's own cache (`max-age=60, stale-while-revalidate=240`), so a revoked card is gone within ADR 0001 §7's five to
+ * six minutes (2.0.0's 60 s + 300 s here stacked to about twelve).
+ */
+export const CARD_DELIVERY_TTL_MS = 30_000
+/**
+ * How long past its TTL a certificate may still paint while it is refreshed or CertREV is down (2.0.1: 30 s; 2.0.0:
+ * 300 s). Never longer: past it, a read that cannot reach CertREV prints nothing.
+ */
+export const CARD_DELIVERY_STALE_MS = 30_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
@@ -40,7 +64,7 @@ const bakedResolveKid: ResolvePublicKeyByKid = (kid) =>
 
 function newCardCache(now?: () => number): TtlCache<CachedDelivery> {
 	return new TtlCache<CachedDelivery>({
-		ttlMs: 60_000,
+		ttlMs: CARD_DELIVERY_TTL_MS,
 		negativeTtlMs: 5_000,
 		staleMs: CARD_DELIVERY_STALE_MS,
 		// A refresh the host runtime abandoned (workerd cancels a finished request's I/O) never
@@ -66,13 +90,30 @@ 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. 2.0.1: beacons go nowhere (a test that wants them sets its own
+ * transport with `setCardBeaconForTests` after this). Returns a restore.
  */
 export function setCardDeliveryRuntimeForTests(overrides: Partial<CardDeliveryRuntime>): () => void {
 	forgetPageSeedsForTests()
 	forgetFaceHashesForTests()
+	forgetCardDigestsForTests()
+	forgetKeySetsForTests()
+	forgetCardReportsForTests()
+	const restoreBeacon = setCardBeaconForTests()
 	const previous = runtime
 	const now = overrides.now ?? previous.now
 	runtime = {
@@ -82,5 +123,6 @@ export function setCardDeliveryRuntimeForTests(overrides: Partial<CardDeliveryRu
 	}
 	return () => {
 		runtime = previous
+		restoreBeacon()
 	}
 }

package/src/builder/index.tsx

@@ -31,10 +31,10 @@
  * (`face: { html, css }`, unsigned) and the verified envelope signs that face's sha256 digests for the
  * def version served (`content.faceDigest`), an unpinned whole-card block paints that face instead;
  * markup that does not hash to the signed digest is never painted. A revoked, expired, unverifiable or unreachable cert, a marker that
- * is not exactly that shape, or a missing entry id renders nothing. A block WITHOUT the marker
- * (every entry exported before 1.1.0) renders from its options exactly as 1.0.3 did, so the
- * paragraph above still describes it: an editor who deletes the marker gets the options face back,
- * which is the 1.0.3 trust boundary, not a new one.
+ * is not exactly that shape, or a missing entry id renders nothing. 2.0.1: a block WITHOUT the marker
+ * (every entry exported before 1.1.0) renders nothing too, and reports `no_marker`: through 2.0.0 it
+ * painted its options as 1.0.3 did, unsigned export-time claims an editor could change. So deleting the
+ * marker no longer brings any face back.
  *
  * Three things the card DOES enforce, and they are the limit of it: no chrome at all without a
  * `reviewerName` and a `verifyUrl`; a credential renders only welded to its dated verification
@@ -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,

package/src/builder/ssr-seed.ts

@@ -41,9 +41,10 @@
  * page carried for another version.
  *
  * WHEN THE SERVER HAD NO ENVELOPE TO PAINT (1.2.0) the same attribute carries a fallback record instead of a seed:
- * `{ v: 1, baseUrl, externalId, design?, face }`, where `face` is `'options'` (CertREV could not be reached, so the
- * server painted the block's own options face) or `'none'` (the server painted nothing: revoked, expired, unverifiable,
- * for another entry). A browser that renders the card again (hydration, or React's client re-render after a hydration
+ * `{ v: 1, baseUrl, externalId, design?, face, reason? }`, where `face` is `'none'` (the server painted nothing:
+ * revoked, expired, unverifiable, for another entry, or, 2.0.1, CertREV not reached, with `reason` naming why) or, on a
+ * page a 2.0.0 server rendered, `'options'` (CertREV could not be reached and that server painted the block's options
+ * face; 2.0.1 prints nothing for it). A browser that renders the card again (hydration, or React's client re-render after a hydration
  * error elsewhere on the page) paints what the record says, so it neither reads the Delivery API nor shows a card the
  * server withheld. A record holds no payload, so `parseSeed` never takes one for a seed. A `'none'` record sits on a
  * `hidden` element with nothing in it.
@@ -55,6 +56,17 @@
  * whose hashes fail paints what 1.2.1 paints for it. A seed with no face is byte for byte the 1.2.1 seed. The face is
  * on the page twice (painted, and in the seed), which is its page-weight cost.
  *
+ * A CONTRACT-1 CARD RIDES THE SEED (2.0.0), and only when the server printed it: the seed then ends with `card`, the
+ * card document exactly as the Delivery API served it, whose RFC 8785 digest the signed `payload.content.faceDigest`
+ * binds (`contract: 1`, `doc`). The browser prints that card from the seed only after it has checked it against the
+ * seed payload's binding itself (`cert-review-card.tsx`), so a client re-render (React's recovery from a hydration
+ * error, a streamed record, a later mount of the same placement) prints the server's card with no read. A seed with no
+ * card is the 1.3.1 seed byte for byte. The card is on the page twice (printed, and in the seed), as 1.3.0's face is.
+ *
+ * A FALLBACK RECORD MAY NAME ITS REASON (2.0.0): where a contract-1 placement prints nothing, its `'none'` record ends
+ * with `reason` (`card_missing`, `card_verify_failed`, `card_unsupported_contract`, `card_pin_mismatch`), the same
+ * reason the card reports. Every other record is the 1.3.1 record byte for byte, and 1.3.1 ignores the key.
+ *
  * React-free and browser-only in effect: with no `document` (a server) `pageSeedFor` finds nothing, so a server never
  * reads or keeps a seed and a multi-tenant render process holds nothing per page.
  */
@@ -90,6 +102,11 @@ export interface DeliverySeed {
 	 * seed read from the page it is UNVERIFIED until hashed against `payload.content.faceDigest`.
 	 */
 	readonly face?: DeliveredFace
+	/**
+	 * 2.0.0: the contract-1 card document the server printed (the file header), exactly as served; absent whenever it
+	 * printed anything else. On a seed read from the page it is UNVERIFIED until checked against the payload's binding.
+	 */
+	readonly card?: Readonly<Record<string, unknown>>
 }
 
 /** A seed as read from the page: the parsed seed and the attribute's exact text (re-rendered verbatim on hydration). */
@@ -98,7 +115,7 @@ export interface PageSeed {
 	readonly raw: string
 }
 
-/** What the server painted with no verified envelope: the block's options face, or nothing. */
+/** What the server painted with no verified envelope: nothing (2.0.1 never writes `'options'`; a 2.0.0 page may hold one). */
 export type FallbackFace = 'options' | 'none'
 
 /** The record a server writes where it had no envelope to paint (the file header). */
@@ -107,6 +124,8 @@ export interface DeliveryFallback {
 	readonly externalId: string
 	readonly design?: DesignPin
 	readonly face: FallbackFace
+	/** 2.0.0: why a contract-1 placement printed nothing; absent on every other record. */
+	readonly reason?: string
 }
 
 /** A fallback record as read from the page, with the attribute's exact text. */
@@ -203,6 +222,8 @@ export function serializeSeed(seed: DeliverySeed): string {
 		renderDef: seed.renderDef,
 		// 1.3.0: last, and only with a delivered face, so a seed without one is the 1.2.1 bytes.
 		...(seed.face ? { face: { html: seed.face.html, css: seed.face.css } } : {}),
+		// 2.0.0: last, and only with a printed contract-1 card, so a seed without one is the 1.3.1 bytes.
+		...(seed.card ? { card: seed.card } : {}),
 	})
 }
 
@@ -213,6 +234,7 @@ export function serializeFallback(fallback: DeliveryFallback): string {
 		externalId: fallback.externalId,
 		...serializedPin(fallback.design),
 		face: fallback.face,
+		...(fallback.reason === undefined ? {} : { reason: fallback.reason }),
 	})
 }
 
@@ -234,7 +256,7 @@ export function parseSeed(raw: string): DeliverySeed | null {
 		return null
 	}
 	if (!isRecord(value) || value.v !== 1) return null
-	const { baseUrl, externalId, design, payload, signature, renderDef, face } = value
+	const { baseUrl, externalId, design, payload, signature, renderDef, face, card } = value
 	if (typeof baseUrl !== 'string' || typeof externalId !== 'string') return null
 	if (!isRecord(payload) || !isRecord(payload.subject) || !isRecord(payload.lifecycle) || !isRecord(payload.content)) {
 		return null
@@ -252,6 +274,8 @@ export function parseSeed(raw: string): DeliverySeed | null {
 		...(isRecord(signature) ? { signature: signature as unknown as CertSignature } : {}),
 		renderDef: parseRenderDef(renderDef),
 		...(delivered ? { face: delivered } : {}),
+		// 2.0.0: a card that is not a JSON object is no card (the seed paints as its binding says without one).
+		...(isRecord(card) ? { card } : {}),
 	}
 }
 
@@ -264,12 +288,18 @@ export function parseFallback(raw: string): DeliveryFallback | null {
 		return null
 	}
 	if (!isRecord(value) || value.v !== 1 || 'payload' in value) return null
-	const { baseUrl, externalId, design, face } = value
+	const { baseUrl, externalId, design, face, reason } = value
 	if (typeof baseUrl !== 'string' || typeof externalId !== 'string') return null
 	if (face !== 'options' && face !== 'none') return null
 	const pin = parsedPin(design)
 	if (pin === null) return null
-	return { baseUrl, externalId, ...(pin ? { design: pin } : {}), face }
+	return {
+		baseUrl,
+		externalId,
+		...(pin ? { design: pin } : {}),
+		face,
+		...(typeof reason === 'string' ? { reason } : {}),
+	}
 }
 
 /** One placement's key: the origin, the entry and the pin (the read's own key, so a pin never shares a seed). */

package/src/builder/version.ts

@@ -0,0 +1,2 @@
+/** This package's version, as its beacon reports it (held to `package.json` by `version.test.ts`). */
+export const CERT_BLOCK_VERSION = '2.0.1'

package/src/index.ts

@@ -160,6 +160,15 @@ export {
 	invalidateVerdict,
 	sharedVerdictCache,
 } from './verify/get-verified-envelope.js'
+// 2.0.0: the issuer key SET (baked kids, then the origin's published set signed by a baked kid).
+export {
+	type AcceptedKeySet,
+	KEY_SET_PATH,
+	type KeySetResolverOptions,
+	keySetResolver,
+	type PublishedKeySet,
+	verifyKeySet,
+} from './verify/key-set.js'
 export {
 	type FetchingKidResolverOptions,
 	fetchingKidResolver,