@certrev/cert-block 0.1.0

package/src/__tests__/webcomponent.test.tsx

@@ -0,0 +1,106 @@
+// @vitest-environment jsdom
+/**
+ * Web Component + string-renderer tests.
+ *
+ * `renderBadgeHtml` is the framework-agnostic markup source shared by <CertBadge> (it
+ * mirrors the JSX) and the <certrev-badge> custom element. We assert it produces the same
+ * crawlable structure, hand-escapes every interpolated field, and drops unsafe URLs — then
+ * verify the custom element registers, honors a server-rendered light-DOM child (SSR mode),
+ * and fails closed in client mode without a configured key resolver.
+ *
+ * jsdom is opted into per-file (the rest of the suite runs in node) for `HTMLElement` +
+ * `customElements`.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { makeMockPayload } from '../contract/fixtures.js'
+import {
+	CERTREV_BADGE_TAG,
+	CertRevBadgeElement,
+	defineCertRevBadge,
+	setCertRevKidResolver,
+} from '../webcomponent/certrev-badge.js'
+import { renderBadgeHtml } from '../webcomponent/render-badge-html.js'
+
+const payload = makeMockPayload()
+
+describe('renderBadgeHtml (the shared, framework-agnostic markup)', () => {
+	it('renders the same crawlable structure as <CertBadge>: section, expert, credentials, verify link', () => {
+		const html = renderBadgeHtml(payload)
+		expect(html).toMatch(/^<section class="certrev-badge certrev-badge--full"/)
+		expect(html).toContain('Dr. Jane Doe')
+		expect(html).toContain('MD, FAAD')
+		expect(html).toContain('Verify on CertREV')
+		expect(html).toContain('data-certrev-cert-id="cert_fixture_001"')
+		expect(html).toContain('aria-label="Content reviewed by Dr. Jane Doe, MD, FAAD"')
+	})
+
+	it('HAND-ESCAPES a hostile display name (no React here — the string path must escape itself)', () => {
+		const p = makeMockPayload({
+			content: {
+				...payload.content,
+				expert: { ...payload.content.expert, displayName: '<img src=x onerror=alert(1)>' },
+				memo: null,
+			},
+		})
+		const html = renderBadgeHtml(p)
+		expect(html).not.toContain('<img src=x')
+		expect(html).toContain('&lt;img src=x onerror=alert(1)&gt;')
+	})
+
+	it('DROPS a javascript: verify URL (safeHttpUrl) — no verify anchor emitted', () => {
+		const p = makeMockPayload({ content: { ...payload.content, verifyUrl: 'javascript:alert(1)' } })
+		const html = renderBadgeHtml(p)
+		expect(html).not.toContain('javascript:')
+		expect(html).not.toContain('__verify')
+	})
+
+	it('rejects an unsafe accentColor and falls back to the default token', () => {
+		const p = makeMockPayload({
+			content: { ...payload.content, display: { ...payload.content.display, accentColor: 'url(evil)' } },
+		})
+		const html = renderBadgeHtml(p)
+		expect(html).not.toContain('url(evil)')
+		expect(html).toContain('--certrev-accent:#0f766e')
+	})
+
+	it('compact style omits the photo, memo, and dates', () => {
+		const html = renderBadgeHtml(payload, { badgeStyle: 'compact' })
+		expect(html).toContain('certrev-badge--compact')
+		expect(html).not.toContain('__photo')
+		expect(html).not.toContain('__memo')
+		expect(html).not.toContain('__dates')
+	})
+})
+
+describe('<certrev-badge> custom element', () => {
+	it('registers idempotently under its tag', () => {
+		defineCertRevBadge()
+		defineCertRevBadge() // second call is a no-op, must not throw
+		expect(customElements.get(CERTREV_BADGE_TAG)).toBe(CertRevBadgeElement)
+	})
+
+	it('SSR mode: leaves a server-rendered light-DOM badge child untouched on connect', () => {
+		defineCertRevBadge()
+		const host = document.createElement(CERTREV_BADGE_TAG)
+		host.innerHTML = renderBadgeHtml(payload) // server already rendered the badge inside
+		document.body.appendChild(host)
+		// connectedCallback saw an existing .certrev-badge child → must not wipe/replace it.
+		expect(host.querySelector('.certrev-badge')).not.toBeNull()
+		expect(host.innerHTML).toContain('Dr. Jane Doe')
+		host.remove()
+	})
+
+	it('client mode FAIL-CLOSED: with no key resolver configured it renders nothing', () => {
+		setCertRevKidResolver(null as never) // explicitly unconfigured
+		defineCertRevBadge()
+		const host = document.createElement(CERTREV_BADGE_TAG)
+		host.setAttribute('delivery-api', 'https://portal.certrev.com')
+		host.setAttribute('platform', 'shopify')
+		host.setAttribute('external-id', 'gid://shopify/Article/1')
+		document.body.appendChild(host)
+		// No resolver → cannot verify → renders nothing (fail-closed). No badge child appears.
+		expect(host.querySelector('.certrev-badge')).toBeNull()
+		host.remove()
+	})
+})

package/src/components/CertBadge.tsx

@@ -0,0 +1,164 @@
+/**
+ * <CertBadge> — the visible "Reviewed by a credentialed expert" badge.
+ *
+ * SSR-SAFE: a pure render component. No `useState`/`useEffect`/`useRef`, no browser-only
+ * calls, no event handlers — so it works as a React Server Component AND as a client
+ * component that SSRs identically (the crawlable output is the same either way). All
+ * presentation comes from `payload.content.display`; all text is React-escaped; every
+ * URL passes through `safeHttpUrl`.
+ *
+ * ACCESSIBILITY: rendered as a <section> with an accessible name, the accent applied via
+ * an inline custom property (no color-only meaning — the credential text carries it), an
+ * expert photo with meaningful alt text, and a verify link with a descriptive label.
+ *
+ * `badgeStyle: 'compact'` collapses to a single line (name + credentials + verify link);
+ * `'full'` shows the photo, certified/updated dates, and the memo (per display flags).
+ */
+
+import type { CertContent, CertPayload } from '../contract/kernel.js'
+import { safeHttpUrl } from './escape.js'
+import { credentialSuffix, expertNameWithCredentials, formatDate, resolveDisplay } from './format.js'
+
+export interface CertBadgeProps {
+	/** The cryptographically-verified payload (from `getVerifiedEnvelope`). */
+	readonly payload: CertPayload
+	/** Optional accent override (else `display.accentColor`, else CertREV default). */
+	readonly accentColor?: string
+	/** Extra class names appended to the root element's class list. */
+	readonly className?: string
+	/** Override the badge style independent of the signed display config. */
+	readonly badgeStyle?: 'full' | 'compact'
+}
+
+const ROOT_CLASS = 'certrev-badge'
+
+/** Inline-SVG verified checkmark — no external asset, accent-tinted, decorative. */
+function VerifiedMark({ accent }: { accent: string }) {
+	return (
+		<svg
+			className={`${ROOT_CLASS}__mark`}
+			width="20"
+			height="20"
+			viewBox="0 0 24 24"
+			fill="none"
+			aria-hidden="true"
+			focusable="false"
+		>
+			<title>Verified</title>
+			<circle cx="12" cy="12" r="11" fill={accent} />
+			<path d="M7 12.5l3.2 3.2L17 9" stroke="#ffffff" strokeWidth="2.2" strokeLinecap="round" strokeLinejoin="round" />
+		</svg>
+	)
+}
+
+function ExpertPhoto({ content, show }: { content: CertContent; show: boolean }) {
+	const src = show ? safeHttpUrl(content.expert.photoUrl) : null
+	if (!src) return null
+	return (
+		<img
+			className={`${ROOT_CLASS}__photo`}
+			src={src}
+			alt={`Photo of ${content.expert.displayName}`}
+			width={40}
+			height={40}
+			loading="lazy"
+			decoding="async"
+		/>
+	)
+}
+
+export function CertBadge(props: CertBadgeProps) {
+	const { payload } = props
+	const content = payload.content
+	const display = resolveDisplay(content.display, props.accentColor)
+	const style = props.badgeStyle ?? display.badgeStyle
+	const verifyUrl = safeHttpUrl(content.verifyUrl)
+	const profileUrl = safeHttpUrl(content.expert.profileUrl)
+	const certifiedLabel = formatDate(content.certifiedAt)
+	const updatedLabel = formatDate(content.contentModifiedAt)
+	const suffix = credentialSuffix(content)
+	const accent = display.accentColor
+
+	const rootClass = `${ROOT_CLASS} ${ROOT_CLASS}--${style}${props.className ? ` ${props.className}` : ''}`
+	// Accent is exposed as a custom property so brand themes can read it, and applied
+	// directly to the accent border so the component is self-styling without a stylesheet.
+	const rootStyle: Record<string, string> = {
+		['--certrev-accent']: accent,
+		borderInlineStartColor: accent,
+	}
+
+	const expertName = (
+		<span className={`${ROOT_CLASS}__expert-name`}>
+			{content.expert.displayName}
+			{suffix ? <span className={`${ROOT_CLASS}__credentials`}>, {suffix}</span> : null}
+		</span>
+	)
+
+	return (
+		<section
+			className={rootClass}
+			style={rootStyle}
+			data-certrev-cert-id={payload.certId}
+			aria-label={`Content reviewed by ${expertNameWithCredentials(content)}`}
+		>
+			<div className={`${ROOT_CLASS}__header`}>
+				<VerifiedMark accent={accent} />
+				{style === 'full' ? <ExpertPhoto content={content} show={display.showExpertPhoto} /> : null}
+				<div className={`${ROOT_CLASS}__heading`}>
+					<span className={`${ROOT_CLASS}__eyebrow`}>Expert reviewed</span>
+					<span className={`${ROOT_CLASS}__byline`}>
+						Reviewed by{' '}
+						{profileUrl ? (
+							<a className={`${ROOT_CLASS}__expert-link`} href={profileUrl} rel="noopener">
+								{expertName}
+							</a>
+						) : (
+							expertName
+						)}
+					</span>
+				</div>
+			</div>
+
+			{style === 'full' ? (
+				<>
+					{display.showMemo && content.memo ? <p className={`${ROOT_CLASS}__memo`}>{content.memo}</p> : null}
+					{display.showAuthor && content.author.name && content.author.name !== content.expert.displayName ? (
+						<p className={`${ROOT_CLASS}__author`}>
+							Written by {content.author.name}
+							{content.author.title ? `, ${content.author.title}` : ''}
+						</p>
+					) : null}
+					<dl className={`${ROOT_CLASS}__dates`}>
+						{certifiedLabel ? (
+							<div className={`${ROOT_CLASS}__date`}>
+								<dt>Certified</dt>
+								<dd>
+									<time dateTime={content.certifiedAt}>{certifiedLabel}</time>
+								</dd>
+							</div>
+						) : null}
+						{updatedLabel ? (
+							<div className={`${ROOT_CLASS}__date`}>
+								<dt>Last updated</dt>
+								<dd>
+									<time dateTime={content.contentModifiedAt ?? undefined}>{updatedLabel}</time>
+								</dd>
+							</div>
+						) : null}
+					</dl>
+				</>
+			) : null}
+
+			{verifyUrl ? (
+				<a
+					className={`${ROOT_CLASS}__verify`}
+					href={verifyUrl}
+					rel="noopener"
+					aria-label="Verify this certification on CertREV"
+				>
+					Verify on CertREV
+				</a>
+			) : null}
+		</section>
+	)
+}

