@certrev/cert-block 0.1.3 → 0.3.0

package/src/__tests__/render-def.test.tsx

@@ -0,0 +1,286 @@
+/**
+ * WS6 — design-guide render-def support (themeable tokens + subtractive visibility)
+ * + the two always-on compliance strings.
+ *
+ * Two planes, both exercised through the SSR paths (React `renderToStaticMarkup` +
+ * the framework-agnostic `renderBadgeHtml` string renderer — the crawlable output):
+ *   1. the PURE resolution helpers (validators, `resolveRenderTheme`, visibility,
+ *      the fixed font stacks, the byte-verbatim strings);
+ *   2. the RENDERED faces — a themed def emits the four `--certrev-*` vars + the
+ *      def-version stamp + subtractive visibility; NO def is theme-byte-identical
+ *      to the un-themed default; an invalid token is DROPPED (fail-safe); and the
+ *      compensation cue + FTC scope line + strings-version stamp land on EVERY
+ *      claim face (the compliance baseline, with or without a def).
+ */
+
+import { renderToStaticMarkup } from 'react-dom/server'
+import { describe, expect, it } from 'vitest'
+import { CertBadge } from '../components/CertBadge.js'
+import { CertReview } from '../components/CertReview.js'
+import {
+	CERT_SCOPE_LINE,
+	CERT_STRINGS_VERSION,
+	type CertRenderDef,
+	COMPENSATED_EXPERT_CUE,
+	type FontSlot,
+	FONT_STACKS,
+	isCornerRadius,
+	isFieldHidden,
+	isFontSlot,
+	isOpaqueHexColor,
+	resolveRenderTheme,
+	themeCssVarDeclarations,
+} from '../components/render-def.js'
+import { makeMockPayload } from '../contract/fixtures.js'
+import { renderBadgeHtml } from '../webcomponent/render-badge-html.js'
+
+const payload = makeMockPayload()
+
+/** A fully-themed, valid render-def (every token overridden, both fields hidden). */
+const THEMED: CertRenderDef = {
+	tokens: { accentColor: '#123456', surface: '#eeeeee', cornerRadius: '8px', fontSlot: 'serif' },
+	hidden: ['reviewerPhoto', 'memo'],
+	version: 4,
+}
+
+/** Tag-strip a fragment of HTML to its visible text (collapse whitespace). */
+function visibleText(html: string): string {
+	return html
+		.replace(/<[^>]+>/g, ' ')
+		.replace(/\s+/g, ' ')
+		.trim()
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pure helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('token validators (mirror portal src/lib/design-guide/tokens.ts)', () => {
+	it('isOpaqueHexColor accepts 3/6-digit hex, rejects alpha / functions / keywords', () => {
+		for (const ok of ['#fff', '#FFFFFF', '#0a1b3f', '#123']) expect(isOpaqueHexColor(ok)).toBe(true)
+		for (const bad of ['#ffff', '#ffffffaa', '#12', '#1234567', 'transparent', 'rgb(0,0,0)', 'red', '', ' #fff'])
+			expect(isOpaqueHexColor(bad)).toBe(false)
+	})
+
+	it('isCornerRadius accepts a bare 0 or a single unit length, rejects unitless / calc / spaces', () => {
+		for (const ok of ['0', '12px', '0.5rem', '.5em', '100%', '4px']) expect(isCornerRadius(ok)).toBe(true)
+		for (const bad of ['12', '12 px', 'calc(1px)', '1px 2px', '', 'px', '-4px']) expect(isCornerRadius(bad)).toBe(false)
+	})
+
+	it('isFontSlot admits only the three enum members', () => {
+		for (const ok of ['sans', 'serif', 'system']) expect(isFontSlot(ok)).toBe(true)
+		for (const bad of ['mono', 'Arial', '', 'SANS']) expect(isFontSlot(bad)).toBe(false)
+	})
+})
+
+describe('FONT_STACKS — byte-identical to the Shopify Liquid engine literals', () => {
+	it('matches the exact stacks (the parity anchor across the twins)', () => {
+		expect(FONT_STACKS.sans).toBe("'DM Sans', system-ui, -apple-system, BlinkMacSystemFont, sans-serif")
+		expect(FONT_STACKS.serif).toBe("'Playfair Display', Georgia, 'Times New Roman', serif")
+		expect(FONT_STACKS.system).toBe("system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif")
+	})
+})
+
+describe('resolveRenderTheme — validates + drops (fail-safe)', () => {
+	it('returns {} for an absent def', () => {
+		expect(resolveRenderTheme(undefined)).toEqual({})
+	})
+
+	it('resolves every valid token + the fontSlot → fixed stack + the version', () => {
+		expect(resolveRenderTheme(THEMED)).toEqual({
+			accent: '#123456',
+			surface: '#eeeeee',
+			cornerRadius: '8px',
+			fontStack: FONT_STACKS.serif,
+			version: 4,
+		})
+	})
+
+	it('DROPS every invalid token (alpha surface, function accent, calc radius, unknown slot)', () => {
+		const resolved = resolveRenderTheme({
+			tokens: {
+				accentColor: 'rgb(0,0,0)',
+				surface: '#ffffffaa',
+				cornerRadius: 'calc(1px)',
+				fontSlot: 'mono' as FontSlot,
+			},
+			version: 2,
+		})
+		expect(resolved).toEqual({
+			accent: undefined,
+			surface: undefined,
+			cornerRadius: undefined,
+			fontStack: undefined,
+			version: 2,
+		})
+	})
+
+	it('drops a non-finite version', () => {
+		expect(resolveRenderTheme({ version: Number.NaN }).version).toBeUndefined()
+	})
+})
+
+describe('subtractive visibility + var declarations', () => {
+	it('isFieldHidden is true only for a listed field', () => {
+		expect(isFieldHidden({ hidden: ['memo'] }, 'memo')).toBe(true)
+		expect(isFieldHidden({ hidden: ['memo'] }, 'reviewerPhoto')).toBe(false)
+		expect(isFieldHidden(undefined, 'memo')).toBe(false)
+	})
+
+	it('themeCssVarDeclarations is empty for an un-themed face and ordered surface→radius→font', () => {
+		expect(themeCssVarDeclarations({})).toEqual([])
+		expect(themeCssVarDeclarations(resolveRenderTheme(THEMED))).toEqual([
+			['--certrev-surface', '#eeeeee'],
+			['--certrev-radius', '8px'],
+			['--certrev-font', FONT_STACKS.serif],
+		])
+	})
+})
+
+describe('the two always-on compliance strings are byte-verbatim', () => {
+	it('cue + strings-version', () => {
+		expect(COMPENSATED_EXPERT_CUE).toBe('Compensated expert')
+		expect(CERT_STRINGS_VERSION).toBe('2026-07')
+	})
+
+	it('the scope line carries the load-bearing curly apostrophe U+2019', () => {
+		expect(CERT_SCOPE_LINE).toBe(
+			'Independent editorial review of this article’s text and sources. Not a product endorsement, nor medical advice.',
+		)
+		expect(CERT_SCOPE_LINE).toContain('’')
+		expect(CERT_SCOPE_LINE).not.toContain("'") // straight apostrophe would be a contract divergence
+	})
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Rendered — React <CertBadge>
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('<CertBadge> themed', () => {
+	it('emits the four --certrev-* vars, the def-version stamp, and hides subtracted fields', () => {
+		const html = renderToStaticMarkup(<CertBadge payload={payload} renderDef={THEMED} />)
+		expect(html).toContain('--certrev-accent:#123456')
+		expect(html).toContain('--certrev-surface:#eeeeee')
+		expect(html).toContain('--certrev-radius:8px')
+		// React entity-encodes the font stack's single quotes; the family content is intact.
+		expect(html).toContain('--certrev-font:')
+		expect(html).toContain('Playfair Display')
+		expect(html).toContain('data-certrev-def-version="4"')
+		// subtractive visibility: reviewerPhoto + memo hidden
+		expect(html).not.toContain('__photo')
+		expect(html).not.toContain('retinol claims')
+	})
+
+	it('an unthemed badge emits NO theme vars + NO def-version stamp (theme byte-neutral)', () => {
+		const html = renderToStaticMarkup(<CertBadge payload={payload} />)
+		expect(html).not.toContain('--certrev-surface')
+		expect(html).not.toContain('--certrev-radius')
+		expect(html).not.toContain('--certrev-font')
+		expect(html).not.toContain('data-certrev-def-version')
+	})
+})
+
+describe('compliance baseline — cue + scope + strings-version on EVERY claim face', () => {
+	it('full + unthemed: cue, verbatim scope line, and the strings-version stamp all present', () => {
+		const html = renderToStaticMarkup(<CertBadge payload={payload} />)
+		expect(html).toContain('data-certrev-strings-version="2026-07"')
+		expect(html).toContain(CERT_SCOPE_LINE)
+		expect(html).toContain('data-ftc-line')
+		expect(visibleText(html)).toContain(COMPENSATED_EXPERT_CUE)
+	})
+
+	it('compact ALSO carries the cue + scope (a compact claim badge is still a claim face)', () => {
+		const html = renderToStaticMarkup(<CertBadge payload={payload} badgeStyle="compact" />)
+		expect(html).toContain('certrev-badge--compact')
+		expect(html).toContain(CERT_SCOPE_LINE)
+		expect(visibleText(html)).toContain(COMPENSATED_EXPERT_CUE)
+	})
+
+	it('the cue links "expert" to the reviewer profile; falls back to plain text when unsafe', () => {
+		const linked = renderToStaticMarkup(<CertBadge payload={payload} />)
+		expect(linked).toContain('>expert</a>')
+		const p = makeMockPayload({
+			content: { ...payload.content, expert: { ...payload.content.expert, profileUrl: 'javascript:alert(1)' } },
+		})
+		const unlinked = renderToStaticMarkup(<CertBadge payload={p} />)
+		expect(unlinked).not.toContain('javascript:')
+		expect(visibleText(unlinked)).toContain(COMPENSATED_EXPERT_CUE)
+	})
+})
+
+describe('<CertReview> forwards the render-def to the badge', () => {
+	it('a themed def reaches the badge; the JSON-LD stays presentation-blind', () => {
+		const html = renderToStaticMarkup(<CertReview verdict={{ decision: 'render', payload }} renderDef={THEMED} />)
+		expect(html).toContain('--certrev-surface:#eeeeee')
+		expect(html).toContain('data-certrev-def-version="4"')
+		// the projector never sees the def — the graph is byte-unchanged
+		expect(html).toContain('application/ld+json')
+	})
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Rendered — the framework-agnostic string path (renderBadgeHtml)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('renderBadgeHtml themed (the crawlable string path)', () => {
+	it('emits each --certrev-* var exactly once; the font stack is the RAW fixed literal (byte-exact)', () => {
+		const html = renderBadgeHtml(payload, { renderDef: THEMED })
+		expect(html).toContain('--certrev-accent:#123456')
+		expect(html).toContain('--certrev-surface:#eeeeee')
+		expect(html).toContain('--certrev-radius:8px')
+		expect(html).toContain(`--certrev-font:${FONT_STACKS.serif}`) // byte-exact, single quotes raw
+		for (const v of ['--certrev-accent:', '--certrev-surface:', '--certrev-radius:', '--certrev-font:'])
+			expect((html.match(new RegExp(v.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g')) ?? []).length).toBe(1)
+		expect(html).toContain('data-certrev-def-version="4"')
+		expect(html).toContain('data-certrev-strings-version="2026-07"')
+		expect(html).not.toContain('__photo') // reviewerPhoto hidden
+		expect(html).not.toContain('__memo') // memo hidden
+	})
+
+	it('the compliance baseline is present: verbatim scope line + the cue', () => {
+		const html = renderBadgeHtml(payload, { renderDef: THEMED })
+		expect(html).toContain(CERT_SCOPE_LINE)
+		expect(html).toContain('data-ftc-line')
+		expect(visibleText(html)).toContain(COMPENSATED_EXPERT_CUE)
+	})
+
+	it('DROPS every invalid token (fail-safe to preset default); no injection reaches the style', () => {
+		const html = renderBadgeHtml(payload, {
+			renderDef: {
+				tokens: {
+					accentColor: 'rgb(0,0,0)',
+					surface: '#ffffffaa',
+					cornerRadius: 'calc(1px)',
+					fontSlot: 'mono' as FontSlot,
+				},
+			},
+		})
+		expect(html).not.toContain('rgb(0,0,0)')
+		expect(html).not.toContain('#ffffffaa')
+		expect(html).not.toContain('calc(')
+		expect(html).not.toContain('--certrev-surface')
+		expect(html).not.toContain('--certrev-radius')
+		expect(html).not.toContain('--certrev-font')
+		// the invalid accent fell back to the signed display accent (never the rgb)
+		expect(html).toContain('--certrev-accent:#7c3aed')
+	})
+
+	it('un-themed: theme output is BYTE-IDENTICAL to the pre-WS6 single-accent form', () => {
+		const html = renderBadgeHtml(payload)
+		expect(html).toContain('style="--certrev-accent:#7c3aed;border-inline-start-color:#7c3aed"')
+		expect(html).not.toContain('--certrev-surface')
+		expect(html).not.toContain('data-certrev-def-version')
+		// baseline compliance strings still land on the un-themed face
+		expect(html).toContain('data-certrev-strings-version="2026-07"')
+		expect(html).toContain(CERT_SCOPE_LINE)
+	})
+
+	it('renders the cue as plain text when the profile URL is unsafe/absent', () => {
+		const p = makeMockPayload({
+			content: { ...payload.content, expert: { ...payload.content.expert, profileUrl: 'javascript:alert(1)' } },
+		})
+		const html = renderBadgeHtml(p)
+		expect(html).not.toContain('javascript:')
+		expect(html).toContain('Compensated expert')
+	})
+})

package/src/__tests__/webcomponent.test.tsx

@@ -71,6 +71,16 @@ describe('renderBadgeHtml (the shared, framework-agnostic markup)', () => {
 		expect(html).not.toContain('__memo')
 		expect(html).not.toContain('__dates')
 	})
+
+	it('carries the always-on compliance baseline (cue + verbatim scope line + strings-version) on every face', () => {
+		const html = renderBadgeHtml(payload)
+		expect(html).toContain('data-certrev-strings-version="2026-07"')
+		expect(html).toContain(
+			'Independent editorial review of this article’s text and sources. Not a product endorsement, nor medical advice.',
+		)
+		expect(html).toContain('data-ftc-line')
+		expect(html.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ')).toContain('Compensated expert')
+	})
 })
 
 describe('<certrev-badge> custom element', () => {

package/src/components/CertBadge.tsx

@@ -11,23 +11,44 @@
  * 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).
+ * `badgeStyle: 'compact'` collapses the reviewer block to a single line (name + credentials);
+ * `'full'` shows the photo, certified/updated dates, and the memo (per display flags). BOTH
+ * styles carry the compensation cue + FTC scope line (the always-on compliance disclosures).
+ *
+ * THEMING (WS6): presentation defaults come from `payload.content.display`; an optional
+ * `renderDef` prop layers a brand's validated themeable tokens (emitted as `--certrev-*`
+ * CSS custom properties) and its subtractive field-visibility on top. No `renderDef` → the
+ * CertREV preset default (theme output byte-identical to un-themed).
  */
 
 import type { CertContent, CertPayload } from '../contract/kernel.js'
 import { safeHttpUrl } from './escape.js'
 import { credentialSuffix, expertNameWithCredentials, formatDate, resolveDisplay } from './format.js'
+import {
+	CERT_SCOPE_LINE,
+	CERT_STRINGS_VERSION,
+	type CertRenderDef,
+	resolveRenderTheme,
+	themeCssVarDeclarations,
+} from './render-def.js'
 
 export interface CertBadgeProps {
 	/** The cryptographically-verified payload (from `getVerifiedEnvelope`). */
 	readonly payload: CertPayload
-	/** Optional accent override (else `display.accentColor`, else CertREV default). */
+	/** Optional accent override (else render-def, 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'
+	/**
+	 * The brand render-def (WS6). ABSENT → the badge renders the CertREV preset
+	 * default (fail-safe; theme output byte-identical to un-themed). PRESENT → its
+	 * validated themeable tokens are emitted as `--certrev-*` CSS custom properties
+	 * and its subtractive hide-set removes brand-toggleable fields. Invalid tokens
+	 * are dropped (defense-in-depth over the write-path gate).
+	 */
+	readonly renderDef?: CertRenderDef
 }
 
 const ROOT_CLASS = 'certrev-badge'
@@ -70,7 +91,8 @@ function ExpertPhoto({ content, show }: { content: CertContent; show: boolean })
 export function CertBadge(props: CertBadgeProps) {
 	const { payload } = props
 	const content = payload.content
-	const display = resolveDisplay(content.display, props.accentColor)
+	const display = resolveDisplay(content.display, props.accentColor, props.renderDef)
+	const theme = resolveRenderTheme(props.renderDef)
 	const style = props.badgeStyle ?? display.badgeStyle
 	const verifyUrl = safeHttpUrl(content.verifyUrl)
 	const profileUrl = safeHttpUrl(content.expert.profileUrl)
@@ -82,10 +104,13 @@ export function CertBadge(props: CertBadgeProps) {
 	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.
+	// A THEMED brand additionally emits the surface/radius/font vars; with no render-def
+	// `themeCssVarDeclarations` is empty, so the un-themed style is byte-identical.
 	const rootStyle: Record<string, string> = {
 		['--certrev-accent']: accent,
 		borderInlineStartColor: accent,
 	}
+	for (const [name, value] of themeCssVarDeclarations(theme)) rootStyle[name] = value
 
 	const expertName = (
 		<span className={`${ROOT_CLASS}__expert-name`}>
@@ -99,6 +124,8 @@ export function CertBadge(props: CertBadgeProps) {
 			className={rootClass}
 			style={rootStyle}
 			data-certrev-cert-id={payload.certId}
+			data-certrev-strings-version={CERT_STRINGS_VERSION}
+			data-certrev-def-version={theme.version}
 			aria-label={`Content reviewed by ${expertNameWithCredentials(content)}`}
 		>
 			<div className={`${ROOT_CLASS}__header`}>
@@ -149,6 +176,31 @@ export function CertBadge(props: CertBadgeProps) {
 				</>
 			) : null}
 
+			{/* Design guide §3: the compensation cue + FTC scope line are LOCKED on every
+			    claim-bearing face (named / credentialed / memo) — with or without a memo —
+			    so a brand can never show an endorsement impression without its disclosures.
+			    cert-block only ever renders a claim face (it always carries the reviewer
+			    byline), so both lines render on both the full AND compact styles. This is
+			    the compliance BASELINE — it lands regardless of a render-def, matching the
+			    Shopify/WordPress engine fix. The cue's "expert" links to the reviewer's
+			    CertREV profile (the whole cue tag-strips to the byte-verbatim
+			    COMPENSATED_EXPERT_CUE). The scope line is byte-verbatim CERT_SCOPE_LINE. */}
+			<div className={`${ROOT_CLASS}__disclosure`}>
+				<span className={`${ROOT_CLASS}__compensated-cue`}>
+					Compensated{' '}
+					{profileUrl ? (
+						<a className={`${ROOT_CLASS}__cue-link`} href={profileUrl} rel="noopener">
+							expert
+						</a>
+					) : (
+						'expert'
+					)}
+				</span>
+				<p className={`${ROOT_CLASS}__ftc`} data-ftc-disclosure>
+					<span data-ftc-line>{CERT_SCOPE_LINE}</span>
+				</p>
+			</div>
+
 			{verifyUrl ? (
 				<a
 					className={`${ROOT_CLASS}__verify`}

package/src/components/CertReview.tsx

@@ -11,6 +11,7 @@
 import type { CertVerdict } from '../contract/kernel.js'
 import { CertBadge } from './CertBadge.js'
 import { CertJsonLd } from './CertJsonLd.js'
+import type { CertRenderDef } from './render-def.js'
 
 export interface CertReviewProps {
 	/** The verdict from `getVerifiedEnvelope` (or a direct kernel call). */
@@ -20,6 +21,12 @@ export interface CertReviewProps {
 	readonly accentColor?: string
 	readonly className?: string
 	readonly badgeStyle?: 'full' | 'compact'
+	/**
+	 * The brand render-def (WS6). Forwarded to `<CertBadge>` for themeable-token
+	 * emission + subtractive visibility; absent → the CertREV preset default. The
+	 * JSON-LD is presentation-blind, so the def never touches the structured data.
+	 */
+	readonly renderDef?: CertRenderDef
 	/** Omit the JSON-LD (e.g. the page already emits it elsewhere). Default false. */
 	readonly omitJsonLd?: boolean
 }
@@ -35,6 +42,7 @@ export function CertReview(props: CertReviewProps) {
 				accentColor={props.accentColor}
 				className={props.className}
 				badgeStyle={props.badgeStyle}
+				renderDef={props.renderDef}
 			/>
 			{props.omitJsonLd ? null : <CertJsonLd payload={payload} pageUrl={props.pageUrl} />}
 		</>

package/src/components/format.ts

@@ -4,6 +4,7 @@
  */
 
 import type { CertContent, CertDisplayConfig } from '../contract/kernel.js'
+import { type CertRenderDef, isFieldHidden, resolveRenderTheme } from './render-def.js'
 
 /** Default accent if the brand didn't pin one (CertREV teal). */
 export const DEFAULT_ACCENT = '#0f766e'
@@ -16,13 +17,29 @@ export interface ResolvedDisplay {
 	readonly badgeStyle: 'full' | 'compact'
 }
 
-/** Resolve the optional display config to concrete presentation flags + accent. */
-export function resolveDisplay(display: CertDisplayConfig | undefined, accentOverride?: string): ResolvedDisplay {
+/**
+ * Resolve the optional display config + optional brand render-def to concrete
+ * presentation flags + accent.
+ *
+ * Accent PRECEDENCE mirrors the Shopify Liquid engine exactly: an explicit
+ * `accentOverride` (a block/prop override) wins, then the render-def's validated
+ * accent (a THEMED brand), then the signed display's accent, else the CertREV
+ * default. Visibility is SUBTRACTIVE: the render-def's hide-set can only turn a
+ * preset-placed field OFF (never on) — a hidden `reviewerPhoto` / `memo` wins over
+ * a display flag that shows it. When no render-def is supplied the theme resolves
+ * empty, so accent + visibility are byte-identical to the pre-theming behavior.
+ */
+export function resolveDisplay(
+	display: CertDisplayConfig | undefined,
+	accentOverride?: string,
+	renderDef?: CertRenderDef,
+): ResolvedDisplay {
+	const theme = resolveRenderTheme(renderDef)
 	return {
-		accentColor: accentOverride ?? display?.accentColor ?? DEFAULT_ACCENT,
-		showExpertPhoto: display?.showExpertPhoto ?? true,
+		accentColor: accentOverride ?? theme.accent ?? display?.accentColor ?? DEFAULT_ACCENT,
+		showExpertPhoto: (display?.showExpertPhoto ?? true) && !isFieldHidden(renderDef, 'reviewerPhoto'),
 		showAuthor: display?.showAuthor ?? true,
-		showMemo: display?.showMemo ?? true,
+		showMemo: (display?.showMemo ?? true) && !isFieldHidden(renderDef, 'memo'),
 		badgeStyle: display?.badgeStyle ?? 'full',
 	}
 }