@certrev/cert-block 1.0.3 → 1.1.0

package/src/components/render-cert-block.ts

@@ -66,6 +66,15 @@
 
 import { escapeAttribute, escapeHtml, safeHttpUrl } from './escape.js'
 import { dedupeCredential, formatDate } from './format.js'
+import {
+	MEMO_ATTR,
+	MEMO_COLLAPSED_LINES,
+	MEMO_EXPAND_LABEL,
+	MEMO_TEXT_ATTR,
+	MEMO_TOGGLE_ATTR,
+	memoCollapses,
+	NARROW_VIEWPORT,
+} from './memo-toggle.js'
 import { CERTREV_LINK_REL } from './rel.js'
 import {
 	CERT_SCOPE_LINE,
@@ -165,6 +174,15 @@ export interface RenderCertBlockInput {
 	 * Ignored outside banner mode.
 	 */
 	readonly part?: 'full' | 'header' | 'memo'
+	/**
+	 * 1.1.0: the PHONE face. ABSENT ⇒ byte-identical to 1.0.3. `true` ⇒ at `NARROW_VIEWPORT` or
+	 * narrower the banner header stacks its author and reviewer columns, and a long memo
+	 * (`memoCollapses`) is clamped to `MEMO_COLLAPSED_LINES` lines behind a native toggle
+	 * (`memo-toggle.ts`) on every face that paints one. Wider viewports paint the same card as
+	 * without it. The Builder card's envelope face sets it; the options path and every other
+	 * surface leave it off.
+	 */
+	readonly responsive?: boolean
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -267,6 +285,77 @@ function showsCompensationCue(facts: CertBlockFacts, placed: PlacedTest): boolea
 const STAMP_LINK_STYLE =
 	'font-family:var(--font-mono);font-size:10.5px;font-weight:500;letter-spacing:.14em;text-transform:uppercase;color:var(--navy);text-decoration:none;cursor:pointer;'
 
+// ─────────────────────────────────────────────────────────────────────────────
+// The PHONE face (1.1.0, `responsive`): one scoped stylesheet per root, and the
+// collapsible memo markup `memo-toggle.ts` flips
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The phone rules, scoped to a responsive root so a host page's other markup is never touched.
+ * Every rule lives inside the media query: a desktop viewport, or a host that strips the
+ * `<style>`, paints exactly the 1.0.3 card (the toggle stays hidden by its inline `display:none`,
+ * which only the `!important` rule here overrides).
+ */
+const RESPONSIVE_STYLE =
+	`<style>@media ${NARROW_VIEWPORT}{` +
+	`.certrev-cert[data-certrev-responsive] [data-certrev-stack]{grid-template-columns:1fr!important}` +
+	`.certrev-cert[data-certrev-responsive] [${MEMO_ATTR}="collapsed"] [${MEMO_TEXT_ATTR}]{display:-webkit-box;-webkit-box-orient:vertical;-webkit-line-clamp:${MEMO_COLLAPSED_LINES};line-clamp:${MEMO_COLLAPSED_LINES};overflow:hidden}` +
+	`.certrev-cert[data-certrev-responsive] [${MEMO_TOGGLE_ATTR}]{display:inline-flex!important}` +
+	`}</style>`
+
+/**
+ * The memo toggle: a native button (keyboard and screen reader for free), a 44px touch target,
+ * styled as the memo footer's stamp links. Hidden INLINE rather than with `hidden`, so a host
+ * stylesheet's `[hidden]{display:none!important}` cannot pin it shut on a phone.
+ */
+const MEMO_TOGGLE_STYLE =
+	'display:none;align-items:center;min-height:44px;padding:0;margin:0;border:0;background:none;cursor:pointer;font-family:var(--font-mono);font-size:10.5px;font-weight:700;letter-spacing:.14em;text-transform:uppercase;color:var(--navy);text-decoration:underline;text-underline-offset:3px;'
+
+/** A stable short id for the memo text (the toggle's `aria-controls`); FNV-1a, base 36. */
+function memoId(seed: string): string {
+	let h = 0x811c9dc5
+	for (let i = 0; i < seed.length; i++) {
+		h ^= seed.charCodeAt(i)
+		h = Math.imul(h, 0x01000193)
+	}
+	return `certrev-memo-${(h >>> 0).toString(36)}`
+}
+
+/** The attributes and toggle a collapsible memo adds; all empty when it does not collapse. */
+interface MemoCollapse {
+	/** On the box that holds the memo text and its toggle: the state. */
+	readonly box: string
+	/** On the memo text element: its id and the clamp hook. */
+	readonly text: string
+	readonly toggle: string
+}
+
+const NO_MEMO_COLLAPSE: MemoCollapse = { box: '', text: '', toggle: '' }
+
+/**
+ * Collapsed by default: the phone rule clamps the text, and the desktop never reads the state.
+ * The clamp is visual only, so a screen reader reads the whole memo in either state and hears
+ * the toggle as "Read the full memo, button, collapsed".
+ */
+function memoCollapse(facts: CertBlockFacts, responsive: boolean, mode: CertBlockLayout): MemoCollapse {
+	if (!responsive || !memoCollapses(facts.memo)) return NO_MEMO_COLLAPSE
+	const id = memoId(`${mode}\n${facts.certificateUrl}\n${facts.memo}`)
+	return {
+		box: ` ${MEMO_ATTR}="collapsed"`,
+		text: ` id="${id}" ${MEMO_TEXT_ATTR}`,
+		toggle:
+			`<button type="button" ${MEMO_TOGGLE_ATTR} aria-expanded="false" aria-controls="${id}" ` +
+			`style="${MEMO_TOGGLE_STYLE}">${MEMO_EXPAND_LABEL}</button>`,
+	}
+}
+
+/** The sidebar/custom memo quote, collapsible on a phone. */
+function memoQuote(facts: CertBlockFacts, responsive: boolean, mode: CertBlockLayout): string {
+	const collapse = memoCollapse(facts, responsive, mode)
+	const quote = `<blockquote${collapse.text} style="margin:16px 0 0;padding-left:16px;border-left:3px solid var(--ba,#0a1b3f);font-size:15px;line-height:1.5;color:var(--cr-ink-soft);white-space:pre-line;">${escapeHtml(facts.memo)}</blockquote>`
+	return collapse.toggle ? `<div${collapse.box}>${quote}${collapse.toggle}</div>` : quote
+}
+
 /** A round avatar tile with the given initials. */
 function avatar(text: string, size: number, fontSize: number): string {
 	return (
@@ -394,13 +483,22 @@ function rootStyle(theme: ResolvedBlockTheme): string {
 	].join(';')
 }
 
-function root(mode: CertBlockLayout, theme: ResolvedBlockTheme, inner: string, face?: CertBlockFace): string {
+function root(
+	mode: CertBlockLayout,
+	theme: ResolvedBlockTheme,
+	inner: string,
+	face?: CertBlockFace,
+	responsive = false,
+): string {
 	// The rung is an OBSERVABILITY stamp for the crawl monitor — only emitted when a
 	// face is present, so the grandfathered (face-absent) output stays byte-identical.
 	const rungAttr = face ? ` data-certrev-rung="${escapeAttribute(face.rung)}"` : ''
+	// The phone face (1.1.0): the scope its rules key on, and the rules, only when asked for.
+	const responsiveAttr = responsive ? ' data-certrev-responsive' : ''
+	const style = responsive ? RESPONSIVE_STYLE : ''
 	return (
 		`<div class="certrev-cert certrev-cert--${mode}" data-certrev-mode="${mode}" ` +
-		`data-certrev-strings-version="${CERT_STRINGS_VERSION}"${rungAttr} style="${rootStyle(theme)}">${inner}</div>`
+		`data-certrev-strings-version="${CERT_STRINGS_VERSION}"${rungAttr}${responsiveAttr} style="${rootStyle(theme)}">${style}${inner}</div>`
 	)
 }
 
@@ -408,7 +506,7 @@ function root(mode: CertBlockLayout, theme: ResolvedBlockTheme, inner: string, f
 // Face — BANNER: a certification header card + a separate expert-memo card
 // ─────────────────────────────────────────────────────────────────────────────
 
-function bannerHeaderCard(facts: CertBlockFacts, placed: PlacedTest): string {
+function bannerHeaderCard(facts: CertBlockFacts, placed: PlacedTest, responsive = false): string {
 	const certified = formatDate(facts.certifiedAt)
 	const subtitle =
 		placed('authorTitle') && facts.authorTitle
@@ -473,7 +571,8 @@ function bannerHeaderCard(facts: CertBlockFacts, placed: PlacedTest): string {
 		`<div style="border:1px solid var(--navy-10);border-radius:calc(var(--br,14px) * 0.7);overflow:hidden;font-family:var(--cr-bf);">` +
 		header +
 		`<div style="padding:22px 24px 18px;">` +
-		`<div style="display:grid;grid-template-columns:${gridCols};gap:22px;">` +
+		// On a phone (responsive) the two columns stack: the stylesheet keys on `data-certrev-stack`.
+		`<div${responsive ? ' data-certrev-stack' : ''} style="display:grid;grid-template-columns:${gridCols};gap:22px;">` +
 		authorColumn +
 		`<div>` +
 		`<div style="font-family:var(--font-mono);font-size:10px;font-weight:700;letter-spacing:.14em;text-transform:uppercase;color:var(--navy);margin-bottom:11px;">Reviewed by</div>` +
@@ -487,7 +586,7 @@ function bannerHeaderCard(facts: CertBlockFacts, placed: PlacedTest): string {
 	)
 }
 
-function bannerMemoCard(facts: CertBlockFacts, placed: PlacedTest): string {
+function bannerMemoCard(facts: CertBlockFacts, placed: PlacedTest, responsive = false): string {
 	// The memo card composes `<name><, credential>` as two spans rather than through
 	// `nameWithCredential`, so it needs the SAME duplicate guard — the doubled "MD, MD" was
 	// visible on this card too. Gated on what SURVIVES the dedupe, not on the raw field: a
@@ -500,15 +599,18 @@ function bannerMemoCard(facts: CertBlockFacts, placed: PlacedTest): string {
 	// placement (the pattern `bio` already follows): placement alone painted an "Expert
 	// memo" heading over an empty `<p>` for a contract-legal empty memo.
 	const memoAvatar = placed('reviewerPhoto') ? avatar(initials(facts.reviewerName), 46, 13) : ''
+	// On a phone a long memo collapses; the name row stays visible above it (the box is the column).
+	const collapse = memoCollapse(facts, responsive, 'banner')
 	const memoSection =
 		placed('memo') && facts.memo
 			? `<div style="font-family:var(--font-mono);font-size:10px;letter-spacing:.16em;text-transform:uppercase;color:var(--navy-55);margin-bottom:14px;">Expert memo</div>` +
 				`<div style="display:flex;gap:15px;">${memoAvatar}` +
-				`<div style="flex:1;min-width:0;">` +
+				`<div${collapse.box} style="flex:1;min-width:0;">` +
 				`<div style="font-size:16px;line-height:1.2;color:var(--cr-ink);"><span style="font-weight:700;">${escapeHtml(facts.reviewerName)}</span>${credTail}</div>` +
 				// Readable, UPRIGHT DM Sans quote (the display-serif italic hurt legibility);
 				// pre-line preserves the reviewer's paragraph breaks. No left accent bar (matches the guide).
-				`<p style="margin:11px 0 14px;font-size:15.5px;line-height:1.6;color:var(--cr-ink-soft);white-space:pre-line;">${escapeHtml(facts.memo)}</p>` +
+				`<p${collapse.text} style="margin:11px 0 14px;font-size:15.5px;line-height:1.6;color:var(--cr-ink-soft);white-space:pre-line;">${escapeHtml(facts.memo)}</p>` +
+				collapse.toggle +
 				`</div>` +
 				`</div>`
 			: ''
@@ -547,7 +649,7 @@ function bannerMemoCard(facts: CertBlockFacts, placed: PlacedTest): string {
 // Face — SIDEBAR (the DEFAULT): a reviewer card pinned beside the article body
 // ─────────────────────────────────────────────────────────────────────────────
 
-function sidebarCard(facts: CertBlockFacts, placed: PlacedTest): string {
+function sidebarCard(facts: CertBlockFacts, placed: PlacedTest, responsive = false): string {
 	const header = placed('label')
 		? `<div style="display:flex;align-items:center;justify-content:center;gap:10px;padding:12px;background:var(--certrev-bar-bg,#0a1b3f);color:var(--certrev-bar-fg,#fff);font-family:var(--font-mono);font-size:12px;font-weight:700;letter-spacing:.16em;text-transform:uppercase;">${logo(18)} Expert reviewed</div>`
 		: ''
@@ -558,10 +660,7 @@ function sidebarCard(facts: CertBlockFacts, placed: PlacedTest): string {
 			: ''
 	// Gated on CONTENT as well as placement (like `bioPara` above) — placement alone rendered
 	// an empty accent-bordered blockquote for a contract-legal empty memo.
-	const blockquote =
-		placed('memo') && facts.memo
-			? `<blockquote style="margin:16px 0 0;padding-left:16px;border-left:3px solid var(--ba,#0a1b3f);font-size:15px;line-height:1.5;color:var(--cr-ink-soft);white-space:pre-line;">${escapeHtml(facts.memo)}</blockquote>`
-			: ''
+	const blockquote = placed('memo') && facts.memo ? memoQuote(facts, responsive, 'sidebar') : ''
 	// Disclosure row: cue + ` · ` + scope; the separator only when BOTH land, the row only when either does.
 	const cueEl = showsCompensationCue(facts, placed)
 		? `<span style="font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;">${escapeHtml(COMPENSATED_EXPERT_CUE)}</span>`
@@ -662,7 +761,7 @@ function floatingPill(facts: CertBlockFacts, placed: PlacedTest): string {
 // (which surfaces the switch covers) — not something to settle by quietly adding hooks.
 // ─────────────────────────────────────────────────────────────────────────────
 
-function renderCustomFace(facts: CertBlockFacts, placed: PlacedTest): string {
+function renderCustomFace(facts: CertBlockFacts, placed: PlacedTest, responsive = false): string {
 	const parts: string[] = []
 
 	// 1. label — the navy "Expert reviewed" header bar (sidebar's header markup)
@@ -703,9 +802,7 @@ function renderCustomFace(facts: CertBlockFacts, placed: PlacedTest): string {
 
 	// 5. memo (sidebar's blockquote) — placement AND content, like `bio` directly above
 	if (placed('memo') && facts.memo) {
-		parts.push(
-			`<blockquote style="margin:16px 0 0;padding-left:16px;border-left:3px solid var(--ba,#0a1b3f);font-size:15px;line-height:1.5;color:var(--cr-ink-soft);white-space:pre-line;">${escapeHtml(facts.memo)}</blockquote>`,
-		)
+		parts.push(memoQuote(facts, responsive, 'custom'))
 	}
 
 	// 6. disclosures (sidebar's cue · scope row; separator only when BOTH land)
@@ -755,13 +852,14 @@ export function renderCertBlock(input: RenderCertBlockInput): string {
 	const theme = resolveBlockTheme(input.theme)
 	const { facts, face } = input
 	const placed = placedTester(face)
+	const responsive = input.responsive === true
 	switch (input.mode) {
 		case 'banner': {
 			// Suppress the memo card entirely when the engine placed none of its fields
 			// (avoids an empty bordered shell). Grandfather: all placed ⇒ card renders.
 			const memoCard =
 				placed('memo') || placed('profileLink') || placed('certificateLink') || placed('scopeLine')
-					? bannerMemoCard(facts, placed)
+					? bannerMemoCard(facts, placed, responsive)
 					: ''
 			// First-class memo split: default 'full' is byte-identical to the prior
 			// header+memo render; 'header'/'memo' emit only that card so the exporter can place
@@ -770,16 +868,17 @@ export function renderCertBlock(input: RenderCertBlockInput): string {
 			const part = input.part === 'header' || input.part === 'memo' ? input.part : 'full'
 			const inner =
 				part === 'header'
-					? bannerHeaderCard(facts, placed)
+					? bannerHeaderCard(facts, placed, responsive)
 					: part === 'memo'
 						? memoCard
-						: bannerHeaderCard(facts, placed) + memoCard
-			return root('banner', theme, inner, face)
+						: bannerHeaderCard(facts, placed, responsive) + memoCard
+			return root('banner', theme, inner, face, responsive)
 		}
 		case 'floating':
+			// The pill has no memo and no columns: nothing on it changes on a phone.
 			return root('floating', theme, floatingPill(facts, placed), face)
 		case 'custom':
-			return root('custom', theme, renderCustomFace(facts, placed), face)
+			return root('custom', theme, renderCustomFace(facts, placed, responsive), face, responsive)
 		// THE default placement, named here and nowhere else: the declared default and the
 		// runtime fallback are the same line, so they cannot drift apart. Naming `sidebar` as a
 		// real case also keeps the exhaustiveness read over CertBlockLayout honest — a reader
@@ -787,6 +886,6 @@ export function renderCertBlock(input: RenderCertBlockInput): string {
 		// biome-ignore lint/complexity/noUselessSwitchCase: the redundancy IS the mechanism (see above)
 		case 'sidebar':
 		default:
-			return root('sidebar', theme, sidebarCard(facts, placed), face)
+			return root('sidebar', theme, sidebarCard(facts, placed, responsive), face, responsive)
 	}
 }

package/src/index.ts

@@ -36,6 +36,21 @@ export {
 	type ResolvedDisplay,
 	resolveDisplay,
 } from './components/format.js'
+// ── The PHONE face's collapsible memo (1.1.0): the markup contract + the one toggle ──
+export {
+	MEMO_ATTR,
+	MEMO_COLLAPSE_LABEL,
+	MEMO_COLLAPSE_MIN_BREAKS,
+	MEMO_COLLAPSE_MIN_CHARS,
+	MEMO_COLLAPSED_LINES,
+	MEMO_EXPAND_LABEL,
+	MEMO_TEXT_ATTR,
+	MEMO_TOGGLE_ATTR,
+	memoCollapses,
+	memoToggleFor,
+	NARROW_VIEWPORT,
+	toggleMemo,
+} from './components/memo-toggle.js'
 // ── Pre-sales PREVIEW block — static, non-delivery, hard-bounded ──
 export {
 	type PreviewBlockOptions,
@@ -118,6 +133,19 @@ export {
 	serializeJsonLdForScript,
 } from './jsonld/project.js'
 export { TtlCache, type TtlCacheOptions } from './verify/cache.js'
+export {
+	type CachedDelivery,
+	deliveryCacheKey,
+	deliveryUrl,
+	type GetVerifiedDeliveryOptions,
+	getVerifiedDelivery,
+	invalidateDelivery,
+	parseRenderDef,
+	peekVerifiedDelivery,
+	settleDelivery,
+	sharedDeliveryCache,
+	type VerifiedDelivery,
+} from './verify/get-verified-delivery.js'
 // ── Verify layer ──────────────────────────────────────────────────────────────────
 export {
 	type EnvelopeSource,

package/src/verify/get-verified-delivery.ts

@@ -0,0 +1,211 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * getVerifiedDelivery — the envelope PLUS the brand's render def, from the Delivery API
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * 1.1.0. The Delivery API answers a Builder placement with the signed artifact and, beside it,
+ * the brand's resolved render-def projection as a top-level `renderDef` sibling (the same shape a
+ * Shopify store carries in its `render_def` metafield). The envelope's signature covers `payload`
+ * only, so the sibling rides the response without touching the signed bytes, and a tombstone
+ * carries none. `getVerifiedEnvelope` keeps discarding it; this reads it.
+ *
+ * The same fetch, deadline, kernel and fail-closed rules as `getVerifiedEnvelope` (every sourcing
+ * failure reports the reason it actually is; nothing throws into the render path). Two things are
+ * different, and both are the point:
+ *
+ *  1. WHAT IS CACHED is the cryptographically verified PAYLOAD, not the verdict. The lifecycle
+ *     policy (revoked, expired) and the subject match are re-run by `renderVerdict` on EVERY call,
+ *     with the caller's clock. So a payload that was valid when fetched and expires while cached
+ *     stops rendering at its `expiresAt`, not at the next refetch; and a refetch after the TTL
+ *     picks up a tombstone (revocation) or a changed def with no write on the brand's side.
+ *  2. The CACHE KEY is the Delivery URL plus the rendering placement, so a staging and a
+ *     production origin never share an entry, and neither do two placements.
+ *
+ * `peekVerifiedDelivery` is the synchronous read of the same cache: a React component suspends on
+ * `getVerifiedDelivery` once, then reads the settled value without a second promise (which is what
+ * keeps a streaming SSR render from suspending forever on a fresh promise every retry).
+ */
+
+import type { CertChromeRenderDef } from '../builder/cert-chrome-data.js'
+import type {
+	CertDeliveryArtifact,
+	CertPayload,
+	CertSuppressReason,
+	CertVerdict,
+	RenderContext,
+	ResolvePublicKeyByKid,
+} from '../contract/kernel.js'
+import { renderVerdict, verifyArtifact } from '../contract/kernel.js'
+import { TtlCache } from './cache.js'
+import { DEFAULT_FETCH_TIMEOUT_MS, fetchWithDeadline } from './fetch-with-deadline.js'
+
+/** What one Delivery read settles to, as cached: a verified payload + its def, or the reason not. */
+export type CachedDelivery =
+	| { readonly kind: 'verified'; readonly payload: CertPayload; readonly renderDef: CertChromeRenderDef | null }
+	| { readonly kind: 'suppressed'; readonly reason: CertSuppressReason }
+
+/** The answer for one render: the verdict AT THIS RENDER'S CLOCK, and the def to paint it with. */
+export interface VerifiedDelivery {
+	readonly verdict: CertVerdict
+	/** The brand's render def, or null (no def resolved, a malformed one, or a suppress verdict). */
+	readonly renderDef: CertChromeRenderDef | null
+}
+
+export interface GetVerifiedDeliveryOptions {
+	/** Base URL of the CertREV app that serves the Delivery API, e.g. 'https://portal.certrev.com'. */
+	readonly baseUrl: string
+	readonly platform: string
+	readonly externalId: string
+	/** kid → public-key resolver. Required: no verify without keys. */
+	readonly resolveKid: ResolvePublicKeyByKid
+	/** Render context: the platform + externalId this edge IS, and the render's clock (`now`). */
+	readonly context: RenderContext
+	readonly fetchImpl?: typeof fetch
+	/** Cache override. Defaults to the module-level shared delivery cache. */
+	readonly cache?: TtlCache<CachedDelivery>
+	/** TTL in ms for a VERIFIED read (default: the cache's positive TTL, 60_000 on the shared one). */
+	readonly ttlMs?: number
+	/** Deadline in ms for the fetch (default `DEFAULT_FETCH_TIMEOUT_MS`, 3s). */
+	readonly timeoutMs?: number
+}
+
+/** Shared per-process cache: 60s for a verified read, 5s for a suppressed one. */
+const sharedDeliveryCache = new TtlCache<CachedDelivery>({ ttlMs: 60_000, negativeTtlMs: 5_000 })
+
+function suppressed(reason: CertSuppressReason): CachedDelivery {
+	return { kind: 'suppressed', reason }
+}
+
+export function deliveryUrl(baseUrl: string, platform: string, externalId: string): string {
+	const base = baseUrl.replace(/\/+$/, '')
+	return `${base}/api/cert/v1/delivery/${encodeURIComponent(platform)}/${encodeURIComponent(externalId)}`
+}
+
+/** Cache key: the URL (origin included) × the placement rendering it. No clock: the TTL bounds time. */
+export function deliveryCacheKey(
+	opts: Pick<GetVerifiedDeliveryOptions, 'baseUrl' | 'platform' | 'externalId' | 'context'>,
+): string {
+	return `delivery:${deliveryUrl(opts.baseUrl, opts.platform, opts.externalId)}|${encodeURIComponent(opts.context.platform)}:${encodeURIComponent(opts.context.externalId)}`
+}
+
+const isString = (v: unknown): v is string => typeof v === 'string'
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v)
+
+/**
+ * The def sibling, shape-checked. Anything that is not the metafield shape is null, which paints
+ * the preset default (the same thing an absent def paints): a def is presentation, never a claim,
+ * so a malformed one degrades the styling and nothing else. The TOKEN VALUES are not judged here;
+ * `resolveBlockTheme` re-validates each at paint time and drops what is not a safe value.
+ */
+export function parseRenderDef(value: unknown): CertChromeRenderDef | null {
+	if (!isRecord(value)) return null
+	const { v, preset, rung, tokens, hidden, barInkFg, layout, customFace } = value
+	if (typeof v !== 'number' || !Number.isFinite(v)) return null
+	if (!isString(preset) || !isString(rung) || !isRecord(tokens)) return null
+	if (!Array.isArray(hidden) || !hidden.every(isString)) return null
+	if (layout !== undefined && !isString(layout)) return null
+	let face: CertChromeRenderDef['customFace']
+	if (customFace !== undefined) {
+		if (!isRecord(customFace) || !Array.isArray(customFace.placedFields) || !customFace.placedFields.every(isString)) {
+			return null
+		}
+		face = { placedFields: [...customFace.placedFields] }
+	}
+	const tokenOut: Record<string, string> = {}
+	for (const key of ['accentColor', 'surface', 'cornerRadius', 'fontSlot', 'barInk', 'inkColor'] as const) {
+		if (isString(tokens[key])) tokenOut[key] = tokens[key]
+	}
+	return {
+		v,
+		preset,
+		rung,
+		tokens: tokenOut,
+		...(barInkFg === '#141414' || barInkFg === '#ffffff' ? { barInkFg } : {}),
+		hidden: [...hidden],
+		...(layout !== undefined ? { layout } : {}),
+		...(face ? { customFace: face } : {}),
+	}
+}
+
+/** Fetch, parse and cryptographically verify one Delivery response. Never throws. */
+async function loadDelivery(opts: GetVerifiedDeliveryOptions): Promise<CachedDelivery> {
+	const fetchImpl = opts.fetchImpl ?? globalThis.fetch
+	let res: Response
+	try {
+		res = await fetchWithDeadline(
+			fetchImpl,
+			deliveryUrl(opts.baseUrl, opts.platform, opts.externalId),
+			{ headers: { accept: 'application/json' } },
+			opts.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS,
+		)
+	} catch {
+		// Unreachable, DNS/TLS, or the deadline. Same least-wrong member as getVerifiedEnvelope.
+		return suppressed('unsupported_contract_version')
+	}
+	// Nothing served for this placement: never certified, or withdrawn. A LIVE revocation is a 200
+	// tombstone, so a 4xx here genuinely means "no credential for this subject".
+	if (res.status === 404 || res.status === 410) return suppressed('subject_mismatch')
+	if (!res.ok) return suppressed('unsupported_contract_version')
+	let body: unknown
+	try {
+		body = await res.json()
+	} catch {
+		return suppressed('unsupported_contract_version')
+	}
+	if (!isRecord(body)) return suppressed('unsupported_contract_version')
+	let verdict: CertVerdict
+	try {
+		// `verifyArtifact`, so a tombstone verifies as itself and reports 'revoked'. The kernel reads
+		// `payload` + `signature` (or the tombstone's own fields); the `renderDef` sibling is not
+		// part of what is verified, and is never read unless the artifact verified.
+		verdict = await verifyArtifact(body as unknown as CertDeliveryArtifact, opts.resolveKid, { ...opts.context })
+	} catch {
+		return suppressed('unknown_key')
+	}
+	if (verdict.decision !== 'render') return suppressed(verdict.reason)
+	return { kind: 'verified', payload: verdict.payload, renderDef: parseRenderDef(body.renderDef) }
+}
+
+/** Apply the render-time policy to a cached read: lifecycle + subject at THIS render's clock. */
+export function settleDelivery(cached: CachedDelivery, context: RenderContext): VerifiedDelivery {
+	if (cached.kind === 'suppressed') return { verdict: { decision: 'suppress', reason: cached.reason }, renderDef: null }
+	const verdict = renderVerdict(cached.payload, context)
+	return { verdict, renderDef: verdict.decision === 'render' ? cached.renderDef : null }
+}
+
+/**
+ * Fetch (if needed), verify, cache, and settle one Delivery read for one placement. FAIL-CLOSED:
+ * the verdict is `render` only when the artifact verified against `resolveKid` AND, at
+ * `context.now`, the payload is unrevoked, unexpired and for this placement.
+ */
+export async function getVerifiedDelivery(opts: GetVerifiedDeliveryOptions): Promise<VerifiedDelivery> {
+	const cache = opts.cache ?? sharedDeliveryCache
+	const cached = await cache.getOrLoad(
+		deliveryCacheKey(opts),
+		() => loadDelivery(opts),
+		(v) => v.kind === 'suppressed',
+		opts.ttlMs,
+	)
+	return settleDelivery(cached, opts.context)
+}
+
+/**
+ * The synchronous read: the settled answer when a fresh read is cached, else `undefined` (the
+ * caller then awaits `getVerifiedDelivery`). Never fetches.
+ */
+export function peekVerifiedDelivery(
+	opts: Pick<GetVerifiedDeliveryOptions, 'baseUrl' | 'platform' | 'externalId' | 'context' | 'cache'>,
+): VerifiedDelivery | undefined {
+	const cached = (opts.cache ?? sharedDeliveryCache).peek(deliveryCacheKey(opts))
+	return cached === undefined ? undefined : settleDelivery(cached, opts.context)
+}
+
+/** Drop every cached read for one placement (e.g. from a revocation webhook). */
+export function invalidateDelivery(
+	opts: Pick<GetVerifiedDeliveryOptions, 'baseUrl' | 'platform' | 'externalId' | 'context'>,
+	cache: TtlCache<CachedDelivery> = sharedDeliveryCache,
+): void {
+	cache.delete(deliveryCacheKey(opts))
+}
+
+export { sharedDeliveryCache }