package/src/components/CertJsonLd.tsx

@@ -0,0 +1,36 @@
+/**
+ * <CertJsonLd> — emits the projected schema.org graph as a
+ * `<script type="application/ld+json">`.
+ *
+ * The JSON-LD is PROJECTED from the verified facts (never stored in the envelope — see
+ * the projector). SSR-safe: it renders a single <script> whose body is the serialized
+ * graph with `<` neutralized so it can't break out of the script tag (standard
+ * dangerouslySetInnerHTML-for-JSON-LD pattern; the content is our own deterministic
+ * serialization of trusted-shape data, not arbitrary HTML).
+ *
+ * Place it inside the page <head> (Next: in a layout/head; Hydrogen: in the route
+ * component — React 19 hoists <script> in <head>) so crawlers read structured data
+ * without client JS.
+ */
+
+import type { CertPayload } from '../contract/kernel.js'
+import { projectCertJsonLd, type ProjectJsonLdOptions, serializeJsonLdForScript } from '../jsonld/project.js'
+
+export interface CertJsonLdProps extends ProjectJsonLdOptions {
+	readonly payload: CertPayload
+	/** Optional id on the <script> so a page can find/replace it deterministically. */
+	readonly scriptId?: string
+}
+
+export function CertJsonLd(props: CertJsonLdProps) {
+	const { payload, scriptId, ...opts } = props
+	const json = serializeJsonLdForScript(projectCertJsonLd(payload, opts))
+	return (
+		<script
+			type="application/ld+json"
+			id={scriptId}
+			// biome-ignore lint/security/noDangerouslySetInnerHtml: JSON-LD requires raw script body; the content is our deterministic serialization with `<` neutralized (serializeJsonLdForScript), not arbitrary HTML.
+			dangerouslySetInnerHTML={{ __html: json }}
+		/>
+	)
+}

