@certrev/cert-block 1.3.0 → 2.0.1

package/src/builder/card-contract.ts

@@ -0,0 +1,336 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * The contract-1 card a Builder block prints (2.0.0): the server's card document, bound by the signed digest
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * CertREV's contract v1 (portal ADR 0001) moves the card to the server: one renderer paints every part of a placement
+ * into a CARD DOCUMENT, and every CMS client prints those parts verbatim. Nothing visual, no string a reader sees and
+ * no layout is computed here. The Builder Delivery response carries the document as an UNSIGNED top-level sibling,
+ * `card`, beside `payload`, `signature`, `renderDef` and `face`. What binds it is the signed
+ * `payload.content.faceDigest`, which for a contract-1 Builder placement is
+ *
+ *   { v: 1, defVersion, html, css, contract: 1, doc }
+ *
+ * where `doc` is the lowercase hex sha256 of the document's RFC 8785 bytes (cert-contract's `canonicalizeJson`) and
+ * `html`/`css` bind 1.3.x's delivered face, which this client no longer reads for such a placement.
+ *
+ * THE SCHEMA IS THE PORTAL'S (`src/lib/cert-delivery/card-document.ts`, `CardDocumentV1`; source read at portal
+ * v1-core d5e459b685). This module mirrors only the fields a client reads, read-only, and never redefines them: the
+ * digest covers the document's exact bytes, so `parseCardDocument` returns the object it was given, never a copy.
+ *
+ * Which path a verified delivery takes is decided by the SIGNED binding alone (`acceptedCardBinding`):
+ *  - no `contract` key in the digest (every brand without CertREV's contract-1 entitlement): the 1.3.1 path, unchanged;
+ *  - a well-formed contract-1 binding: the card, only when the served document hashes to `doc` and names the same
+ *    design version, certificate and placement (`cardBinds`); anything else prints nothing and is reported;
+ *  - a `contract` key that is not a well-formed contract-1 binding (a later contract, a malformed digest): nothing, and
+ *    reported. A client refuses a contract it does not support (ADR 0001, section 2).
+ *
+ * React-free. Hashing uses WebCrypto (`crypto.subtle.digest`), as the kernel and the 1.3.0 face gate do, so it runs
+ * wherever the card verifies (Node SSR, edge runtimes, a browser in a secure context); the card owns the suspension.
+ */
+
+import { type CertContent, type CertPayload, canonicalizeJson } from '../contract/kernel.js'
+import { evictOldestSettled, sha256HexUtf8 } from './delivered-face.js'
+
+/** The contract this client prints. */
+export const CARD_CONTRACT_VERSION = 1
+
+/** The part names a document can hold, by where they go: banner card and memo, the sidebar rail, the floating pill. */
+export const CARD_PART_NAMES = ['top', 'bottom', 'rail', 'pill'] as const
+export type CardPartName = (typeof CARD_PART_NAMES)[number]
+
+/** The layouts a document paints. */
+export type CardLayout = 'banner' | 'sidebar' | 'floating'
+const CARD_LAYOUTS: readonly string[] = ['banner', 'sidebar', 'floating']
+
+/**
+ * The fields of the portal's `CardDocumentV1` this client reads. The document carries more (`renderer`, `placement`,
+ * `jsonld`, `lifecycle`, `cache`, `illustrative`); they are part of the digest and printed nowhere by Builder.
+ */
+export interface CardDocumentV1 {
+	readonly contract: 1
+	readonly kind: 'certrev.card'
+	readonly certId: string
+	readonly subject: { readonly platform: string; readonly externalId: string }
+	readonly defVersion: number
+	readonly layout: CardLayout
+	/** Each part is one complete `<certrev-card>` host holding a declarative shadow root. */
+	readonly parts: Partial<Record<CardPartName, string>>
+	/** CertREV's own certificate and expert-profile dialogs: complete hosts, identical on every brand and CMS. */
+	readonly dialogs: { readonly expert?: string; readonly certificate?: string }
+	readonly assets: {
+		/** A complete `<style data-certrev-card-head>` fragment: the pill's fixed box and the fonts. */
+		readonly head: string
+		/** The hosted runtime (dialogs, revalidate, polyfill), present once CertREV serves it. */
+		readonly runtime?: { readonly src: string; readonly integrity: string }
+	}
+}
+
+/** The signed binding of a contract-1 card, as the verified `content.faceDigest` carries it. */
+export interface CardBinding {
+	readonly contract: 1
+	readonly defVersion: number
+	readonly doc: string
+}
+
+const SHA256_HEX = /^[0-9a-f]{64}$/
+const SRI = /^(?:sha256|sha384|sha512)-[A-Za-z0-9+/]+={0,2}(?:\s+(?:sha256|sha384|sha512)-[A-Za-z0-9+/]+={0,2})*$/
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v)
+const isString = (v: unknown): v is string => typeof v === 'string'
+
+/**
+ * The signed binding, judged:
+ *  - `null`: the verified content's digest has no `contract` key (or there is no digest): not a contract-1 placement,
+ *    so the card paints what 1.3.1 paints;
+ *  - a `CardBinding`: `{ v: 1, contract: 1 }` with a non-negative integer `defVersion` and a 64-char lowercase hex `doc`
+ *    (`html` and `css` may be there or not; this client does not read them);
+ *  - `'unsupported'`: a `contract` key with anything else (another contract, a malformed binding). Fails closed.
+ */
+export function acceptedCardBinding(content: CertContent | null | undefined): CardBinding | 'unsupported' | null {
+	const digest: unknown = (content as { faceDigest?: unknown } | null | undefined)?.faceDigest
+	// Own keys via `Object.keys`, not `Object.hasOwn`: this runs for every verified placement, in browsers 1.3.1 painted in
+	// (Safari before 15.4 has no `Object.hasOwn`; break-it B3).
+	if (!isRecord(digest) || !Object.keys(digest).includes('contract')) return null
+	const { v, contract, defVersion, doc } = digest
+	if (v !== 1 || contract !== CARD_CONTRACT_VERSION) return 'unsupported'
+	if (typeof defVersion !== 'number' || !Number.isSafeInteger(defVersion) || defVersion < 0) return 'unsupported'
+	if (!isString(doc) || !SHA256_HEX.test(doc)) return 'unsupported'
+	return { contract: CARD_CONTRACT_VERSION, defVersion, doc }
+}
+
+/**
+ * The runtime's `src` must be CertREV's: an `https:` URL on `certrev.com` or one of its subdomains, with no credentials
+ * and no port (the rule the delivery marker's origin follows). Anything else is not a runtime, so no document, even one
+ * planted in a page's record, can make the card load a script from elsewhere (break-it B7).
+ */
+function isCertrevRuntimeUrl(value: unknown): boolean {
+	if (!isString(value)) return false
+	try {
+		const url = new URL(value)
+		const host = url.hostname.toLowerCase()
+		return (
+			url.protocol === 'https:' &&
+			!url.username &&
+			!url.password &&
+			!url.port &&
+			(host === 'certrev.com' || host.endsWith('.certrev.com'))
+		)
+	} catch {
+		return false
+	}
+}
+
+/**
+ * The served document, shape-checked for what this client reads: the object itself when it is a contract-1 card
+ * document, else null. Nothing is copied or normalised (the digest covers the object as served). Parts it does not
+ * know are left in place (they are part of the digest) and never printed.
+ */
+export function parseCardDocument(value: unknown): CardDocumentV1 | null {
+	if (!isRecord(value)) return null
+	const { contract, kind, certId, subject, defVersion, layout, parts, dialogs, assets } = value
+	if (contract !== CARD_CONTRACT_VERSION || kind !== 'certrev.card' || !isString(certId)) return null
+	if (!isRecord(subject) || !isString(subject.platform) || !isString(subject.externalId)) return null
+	if (typeof defVersion !== 'number' || !Number.isSafeInteger(defVersion) || defVersion < 0) return null
+	if (!isString(layout) || !CARD_LAYOUTS.includes(layout)) return null
+	if (!isRecord(parts)) return null
+	for (const name of CARD_PART_NAMES) if (parts[name] !== undefined && !isString(parts[name])) return null
+	if (!isRecord(dialogs)) return null
+	if (dialogs.expert !== undefined && !isString(dialogs.expert)) return null
+	if (dialogs.certificate !== undefined && !isString(dialogs.certificate)) return null
+	if (!isRecord(assets) || !isString(assets.head)) return null
+	if (assets.runtime !== undefined) {
+		const runtime = assets.runtime
+		if (
+			!isRecord(runtime) ||
+			!isCertrevRuntimeUrl(runtime.src) ||
+			!isString(runtime.integrity) ||
+			!SRI.test(runtime.integrity)
+		) {
+			return null
+		}
+	}
+	return value as unknown as CardDocumentV1
+}
+
+/** Lowercase hex sha256 of a document's RFC 8785 bytes; null when it cannot be canonicalized or hashed. */
+export async function cardDocumentDigest(card: unknown): Promise<string | null> {
+	let canonical: string
+	try {
+		canonical = canonicalizeJson(card)
+	} catch {
+		return null
+	}
+	try {
+		return await sha256HexUtf8(canonical)
+	} catch {
+		return null
+	}
+}
+
+/** One document's digest: the pending hash, and its answer once settled (null never matches). */
+export interface CardDigestMemo {
+	readonly pending: Promise<string | null>
+	settled?: { readonly digest: string | null }
+}
+
+/** How many documents' digests are kept (insertion order; the oldest goes first). A page holds one or a few. */
+const CARD_DIGEST_MEMO_MAX = 32
+const cardDigestMemo = new Map<string, CardDigestMemo>()
+
+/**
+ * The memoized digest of one document, keyed by its canonical bytes (a seed parsed afresh from the page and the
+ * server's cached read of the same document share one entry). A document that cannot be canonicalized settles to null
+ * at once, without a key.
+ */
+export function cardDigestFor(card: unknown): CardDigestMemo {
+	let key: string
+	try {
+		key = canonicalizeJson(card)
+	} catch {
+		const failed: CardDigestMemo = { pending: Promise.resolve(null), settled: { digest: null } }
+		return failed
+	}
+	const known = cardDigestMemo.get(key)
+	if (known) return known
+	const fresh: CardDigestMemo = {
+		pending: sha256HexUtf8(key).then(
+			(digest) => {
+				fresh.settled = { digest }
+				return digest
+			},
+			() => {
+				fresh.settled = { digest: null }
+				return null
+			},
+		),
+	}
+	evictOldestSettled(cardDigestMemo, CARD_DIGEST_MEMO_MAX)
+	cardDigestMemo.set(key, fresh)
+	return fresh
+}
+
+/** Test seam: forget every document's digest (a new process). */
+export function forgetCardDigestsForTests(): void {
+	cardDigestMemo.clear()
+}
+
+/**
+ * The synchronous half of the check: the document binds this binding, payload and placement in everything but its
+ * bytes (contract, design version, certificate, and the Builder placement it was painted for).
+ */
+export function cardMatchesPlacement(
+	card: CardDocumentV1,
+	binding: CardBinding,
+	payload: CertPayload,
+	externalId: string,
+): boolean {
+	return (
+		card.contract === binding.contract &&
+		card.defVersion === binding.defVersion &&
+		card.certId === payload.certId &&
+		card.subject.platform === 'builder' &&
+		card.subject.externalId === externalId
+	)
+}
+
+/** The asynchronous half's verdict: the document's own digest is the signed one. */
+export function cardDigestMatches(digest: string | null, binding: CardBinding): boolean {
+	return digest !== null && digest === binding.doc
+}
+
+/** Both halves at once (for callers outside React): the served document is the one the verified envelope signs. */
+export async function cardBinds(
+	card: CardDocumentV1,
+	binding: CardBinding,
+	payload: CertPayload,
+	externalId: string,
+): Promise<boolean> {
+	if (!cardMatchesPlacement(card, binding, payload, externalId)) return false
+	return cardDigestMatches(await cardDigestFor(card).pending, binding)
+}
+
+/**
+ * The parts one Builder block prints, in page order. The saved design decides the layout (the block's `mode` is not
+ * read). A banner block prints its card (`top`) and its memo (`bottom`); a block whose `part` is `'header'` prints the
+ * card only, and one whose `part` is `'memo'` the memo only, so a split banner prints each part once. Outside the
+ * banner a `'memo'` block prints nothing and any other block the design's one part (the rail, the pill): a page that
+ * kept its split header and memo blocks after the brand chose a sidebar design shows one sidebar card, not two.
+ */
+export function cardPartsFor(card: CardDocumentV1, part: unknown): CardPartName[] {
+	let names: CardPartName[]
+	if (card.layout === 'banner') {
+		names = part === 'header' ? ['top'] : part === 'memo' ? ['bottom'] : ['top', 'bottom']
+	} else if (part === 'memo') {
+		names = []
+	} else {
+		names = card.layout === 'sidebar' ? ['rail'] : ['pill']
+	}
+	return names.filter((name) => typeof card.parts[name] === 'string')
+}
+
+function escapeAttribute(value: string): string {
+	return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+/** The runtime's tag, or '' when the document names none. */
+export function cardRuntimeTag(card: CardDocumentV1): string {
+	const runtime = card.assets.runtime
+	if (!runtime) return ''
+	return `<script src="${escapeAttribute(runtime.src)}" integrity="${escapeAttribute(runtime.integrity)}" crossorigin="anonymous" defer></script>`
+}
+
+/** Which of the document's parts is its first, in this order: the block holding it prints the page's assets. */
+const CARD_FIRST_PART_ORDER: readonly CardPartName[] = ['top', 'rail', 'pill', 'bottom']
+
+/**
+ * The document's first part: `top`, else `rail`, else `pill`, from the document's own parts (the lead's ruling on ADR
+ * 0001's head-once-per-page, relay 074dbd2c8ef3); `bottom` only for a document with none of those, so its head and
+ * dialogs always have a block to print them. Null for a document with no part.
+ */
+export function cardFirstPart(card: CardDocumentV1): CardPartName | null {
+	return CARD_FIRST_PART_ORDER.find((name) => typeof card.parts[name] === 'string') ?? null
+}
+
+/** Whether the block printing `names` prints the page's head fragment, dialogs and runtime: it holds the first part. */
+export function cardCarriesAssets(card: CardDocumentV1, names: readonly CardPartName[]): boolean {
+	const first = cardFirstPart(card)
+	return first !== null && names.includes(first)
+}
+
+/**
+ * 2.0.1: the page's CertREV graph, when the document carries one CertREV's server resolved for this placement
+ * (`card.jsonld.graph`: a complete JSON-LD object, every link and page fact filled in, an additive key under contract
+ * 1). Printed verbatim as `<script type="application/ld+json" data-certrev-graph ...>`, with every `<` written as
+ * `\u003c` so no value can close the element; '' when the document has no graph. The block never builds or edits the
+ * graph: what it says, and when it changes, is the server's.
+ */
+export function cardGraphTag(card: CardDocumentV1): string {
+	const jsonld = (card as unknown as { jsonld?: unknown }).jsonld
+	if (typeof jsonld !== 'object' || jsonld === null) return ''
+	const graph = (jsonld as { graph?: unknown }).graph
+	if (typeof graph !== 'object' || graph === null || Array.isArray(graph)) return ''
+	let json: string
+	try {
+		json = JSON.stringify(graph)
+	} catch {
+		return ''
+	}
+	const id = escapeAttribute(card.subject.externalId)
+	return `<script type="application/ld+json" data-certrev-graph="" data-certrev-platform="builder" data-certrev-external-id="${id}">${json.replace(/</g, '\\u003c')}</script>`
+}
+
+/**
+ * Exactly what a block prints inside its wrapper: its parts in page order and, only in the block holding the document's
+ * first part (`cardCarriesAssets`), the head fragment before them and both dialogs (expert, then certificate), the
+ * runtime's tag and (2.0.1) the page's graph after. So a split banner (a header block and a memo block) prints the head, the dialogs and the runtime
+ * once, in the header block, with no coordination between the blocks and with JavaScript off; the runtime finds a
+ * control's dialog anywhere on the page by its placement. Every byte but the runtime tag is the document's own.
+ */
+export function cardHtml(card: CardDocumentV1, names: readonly CardPartName[]): string {
+	let parts = ''
+	for (const name of names) parts += card.parts[name] ?? ''
+	if (!cardCarriesAssets(card, names)) return parts
+	const dialogs = (card.dialogs.expert ?? '') + (card.dialogs.certificate ?? '')
+	return card.assets.head + parts + dialogs + cardRuntimeTag(card) + cardGraphTag(card)
+}

package/src/builder/card-placement.ts

@@ -0,0 +1,208 @@
+/**
+ * 2.0.1: the card document's placement hints (`card.placement`, ADR 0001 §2), applied by the block in the browser, so
+ * CertREV can move a banner's card and memo on a Builder page with no new install (Owen: the reviewer up top, the memo
+ * at the end).
+ *
+ * A Builder page renders an entry as `[builder-content-id] > .builder-blocks > .builder-block`, one top-level block per
+ * block the editor placed; the CertREV block is one of them. A hint names where a part belongs among those blocks:
+ *
+ *  - `content-start`: before the first block; with `after: 'leading-media'`, after a first block that is only media
+ *    (an image, a picture, a video or an iframe, and no text);
+ *  - `after-byline`: after the block that holds the article's byline: an element marked `data-certrev-anchor="byline"`
+ *    first, else the first `[rel~="author"]`, `[itemprop="author"]`, `.byline`, `[class*="byline"]` or `address`;
+ *  - `before-references`: before the block that opens the references (a heading or label reading References, Sources,
+ *    Citations or Works cited, or an element whose id names references);
+ *  - `content-end`: after the last block;
+ *  - `pinned`, or any anchor this client does not know: where the editor put it.
+ * An anchor that the page does not have falls back to the hint's `else`, and then to where the editor put it.
+ *
+ * Only a banner's parts move (`top`, `bottom`): a sidebar's rail floats beside the copy from the block the editor
+ * placed, and a floating pill is pinned to the viewport. A part moves into a holder (`data-certrev-placed`) inserted
+ * among the top-level blocks; the block itself stays where it was, with the card's head, dialogs and runtime.
+ *
+ * WHEN: in the browser only, after the page has loaded and React has hydrated (two frames after `load`), never during
+ * a render or a hydration, and never in Builder's visual editor or preview (`builder.frameEditing`,
+ * `builder.preview`, `__builder_editing__` in the address): an editor sees each block where it placed it. With JavaScript off, and until then, every part is where the editor put it. A card React
+ * prints again (a new document) or unmounts takes its moved parts with it first, so a part is never printed twice.
+ */
+
+import type { CardDocumentV1, CardPartName } from './card-contract.js'
+
+const MOVABLE: readonly CardPartName[] = ['top', 'bottom']
+const PLACED_ATTRIBUTE = 'data-certrev-placed'
+const MEDIA = 'img, picture, video, iframe, svg'
+const BYLINE_MARKED = '[data-certrev-anchor="byline"]'
+const BYLINE = '[rel~="author"], [itemprop="author"], .byline, [class*="byline"], address'
+const REFERENCES_TEXT = /^\s*(references|sources|citations|works cited)\s*:?\s*$/i
+const REFERENCES_LABEL = 'h1, h2, h3, h4, h5, h6, strong, b, p, summary, dt, figcaption'
+
+interface Hint {
+	readonly anchor?: unknown
+	readonly after?: unknown
+	readonly else?: unknown
+}
+
+/** Where a part goes: before or after one of the top-level blocks, or to the end of the column. */
+type Target = { readonly before: Element } | { readonly after: Element } | { readonly end: Element }
+
+function hintFor(card: CardDocumentV1, part: CardPartName): Hint | null {
+	const placement = (card as unknown as { placement?: unknown }).placement
+	if (typeof placement !== 'object' || placement === null) return null
+	const hint = (placement as Record<string, unknown>)[part]
+	return typeof hint === 'object' && hint !== null ? (hint as Hint) : null
+}
+
+/** A block that is only media: an image (or picture, video, iframe, svg) and no text of its own. */
+function mediaOnly(block: Element): boolean {
+	return block.querySelector(MEDIA) !== null && (block.textContent ?? '').trim() === ''
+}
+
+function blockOf(node: Element, blocks: readonly Element[]): Element | null {
+	return blocks.find((block) => block === node || block.contains(node)) ?? null
+}
+
+function referencesBlock(blocks: readonly Element[]): Element | null {
+	for (const block of blocks) {
+		if (/references|sources|citations/i.test(block.id)) return block
+		if (block.querySelector('[id*="references" i], [id*="sources" i], [id*="citations" i]')) return block
+		for (const label of Array.from(block.querySelectorAll(REFERENCES_LABEL))) {
+			if (REFERENCES_TEXT.test(label.textContent ?? '')) return block
+		}
+	}
+	return null
+}
+
+function bylineBlock(root: Element, blocks: readonly Element[], own: Element): Element | null {
+	for (const selector of [BYLINE_MARKED, BYLINE]) {
+		for (const node of Array.from(root.querySelectorAll(selector))) {
+			const block = blockOf(node, blocks)
+			if (block && block !== own) return block
+		}
+	}
+	return null
+}
+
+/** One anchor, resolved among the top-level blocks other than the card's own; null when the page has no such place. */
+function resolveAnchor(
+	anchor: unknown,
+	hint: Hint,
+	root: Element,
+	column: Element,
+	blocks: readonly Element[],
+	own: Element,
+): Target | null {
+	const others = blocks.filter((block) => block !== own)
+	switch (anchor) {
+		case 'content-start': {
+			const first = others[0]
+			if (!first) return null
+			return hint.after === 'leading-media' && mediaOnly(first) ? { after: first } : { before: first }
+		}
+		case 'after-byline': {
+			const byline = bylineBlock(root, blocks, own)
+			return byline ? { after: byline } : null
+		}
+		case 'before-references': {
+			const references = referencesBlock(others)
+			return references ? { before: references } : null
+		}
+		case 'content-end':
+			return others.length > 0 ? { end: column } : null
+		default:
+			return null
+	}
+}
+
+/** True when the card's own block already sits where `target` would put the part. */
+function alreadyThere(target: Target, own: Element, blocks: readonly Element[]): boolean {
+	const index = blocks.indexOf(own)
+	if ('before' in target) return blocks[index + 1] === target.before || (index === 0 && blocks[0] === target.before)
+	if ('after' in target) return blocks[index - 1] === target.after
+	return index === blocks.length - 1
+}
+
+/**
+ * Apply the document's hints to the parts this block printed; returns the undo. A no-op, and a no-op undo, outside a
+ * Builder page.
+ *
+ * The undo puts each moved part back in the block's wrapper, unless the wrapper already holds that part again (React
+ * printed a new document into it, which it does before any effect cleanup runs) or has left the page (the card
+ * unmounted): then the moved part is dropped with its holder. Either way no part is ever printed twice.
+ */
+export function applyCardPlacement(wrapper: Element, card: CardDocumentV1, names: readonly CardPartName[]): () => void {
+	const root = wrapper.closest('[builder-content-id]')
+	const column = root?.querySelector(':scope > .builder-blocks') ?? null
+	if (!root || !column) return () => {}
+	const blocks = Array.from(column.children).filter((child) => child.classList.contains('builder-block'))
+	const own = blockOf(wrapper, blocks)
+	if (!own) return () => {}
+	const placed: {
+		readonly holder: Element
+		readonly host: Element
+		readonly part: CardPartName
+		readonly next: Node | null
+	}[] = []
+	for (const part of names) {
+		if (!MOVABLE.includes(part)) continue
+		const hint = hintFor(card, part)
+		if (!hint) continue
+		const host = wrapper.querySelector(`:scope > certrev-card[data-certrev-part="${part}"]`)
+		if (!host) continue
+		const target =
+			resolveAnchor(hint.anchor, hint, root, column, blocks, own) ??
+			(hint.else !== undefined ? resolveAnchor(hint.else, hint, root, column, blocks, own) : null)
+		if (!target || alreadyThere(target, own, blocks)) continue
+		const next = host.nextSibling
+		const holder = (wrapper.ownerDocument ?? document).createElement('div')
+		holder.setAttribute(PLACED_ATTRIBUTE, part)
+		holder.setAttribute('data-certrev-face', 'card')
+		if ('before' in target) column.insertBefore(holder, target.before)
+		else if ('after' in target) column.insertBefore(holder, target.after.nextSibling)
+		else column.appendChild(holder)
+		holder.appendChild(host)
+		placed.push({ holder, host, part, next })
+	}
+	return () => {
+		for (const { holder, host, part, next } of placed) {
+			const printedAgain = wrapper.querySelector(`:scope > certrev-card[data-certrev-part="${part}"]`) !== null
+			if (wrapper.isConnected && !printedAgain) {
+				wrapper.insertBefore(host, next && next.parentNode === wrapper ? next : null)
+			}
+			holder.remove()
+		}
+	}
+}
+
+/** Builder's visual editor and preview load the page with one of these in its address. */
+const EDITOR_PARAMS = ['builder.frameEditing', 'builder.preview', '__builder_editing__']
+
+/** True in Builder's visual editor or preview, where blocks stay where the editor placed them. */
+export function inBuilderEditor(search: string = typeof location === 'undefined' ? '' : location.search): boolean {
+	const params = new URLSearchParams(search)
+	return EDITOR_PARAMS.some((name) => params.has(name))
+}
+
+/**
+ * Run `apply` once the page has loaded and hydrated (two frames after `load`); returns a cancel that also undoes what
+ * `apply` did. Never runs in Builder's editor or preview.
+ */
+export function afterPageSettles(apply: () => () => void): () => void {
+	if (inBuilderEditor()) return () => {}
+	let undo: (() => void) | null = null
+	let cancelled = false
+	const run = () => {
+		if (cancelled) return
+		requestAnimationFrame(() =>
+			requestAnimationFrame(() => {
+				if (!cancelled) undo = apply()
+			}),
+		)
+	}
+	if (document.readyState === 'complete') run()
+	else window.addEventListener('load', run, { once: true })
+	return () => {
+		cancelled = true
+		window.removeEventListener('load', run)
+		undo?.()
+	}
+}

package/src/builder/card-report.ts

@@ -0,0 +1,126 @@
+/**
+ * The Builder card's fallback report (2.0.0; 2.0.1 adds the beacon): one structured event every time a placement does
+ * not print a card, so no fallback is silent.
+ *
+ *  - In the browser: `CustomEvent('certrev:card-fallback', { detail })` on `document`, once per placement and reason per
+ *    page, which a brand (or CertREV's own replica) can listen for; and (2.0.1) the same fallback to CertREV as a beacon
+ *    (`card-beacon.ts`: no reader data, at most three per page).
+ *  - On a server: one `console.warn` line, `[certrev] card_fallback {json}`, per render that takes the fallback; and
+ *    (2.0.1) a beacon, each placement and reason at most once an hour per process.
+ *
+ * The same reason rides the placement's `'none'` record on the page (`ssr-seed.ts`), so a capture can read it too.
+ *
+ * Reasons (2.0.1: every one of them prints NOTHING; no fallback ever prints the block's own export-time options):
+ *  - `card_missing`: a contract-1 placement (the signed binding says `contract: 1`) with no card in the response;
+ *  - `card_verify_failed`: a card that is malformed, or does not hash to the signed digest, or names another design
+ *    version, certificate or placement;
+ *  - `card_unsupported_contract`: a signed binding with a `contract` this client does not print (a newer major);
+ *  - `card_pin_mismatch`: CertREV's replica pinned a design version the signed card was not painted for;
+ *  - `unknown_key`: the envelope's kid is neither baked nor in the origin's signed published key set;
+ *  - `envelope_verify_failed` (2.0.1): the envelope itself did not verify (a bad signature, an algorithm this client does
+ *    not accept, another platform, content that drifted from what was signed, a payload version it cannot read);
+ *  - `delivery_unreachable`: CertREV could not be reached and no verified answer was cached inside the stale window
+ *    (2.0.1: when CertREV answered with an HTTP error, the beacon says `http_5xx` or `http_4xx` and carries `status`);
+ *  - `no_marker`: a block with no delivery marker (an entry exported before 1.1.0, or a block dropped in by hand);
+ *  - `marker_invalid`: a delivery marker this client does not accept, or a block with no Builder entry to read for;
+ *  - `client_read_off`: a block mounted in the browser with no server answer while the brand turned `clientRead` off.
+ */
+
+import { type BeaconOutcome, sendBrowserBeacon, sendServerBeacon } from './card-beacon.js'
+
+export const CARD_FALLBACK_EVENT = 'certrev:card-fallback'
+
+export type CardFallbackReason =
+	| 'card_missing'
+	| 'card_verify_failed'
+	| 'card_unsupported_contract'
+	| 'card_pin_mismatch'
+	| 'unknown_key'
+	| 'envelope_verify_failed'
+	| 'delivery_unreachable'
+	| 'no_marker'
+	| 'marker_invalid'
+	| 'client_read_off'
+
+export const CARD_FALLBACK_REASONS: readonly CardFallbackReason[] = [
+	'card_missing',
+	'card_verify_failed',
+	'card_unsupported_contract',
+	'card_pin_mismatch',
+	'unknown_key',
+	'envelope_verify_failed',
+	'delivery_unreachable',
+	'no_marker',
+	'marker_invalid',
+	'client_read_off',
+]
+
+export interface CardFallbackDetail {
+	readonly reason: CardFallbackReason
+	readonly platform: 'builder'
+	readonly externalId: string
+	/** The certificate, when the envelope verified far enough to name it. */
+	readonly certId?: string
+	/** 2.0.1: with `delivery_unreachable`, the HTTP status CertREV answered with, when it answered. */
+	readonly status?: number
+}
+
+/** The beacon's outcome for each reason. */
+const OUTCOMES: Readonly<Record<CardFallbackReason, BeaconOutcome>> = {
+	card_missing: 'other',
+	card_verify_failed: 'verify_failed',
+	card_unsupported_contract: 'unsupported',
+	card_pin_mismatch: 'other',
+	unknown_key: 'verify_failed',
+	envelope_verify_failed: 'verify_failed',
+	delivery_unreachable: 'unreachable',
+	no_marker: 'other',
+	marker_invalid: 'other',
+	client_read_off: 'other',
+}
+
+/** Placement and reason pairs already reported on this page (browser only), and the document address they belong to. */
+const reportedOnPage = new Set<string>()
+let reportedPage: string | null = null
+
+/** The beacon event for one fallback: an HTTP error says which, with its status. */
+function fallbackEvent(detail: CardFallbackDetail) {
+	const status = detail.status
+	const outcome: BeaconOutcome =
+		status !== undefined && status >= 500
+			? 'http_5xx'
+			: status !== undefined && status >= 400
+				? 'http_4xx'
+				: OUTCOMES[detail.reason]
+	return { kind: 'fallback' as const, reason: detail.reason, outcome, ...(status === undefined ? {} : { status }) }
+}
+
+/**
+ * Report one fallback in the browser: the event and the beacon, once per placement and reason per page. `origin` is the
+ * delivery origin the block reads (absent for a block with no accepted marker: CertREV's production origin).
+ */
+export function reportCardFallbackInBrowser(detail: CardFallbackDetail, origin?: string): void {
+	if (typeof document === 'undefined' || typeof CustomEvent !== 'function') return
+	const page = typeof location !== 'undefined' ? `${location.pathname}${location.search}` : ''
+	if (page !== reportedPage) {
+		reportedPage = page
+		reportedOnPage.clear()
+	}
+	const key = `${detail.externalId}|${detail.reason}`
+	if (reportedOnPage.has(key)) return
+	reportedOnPage.add(key)
+	document.dispatchEvent(new CustomEvent(CARD_FALLBACK_EVENT, { detail }))
+	sendBrowserBeacon(origin, detail.externalId, fallbackEvent(detail))
+}
+
+/** Report one fallback on a server: one structured console line, and the beacon (at most once an hour per process). */
+export function reportCardFallbackOnServer(detail: CardFallbackDetail, origin?: string): void {
+	console.warn(`[certrev] card_fallback ${JSON.stringify(detail)}`)
+	sendServerBeacon(origin, detail.externalId, fallbackEvent(detail))
+}
+
+/** Test seam: forget what this page reported (a new page). */
+export function forgetCardReportsForTests(): void {
+	reportedOnPage.clear()
+	reportedPage = null
+}