@certrev/cert-block 2.0.0 → 2.0.2

package/src/builder/card-beacon.ts

@@ -0,0 +1,201 @@
+/**
+ * The Builder card's beacon (2.0.1): what the card tells CertREV about itself, so a card that does not print on a brand's
+ * page is seen by CertREV and not only by the brand's console.
+ *
+ * One `POST <delivery origin>/api/cert/v1/beacon` per event, a `text/plain` JSON body (a CORS simple request, so no
+ * preflight; the origin is the delivery origin the page's `connect-src` already allows, so no new CSP source):
+ *
+ *     { v: 1, client: 'cert-block', clientVersion, contract, platform: 'builder', externalId, family,
+ *       events: [{ kind: 'fallback' | 'health', reason, outcome, status? }] }
+ *
+ * What it never carries: cookies (`credentials: 'omit'`), the page's address (`referrerPolicy: 'no-referrer'`) or text, the reader's user agent (only a
+ * coarse family: chromium, webkit, gecko, other, or server), or anything the reader typed. `externalId` is the Builder
+ * entry the block renders in, which the brand's page already sends to CertREV when it reads the card.
+ *
+ * How much: in a browser, every fallback (each placement and reason once per page, `card-report.ts`) and one health
+ * event per page in a hundred, at most three beacons per page (a page is a document address: an in-app navigation to
+ * another article starts a new budget); on a server, each placement, reason and origin at most
+ * once an hour per process, with a short deadline, never awaited. A beacon that fails is dropped: it never retries,
+ * never stores anything and never changes what the card prints.
+ */
+
+import { CARD_CONTRACT_VERSION } from './card-contract.js'
+import { CERT_BLOCK_VERSION } from './version.js'
+
+export const BEACON_PATH = '/api/cert/v1/beacon'
+/** Where a block with no accepted delivery marker reports: CertREV's production delivery origin. */
+export const DEFAULT_BEACON_ORIGIN = 'https://portal.certrev.com'
+/** The most beacons one page sends. */
+export const BEACON_MAX_PER_PAGE = 3
+/** The share of page views that send one health event. */
+export const BEACON_HEALTH_SAMPLE = 0.01
+/** A server sends one beacon per placement, reason and origin at most this often. */
+export const BEACON_SERVER_INTERVAL_MS = 3_600_000
+const SERVER_MAX_KEYS = 500
+const SERVER_TIMEOUT_MS = 1_500
+
+export type BeaconOutcome = 'ok' | 'unreachable' | 'http_4xx' | 'http_5xx' | 'verify_failed' | 'unsupported' | 'other'
+export type BeaconFamily = 'chromium' | 'webkit' | 'gecko' | 'server' | 'other'
+
+export interface BeaconEvent {
+	readonly kind: 'fallback' | 'health'
+	readonly reason: string
+	readonly outcome: BeaconOutcome
+	/** The HTTP status CertREV answered with, when a read failed on one (outcome `http_4xx` or `http_5xx`). */
+	readonly status?: number
+}
+
+export interface CardBeacon {
+	readonly v: 1
+	readonly client: 'cert-block'
+	readonly clientVersion: string
+	readonly contract: number
+	readonly platform: 'builder'
+	readonly externalId?: string
+	readonly family: BeaconFamily
+	readonly events: readonly BeaconEvent[]
+}
+
+/** How a beacon leaves: `url`, the JSON body, and where it is sent from. */
+export type BeaconTransport = (url: string, body: string, where: 'browser' | 'server') => void
+
+/** The transport the card ships with: `fetch`, never awaited, never throwing (exported for CertREV's replica harness). */
+export const fetchBeaconTransport: BeaconTransport = (url, body, where) => {
+	try {
+		const send = globalThis.fetch
+		if (typeof send !== 'function') return
+		const init: RequestInit = {
+			method: 'POST',
+			body,
+			headers: { 'content-type': 'text/plain;charset=UTF-8' },
+			credentials: 'omit',
+			// Never the reader's page address, whatever the storefront's Referrer-Policy.
+			referrerPolicy: 'no-referrer',
+			...(where === 'browser'
+				? // Opaque and kept alive: no CORS read of the answer, and it outlives a navigation away.
+					{ mode: 'no-cors' as const, keepalive: true }
+				: typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function'
+					? { signal: AbortSignal.timeout(SERVER_TIMEOUT_MS) }
+					: {}),
+		}
+		void send(url, init).catch(() => {})
+	} catch {
+		// A beacon never throws into a render.
+	}
+}
+
+let transport: BeaconTransport = fetchBeaconTransport
+let sentOnPage = 0
+let healthDrawn: boolean | null = null
+/** The document address the page budget belongs to. */
+let budgetPage: string | null = null
+
+/** Start a new page budget when the document's address changed (an in-app navigation). */
+function samePageBudget(): void {
+	const page = typeof location !== 'undefined' ? `${location.pathname}${location.search}` : ''
+	if (page === budgetPage) return
+	budgetPage = page
+	sentOnPage = 0
+	healthDrawn = null
+}
+const sentOnServer = new Map<string, number>()
+let random: () => number = Math.random
+let clock: () => number = Date.now
+
+/** The coarse browser family, from the user agent; nothing else of it is kept. */
+export function browserFamily(userAgent: string): BeaconFamily {
+	if (/Firefox\//.test(userAgent)) return 'gecko'
+	if (/(Chrome|Chromium|CriOS|Edg)\//.test(userAgent)) return 'chromium'
+	if (/AppleWebKit\//.test(userAgent)) return 'webkit'
+	return 'other'
+}
+
+/** The delivery origin a beacon goes to: an `https:` origin on certrev.com, else CertREV's production origin. */
+function beaconOrigin(baseUrl: string | undefined): string {
+	if (!baseUrl) return DEFAULT_BEACON_ORIGIN
+	try {
+		const url = new URL(baseUrl)
+		const host = url.hostname
+		if (url.protocol === 'https:' && (host === 'certrev.com' || host.endsWith('.certrev.com'))) return url.origin
+	} catch {
+		// Fall through.
+	}
+	return DEFAULT_BEACON_ORIGIN
+}
+
+export function beaconBody(externalId: string, events: readonly BeaconEvent[], family: BeaconFamily): CardBeacon {
+	return {
+		v: 1,
+		client: 'cert-block',
+		clientVersion: CERT_BLOCK_VERSION,
+		contract: CARD_CONTRACT_VERSION,
+		platform: 'builder',
+		...(externalId ? { externalId } : {}),
+		family,
+		events,
+	}
+}
+
+/** Send one event from the browser, within the page's budget. */
+export function sendBrowserBeacon(baseUrl: string | undefined, externalId: string, event: BeaconEvent): void {
+	if (typeof document === 'undefined') return
+	samePageBudget()
+	if (sentOnPage >= BEACON_MAX_PER_PAGE) return
+	sentOnPage++
+	const userAgent = typeof navigator !== 'undefined' ? String(navigator.userAgent ?? '') : ''
+	const body = beaconBody(externalId, [event], browserFamily(userAgent))
+	transport(`${beaconOrigin(baseUrl)}${BEACON_PATH}`, JSON.stringify(body), 'browser')
+}
+
+/** Send one health event from the browser on one page view in a hundred (drawn once per page). */
+export function maybeSendBrowserHealth(baseUrl: string | undefined, externalId: string): void {
+	if (typeof document === 'undefined') return
+	samePageBudget()
+	if (healthDrawn === null) healthDrawn = random() < BEACON_HEALTH_SAMPLE
+	if (!healthDrawn) return
+	healthDrawn = false
+	sendBrowserBeacon(baseUrl, externalId, { kind: 'health', reason: 'card_printed', outcome: 'ok' })
+}
+
+/** Send one event from a server: each placement, reason and origin at most once an hour per process. */
+export function sendServerBeacon(baseUrl: string | undefined, externalId: string, event: BeaconEvent): void {
+	const origin = beaconOrigin(baseUrl)
+	const key = `${origin}|${externalId}|${event.kind}|${event.reason}`
+	const now = clock()
+	const last = sentOnServer.get(key)
+	if (last !== undefined && now - last < BEACON_SERVER_INTERVAL_MS) return
+	sentOnServer.delete(key)
+	if (sentOnServer.size >= SERVER_MAX_KEYS) {
+		const oldest = sentOnServer.keys().next().value
+		if (oldest !== undefined) sentOnServer.delete(oldest)
+	}
+	sentOnServer.set(key, now)
+	transport(`${origin}${BEACON_PATH}`, JSON.stringify(beaconBody(externalId, [event], 'server')), 'server')
+}
+
+/**
+ * Test seam: replace the transport (and the sampling draw and clock) and forget the page's and the process's budget.
+ * Returns a restore.
+ */
+export function setCardBeaconForTests(
+	overrides: { transport?: BeaconTransport; random?: () => number; now?: () => number } = {},
+): () => void {
+	const previous = { transport, random, clock }
+	transport = overrides.transport ?? (() => {})
+	random = overrides.random ?? (() => 1)
+	clock = overrides.now ?? Date.now
+	forgetCardBeaconsForTests()
+	return () => {
+		transport = previous.transport
+		random = previous.random
+		clock = previous.clock
+	}
+}
+
+/** Test seam: a new page and a new process. */
+export function forgetCardBeaconsForTests(): void {
+	sentOnPage = 0
+	healthDrawn = null
+	budgetPage = null
+	sentOnServer.clear()
+}

package/src/builder/card-contract.ts

@@ -298,10 +298,32 @@ export function cardCarriesAssets(card: CardDocumentV1, names: readonly CardPart
 	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) and the
- * runtime's tag after. So a split banner (a header block and a memo block) prints the head, the dialogs and the runtime
+ * 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.
  */
@@ -310,5 +332,5 @@ export function cardHtml(card: CardDocumentV1, names: readonly CardPartName[]):
 	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)
+	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

@@ -1,25 +1,33 @@
 /**
- * The Builder card's fallback report (2.0.0): one structured event every time a placement does not print the card
- * CertREV served, so no fallback is silent.
+ * 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. A brand (or CertREV's own replica) listens for it; the card itself sends nothing anywhere: no beacon, no
- *    request, no storage.
- *  - On a server: one `console.warn` line, `[certrev] card_fallback {json}`, per render that takes the fallback.
+ *    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:
+ * 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;
+ *  - `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;
- *  - `delivery_unreachable`: CertREV could not be reached, so the block's own options face was painted (1.2.0's
- *    deliberate fallback, unchanged, now reported).
+ *  - `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 =
@@ -28,7 +36,24 @@ export type CardFallbackReason =
 	| '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
@@ -36,26 +61,66 @@ export interface CardFallbackDetail {
 	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). */
+/** 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
 
-/** Report one fallback in the browser: the event, once per placement and reason per page. */
-export function reportCardFallbackInBrowser(detail: CardFallbackDetail): void {
+/** 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. */
-export function reportCardFallbackOnServer(detail: CardFallbackDetail): void {
+/** 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
 }