package/src/components/CertRevBacklink.tsx

@@ -0,0 +1,63 @@
+/**
+ * <CertRevBacklink> — the live "Verify on CertREV" link.
+ *
+ * The local badge is a bounded-stale snapshot; `content.verifyUrl` is ALWAYS the live
+ * source of truth. This standalone link lets brands place the verification entry point
+ * wherever they want, independent of the badge. SSR-safe + pure; URL through
+ * `safeHttpUrl`. Renders nothing if the verify URL is unsafe/absent (fail-closed).
+ */
+
+import type { CertPayload } from '../contract/kernel.js'
+import { safeHttpUrl } from './escape.js'
+import { resolveDisplay } from './format.js'
+
+export interface CertRevBacklinkProps {
+	readonly payload: CertPayload
+	readonly accentColor?: string
+	readonly className?: string
+	/** Link text (default "Verify on CertREV"). */
+	readonly label?: string
+}
+
+const ROOT_CLASS = 'certrev-backlink'
+
+export function CertRevBacklink(props: CertRevBacklinkProps) {
+	const verifyUrl = safeHttpUrl(props.payload.content.verifyUrl)
+	if (!verifyUrl) return null
+	const display = resolveDisplay(props.payload.content.display, props.accentColor)
+	const rootClass = `${ROOT_CLASS}${props.className ? ` ${props.className}` : ''}`
+	// Typed as a string record (not inline) so the `--certrev-accent` CSS custom property
+	// is accepted — React's CSSProperties rejects arbitrary custom props on an inline literal.
+	const rootStyle: Record<string, string> = { ['--certrev-accent']: display.accentColor, color: display.accentColor }
+
+	return (
+		<a
+			className={rootClass}
+			style={rootStyle}
+			href={verifyUrl}
+			rel="noopener"
+			aria-label="Verify this certification on CertREV"
+		>
+			<svg
+				className={`${ROOT_CLASS}__icon`}
+				width="14"
+				height="14"
+				viewBox="0 0 24 24"
+				fill="none"
+				aria-hidden="true"
+				focusable="false"
+			>
+				<title>Verified</title>
+				<path
+					d="M12 2l7 3v6c0 4.4-3 8.3-7 9-4-0.7-7-4.6-7-9V5l7-3z"
+					fill="none"
+					stroke="currentColor"
+					strokeWidth="1.8"
+					strokeLinejoin="round"
+				/>
+				<path d="M8.5 12l2.3 2.3L15.5 9" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round" />
+			</svg>
+			<span className={`${ROOT_CLASS}__label`}>{props.label ?? 'Verify on CertREV'}</span>
+		</a>
+	)
+}

package/src/components/CertReview.tsx

@@ -0,0 +1,42 @@
+/**
+ * <CertReview> — the one-line convenience composite.
+ *
+ * Most brand integrations want "render the badge + the JSON-LD from a verified
+ * envelope, or render nothing". This wraps that: pass a `CertVerdict` (the output of
+ * `getVerifiedEnvelope` / the kernel) and it renders the badge + projected JSON-LD on
+ * `render`, and NOTHING on `suppress` (fail-closed at the component boundary too). The
+ * expert bio + backlink remain separately placeable for brands that want finer control.
+ */
+
+import type { CertVerdict } from '../contract/kernel.js'
+import { CertBadge } from './CertBadge.js'
+import { CertJsonLd } from './CertJsonLd.js'
+
+export interface CertReviewProps {
+	/** The verdict from `getVerifiedEnvelope` (or a direct kernel call). */
+	readonly verdict: CertVerdict
+	/** Canonical page URL for JSON-LD @id alignment (merge into the host article node). */
+	readonly pageUrl?: string
+	readonly accentColor?: string
+	readonly className?: string
+	readonly badgeStyle?: 'full' | 'compact'
+	/** Omit the JSON-LD (e.g. the page already emits it elsewhere). Default false. */
+	readonly omitJsonLd?: boolean
+}
+
+export function CertReview(props: CertReviewProps) {
+	// Fail-closed: a suppressed (or any non-render) verdict renders nothing.
+	if (props.verdict.decision !== 'render') return null
+	const payload = props.verdict.payload
+	return (
+		<>
+			<CertBadge
+				payload={payload}
+				accentColor={props.accentColor}
+				className={props.className}
+				badgeStyle={props.badgeStyle}
+			/>
+			{props.omitJsonLd ? null : <CertJsonLd payload={payload} pageUrl={props.pageUrl} />}
+		</>
+	)
+}

package/src/components/ExpertBio.tsx

@@ -0,0 +1,77 @@
+/**
+ * <ExpertBio> — the reviewing expert's identity block (photo, name, credentials, link).
+ *
+ * Renders the E-E-A-T-bearing facts about WHO reviewed the content, separate from the
+ * compact badge. Brands place this near the article footer / author box. SSR-safe + pure
+ * like the rest; every field React-escaped; URLs through `safeHttpUrl`.
+ */
+
+import type { CertPayload } from '../contract/kernel.js'
+import { safeHttpUrl } from './escape.js'
+import { resolveDisplay } from './format.js'
+
+export interface ExpertBioProps {
+	readonly payload: CertPayload
+	readonly accentColor?: string
+	readonly className?: string
+	/** Heading level for the expert name (default 'h3') so it slots into the page outline. */
+	readonly headingLevel?: 'h2' | 'h3' | 'h4'
+}
+
+const ROOT_CLASS = 'certrev-expert-bio'
+
+export function ExpertBio(props: ExpertBioProps) {
+	const { payload } = props
+	const { expert } = payload.content
+	const display = resolveDisplay(payload.content.display, props.accentColor)
+	const profileUrl = safeHttpUrl(expert.profileUrl)
+	const photoUrl = display.showExpertPhoto ? safeHttpUrl(expert.photoUrl) : null
+	const Heading = props.headingLevel ?? 'h3'
+	const rootClass = `${ROOT_CLASS}${props.className ? ` ${props.className}` : ''}`
+	const rootStyle: Record<string, string> = { ['--certrev-accent']: display.accentColor }
+
+	const nameNode = (
+		<Heading className={`${ROOT_CLASS}__name`}>
+			{expert.displayName}
+			{expert.credentials.length > 0 ? (
+				<span className={`${ROOT_CLASS}__credentials`}>, {expert.credentials.map((c) => c.abbreviation).join(', ')}</span>
+			) : null}
+		</Heading>
+	)
+
+	return (
+		<aside className={rootClass} style={rootStyle} aria-label={`About the reviewing expert, ${expert.displayName}`}>
+			{photoUrl ? (
+				<img
+					className={`${ROOT_CLASS}__photo`}
+					src={photoUrl}
+					alt={`Photo of ${expert.displayName}`}
+					width={64}
+					height={64}
+					loading="lazy"
+					decoding="async"
+				/>
+			) : null}
+			<div className={`${ROOT_CLASS}__body`}>
+				{profileUrl ? (
+					<a className={`${ROOT_CLASS}__name-link`} href={profileUrl} rel="noopener">
+						{nameNode}
+					</a>
+				) : (
+					nameNode
+				)}
+				{expert.credentials.length > 0 ? (
+					<ul className={`${ROOT_CLASS}__credential-list`}>
+						{expert.credentials.map((c) => (
+							<li key={`${c.abbreviation}:${c.fullName}`} className={`${ROOT_CLASS}__credential`}>
+								<abbr title={c.fullName}>{c.abbreviation}</abbr>
+								<span className={`${ROOT_CLASS}__credential-full`}> — {c.fullName}</span>
+							</li>
+						))}
+					</ul>
+				) : null}
+				<p className={`${ROOT_CLASS}__role`}>Verified expert reviewer</p>
+			</div>
+		</aside>
+	)
+}

package/src/components/escape.ts

@@ -0,0 +1,72 @@
+/**
+ * SSR-safe escaping + sanitization helpers.
+ *
+ * The components render certification FACTS that originate from brand / expert input
+ * (display names, memos, titles, URLs). React escapes text children + attribute values
+ * by default, so the JSX path is safe without extra work — but two surfaces need
+ * explicit defense:
+ *   1. URLs placed in href/src: a `javascript:` (or `data:`) scheme in a stored URL
+ *      becomes an XSS vector the moment it's clicked. `safeHttpUrl` allows only http(s).
+ *   2. The Web Component + JSON-LD paths build strings by hand (no JSX auto-escaping),
+ *      so they call `escapeHtml` / `escapeAttribute` directly.
+ *
+ * Everything here is pure and runtime-agnostic (no DOM, no Node APIs) so it runs in a
+ * server component, an edge runtime, and the Web Component identically.
+ */
+
+const HTML_ESCAPES: Record<string, string> = {
+	'&': '&amp;',
+	'<': '&lt;',
+	'>': '&gt;',
+	'"': '&quot;',
+	"'": '&#39;',
+}
+
+/** Escape text for safe inclusion in HTML element content or double-quoted attributes. */
+export function escapeHtml(input: string): string {
+	return input.replace(/[&<>"']/g, (c) => HTML_ESCAPES[c] ?? c)
+}
+
+/** Alias kept explicit at call sites where the value lands in an attribute. */
+export const escapeAttribute = escapeHtml
+
+/**
+ * Return the URL only if it is a safe absolute http(s) URL (or a protocol-relative or
+ * site-relative URL), else null. Anything with a `javascript:`/`data:`/`vbscript:`/etc.
+ * scheme — or that fails to parse — is rejected so it can never reach an href/src.
+ * Callers treat null as "omit the link".
+ */
+export function safeHttpUrl(input: string | null | undefined): string | null {
+	if (!input) return null
+	const trimmed = input.trim()
+	if (trimmed === '') return null
+	// Site-relative or protocol-relative URLs are safe (no scheme to abuse).
+	if (trimmed.startsWith('/') || trimmed.startsWith('#') || trimmed.startsWith('?')) return trimmed
+	try {
+		const u = new URL(trimmed)
+		return u.protocol === 'http:' || u.protocol === 'https:' ? u.toString() : null
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Validate a CSS color token for inline `style`. We accept only a conservative set
+ * (`#rgb`/`#rgba`/`#rrggbb`/`#rrggbbaa` hex, `rgb()/rgba()/hsl()/hsla()` functions, and
+ * a bare CSS keyword) so a stored `accentColor` can't inject `expression(...)`,
+ * `url(...)`, or break out of the style attribute. Returns null on anything suspicious.
+ */
+export function safeCssColor(input: string | null | undefined): string | null {
+	if (!input) return null
+	const v = input.trim()
+	if (v === '') return null
+	if (/^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(v)) return v
+	if (/^(?:rgb|rgba|hsl|hsla)\(\s*[0-9.,%\s/]+\)$/.test(v)) return v
+	if (/^[a-zA-Z]{1,32}$/.test(v)) return v
+	return null
+}
+
+/** Collapse interior whitespace + trim. Used to normalize display text. */
+export function tidyText(input: string | null | undefined): string {
+	return (input ?? '').replace(/\s+/g, ' ').trim()
+}

package/src/components/format.ts

@@ -0,0 +1,55 @@
+/**
+ * Presentation helpers shared by the React components + Web Component. Pure, no DOM,
+ * no React — so the same formatting drives JSX and the hand-built Web Component string.
+ */
+
+import type { CertContent, CertDisplayConfig } from '../contract/kernel.js'
+
+/** Default accent if the brand didn't pin one (CertREV teal). */
+export const DEFAULT_ACCENT = '#0f766e'
+
+export interface ResolvedDisplay {
+	readonly accentColor: string
+	readonly showExpertPhoto: boolean
+	readonly showAuthor: boolean
+	readonly showMemo: boolean
+	readonly badgeStyle: 'full' | 'compact'
+}
+
+/** Resolve the optional display config to concrete presentation flags + accent. */
+export function resolveDisplay(display: CertDisplayConfig | undefined, accentOverride?: string): ResolvedDisplay {
+	return {
+		accentColor: accentOverride ?? display?.accentColor ?? DEFAULT_ACCENT,
+		showExpertPhoto: display?.showExpertPhoto ?? true,
+		showAuthor: display?.showAuthor ?? true,
+		showMemo: display?.showMemo ?? true,
+		badgeStyle: display?.badgeStyle ?? 'full',
+	}
+}
+
+/**
+ * Format an ISO-8601 instant to a stable, locale-independent date label ("Jun 21, 2026").
+ * We deliberately DON'T use `toLocaleDateString` — its output varies by runtime ICU data,
+ * which would make SSR output non-deterministic + cause hydration mismatches. Fixed
+ * English month abbreviations keep server + client byte-identical.
+ */
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
+
+export function formatDate(iso: string | null | undefined): string | null {
+	if (!iso) return null
+	const ms = Date.parse(iso)
+	if (Number.isNaN(ms)) return null
+	const d = new Date(ms)
+	return `${MONTHS[d.getUTCMonth()]} ${d.getUTCDate()}, ${d.getUTCFullYear()}`
+}
+
+/** "PhD, RD" — the expert's credential abbreviations, comma-joined. */
+export function credentialSuffix(content: CertContent): string {
+	return content.expert.credentials.map((c) => c.abbreviation).join(', ')
+}
+
+/** "Dr. Jane Doe, PhD, RD" — display name with credential suffix appended. */
+export function expertNameWithCredentials(content: CertContent): string {
+	const suffix = credentialSuffix(content)
+	return suffix ? `${content.expert.displayName}, ${suffix}` : content.expert.displayName
+}