@certrev/cert-block 0.1.2 → 0.2.0

package/src/components/render-def.ts

@@ -0,0 +1,286 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Design-guide RENDER-DEF support (the themeable-token + subtractive-visibility
+ * layer) + the two always-on COMPLIANCE strings.
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * WS6 of the unified cert-render / design-guide build
+ * (~/.claude-account-m/plans/smooth-meandering-graham.md). This is the Builder /
+ * headless projection twin's half of the "law-as-code" contract: cert-block is one
+ * of the four render surfaces (Shopify Liquid, WordPress PHP, JS engine, and this)
+ * that must paint the SAME compliant, optionally-themed badge from the SAME facts.
+ *
+ * cert-block is a self-contained npm package — it does NOT import the portal's
+ * `@/lib/design-guide` enforcement core. Instead it mirrors, at the RENDER edge,
+ * the small subset that shape the projection carries:
+ *
+ *   1. The four allowlisted THEMEABLE tokens `{accentColor, surface, cornerRadius,
+ *      fontSlot}`, emitted as the exact `--certrev-*` CSS custom properties the
+ *      Shopify/WordPress engines emit and the WS11 crawl monitor asserts
+ *      (`--certrev-accent` / `--certrev-surface` / `--certrev-radius` /
+ *      `--certrev-font`). Each is RE-VALIDATED here at render time (defense in
+ *      depth over the write-path fail-closed gate) against the SAME strict
+ *      validators the portal's `tokens.ts` uses, and an invalid value is DROPPED
+ *      (falls back to the preset default) — never emitted. `fontSlot` resolves to
+ *      a FIXED font STACK (never a free-form family — the CSS-injection surface).
+ *   2. SUBTRACTIVE field-visibility: a brand may only HIDE preset-placed,
+ *      brand-toggleable fields (`reviewerPhoto`, `memo`) — never add a field the
+ *      preset doesn't place. Locked fields (cue, scope, links) can never be hidden.
+ *   3. The two always-on COMPLIANCE strings a claim-bearing face carries on EVERY
+ *      rung (design guide §3): the compensation cue and the FTC scope line, both
+ *      byte-verbatim (the scope line's curly apostrophe U+2019 is load-bearing).
+ *
+ * FAIL-SAFE: when NO render-def is supplied the THEMING layer contributes nothing
+ * — no extra CSS vars, no `data-certrev-def-version`, no visibility subtraction —
+ * so the badge's theme output is byte-identical to the un-themed default (the
+ * program's no-op / merge-safety device). The compensation cue + scope line + the
+ * `data-certrev-strings-version` stamp are the compliance BASELINE and land on
+ * every claim face regardless of a def (matching the Shopify/WP engine fix).
+ *
+ * PURITY: no DOM, no Node builtins, no React — safe on every runtime the main
+ * entry targets (edge / Workers / server / client).
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Themeable token vocabulary (mirrors portal src/lib/design-guide/tokens.ts)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** The font ENUM. Resolves to a FIXED slot stack — never a free-form family. */
+export const FONT_SLOTS = ['sans', 'serif', 'system'] as const
+export type FontSlot = (typeof FONT_SLOTS)[number]
+
+/**
+ * The `fontSlot` → fixed font-stack literal. BYTE-IDENTICAL to the Shopify Liquid
+ * engine's stacks (`shopify/extensions/certrev-schema/snippets/certrev-badge.liquid`
+ * — the only font families the twins use), so a themed brand's Builder projection
+ * paints the same typography as its Shopify face. A raw family string in a
+ * `font-family` CSS var is a CSS-injection surface AND breaks the "CertREV hosts no
+ * fonts" invariant, so the enum → stack indirection is the security boundary.
+ */
+export const FONT_STACKS: Readonly<Record<FontSlot, string>> = {
+	sans: "'DM Sans', system-ui, -apple-system, BlinkMacSystemFont, sans-serif",
+	serif: "'Playfair Display', Georgia, 'Times New Roman', serif",
+	system: "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
+}
+
+/** A fully-resolved themeable token set (a brand overrides a subset of these). */
+export interface CertThemeTokens {
+	readonly accentColor: string
+	readonly surface: string
+	readonly cornerRadius: string
+	readonly fontSlot: FontSlot
+}
+
+/** The badge fields a render-def may SUBTRACTIVELY hide (brand-toggleable, free). */
+export const HIDEABLE_FIELDS = ['reviewerPhoto', 'memo'] as const
+export type BadgeVisibilityFieldId = (typeof HIDEABLE_FIELDS)[number]
+
+/**
+ * A brand render-def as it reaches the render edge — the RESOLVED projection the
+ * portal's `getActiveRenderDef` → cert-chrome/builder-export path carries (mirrors
+ * the Shopify `certrev.render_def` metafield `{v, preset, rung, tokens, hidden}`;
+ * cert-block needs only the theming inputs). Every field is OPTIONAL: an absent
+ * `renderDef`, an absent token, or an invalid token all fall back to the preset
+ * default (fail-safe).
+ */
+export interface CertRenderDef {
+	/** Partial themeable-token overrides. Absent/invalid keys use the preset default. */
+	readonly tokens?: Partial<CertThemeTokens>
+	/** SUBTRACTIVE hide-set — the ONLY visibility a brand can express. */
+	readonly hidden?: readonly BadgeVisibilityFieldId[]
+	/** Monotonic per-brand def version, stamped as `data-certrev-def-version`. */
+	readonly version?: number
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Per-token validators (strict, CSS-injection-safe — no trim, exact match)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** 3- or 6-digit hex with a leading `#` — opaque by construction (no alpha). */
+const HEX_OPAQUE = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/
+
+/** A single CSS length: a non-negative number with a `px|rem|em|%` unit, or bare `0`. */
+const RADIUS = /^(?:0|(?:\d+(?:\.\d+)?|\.\d+)(?:px|rem|em|%))$/
+
+/** `accentColor` / `surface` — an opaque hex (surface opacity is FORCED for contrast soundness). */
+export function isOpaqueHexColor(value: string): boolean {
+	return HEX_OPAQUE.test(value)
+}
+
+/** `cornerRadius` — a single unit-bearing CSS length (or bare `0`). */
+export function isCornerRadius(value: string): boolean {
+	return RADIUS.test(value)
+}
+
+/** Is `value` a known font slot? */
+export function isFontSlot(value: string): value is FontSlot {
+	return (FONT_SLOTS as readonly string[]).includes(value)
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The two always-on compliance strings (byte-verbatim — never re-word here)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The compensation cue (design guide "line A"). Rendered beside the reviewer on
+ * EVERY claim-bearing face. Byte-exact; the tag-stripped visible text of the cue
+ * markup must equal this constant. Mirrors portal `COMPENSATED_EXPERT_CUE`.
+ */
+export const COMPENSATED_EXPERT_CUE = 'Compensated expert'
+
+/**
+ * The FTC scope disclaimer (design guide "line B"). Byte-verbatim; the curly
+ * apostrophe (U+2019) in "article’s" is LOAD-BEARING (the MSA §3 references this
+ * copy in the present tense). Mirrors portal `FTC_DISCLOSURE_LINE` / `CERT_SCOPE_LINE`.
+ */
+export const CERT_SCOPE_LINE =
+	'Independent editorial review of this article’s text and sources. Not a product endorsement, nor medical advice.'
+
+/**
+ * The delivered display-string EDITION, stamped as `data-certrev-strings-version`
+ * so the crawl monitor can assert which verbatim strings a live face should carry.
+ * MUST equal the portal's `CERT_DISPLAY_STRINGS_VERSION` (display-strings.ts).
+ * Bump in lockstep whenever the cue or scope line changes.
+ */
+export const CERT_STRINGS_VERSION = '2026-07'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Resolution
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The validated theme a render-def resolves to. Every field is present ONLY when
+ * the def supplied a VALID value for it (an absent/invalid token is dropped so the
+ * preset default shows through). `accent` is surfaced for the accent-precedence
+ * chain in `resolveDisplay`; `surface`/`cornerRadius`/`fontStack` have no legacy
+ * display equivalent and are emitted ONLY on a themed face.
+ */
+export interface ResolvedRenderTheme {
+	readonly accent?: string
+	readonly surface?: string
+	readonly cornerRadius?: string
+	readonly fontStack?: string
+	readonly version?: number
+}
+
+/** Resolve + re-validate a render-def's tokens. Invalid values are DROPPED (fail-safe). */
+export function resolveRenderTheme(def?: CertRenderDef): ResolvedRenderTheme {
+	if (!def) return {}
+	const t = def.tokens ?? {}
+	const accent = t.accentColor && isOpaqueHexColor(t.accentColor) ? t.accentColor : undefined
+	const surface = t.surface && isOpaqueHexColor(t.surface) ? t.surface : undefined
+	const cornerRadius = t.cornerRadius && isCornerRadius(t.cornerRadius) ? t.cornerRadius : undefined
+	const fontStack = t.fontSlot && isFontSlot(t.fontSlot) ? FONT_STACKS[t.fontSlot] : undefined
+	const version = typeof def.version === 'number' && Number.isFinite(def.version) ? def.version : undefined
+	return { accent, surface, cornerRadius, fontStack, version }
+}
+
+/** Is a brand-toggleable field hidden by this render-def's subtractive hide-set? */
+export function isFieldHidden(def: CertRenderDef | undefined, id: BadgeVisibilityFieldId): boolean {
+	return !!def?.hidden?.includes(id)
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Cert-render BLOCK theme — the resolved-token mirror of portal ResolvedRenderDef
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// `renderCertBlock` (render-cert-block.ts) paints the LOCKED CertREV cert design
+// (banner / sidebar / floating) from an ALREADY-RESOLVED token set — the portal
+// bakes `ResolvedRenderDef` (render-def.ts + tokens.ts) and the projection carries
+// its theme half here. This is a WIDER slot vocabulary than the `CertThemeTokens`
+// above (which the legacy `<CertBadge>` uses): it mirrors the portal's FULL
+// five-member `FontSlot` enum + the pre-computed `accentFg` ink, so the block can
+// reproduce the guide's four-font design (DM Sans body, Playfair memo, JetBrains
+// mono labels, Plus Jakarta wordmark). It is kept DISTINCT from `FONT_SLOTS` /
+// `FONT_STACKS` above so the legacy badge's three-slot contract stays byte-frozen.
+
+/**
+ * The full portal font-slot enum (mirrors portal `src/lib/design-guide/tokens.ts`
+ * `FONT_SLOTS`). `grotesk` ⇐ the guide's wordmark slot; `mono` ⇐ the label slot.
+ */
+export const RENDER_BLOCK_FONT_SLOTS = ['sans', 'serif', 'system', 'grotesk', 'mono'] as const
+export type RenderBlockFontSlot = (typeof RENDER_BLOCK_FONT_SLOTS)[number]
+
+/**
+ * The `RenderBlockFontSlot` → fixed family stack. BYTE-IDENTICAL to the portal's
+ * `FONT_SLOT_STACKS` (the guide's stacks — the cert-render parity anchor across the
+ * twins). Resolved family strings, never `var(...)` indirections. A raw family in a
+ * `font-family` CSS var is a CSS-injection surface, so the enum → stack indirection
+ * stays the security boundary (a caller can only pass an enum member).
+ */
+export const RENDER_BLOCK_FONT_STACKS: Readonly<Record<RenderBlockFontSlot, string>> = {
+	sans: "'DM Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif",
+	serif: "'Playfair Display', Georgia, 'Times New Roman', serif",
+	grotesk: "'Plus Jakarta Sans', system-ui, Helvetica, Arial, sans-serif",
+	mono: "'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, monospace",
+	system: "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif",
+}
+
+/** Is `value` a known render-block font slot? */
+export function isRenderBlockFontSlot(value: string): value is RenderBlockFontSlot {
+	return (RENDER_BLOCK_FONT_SLOTS as readonly string[]).includes(value)
+}
+
+/**
+ * The resolved themeable-token set `renderCertBlock` paints — the render-edge mirror
+ * of the portal `ResolvedRenderDef` theme half (`tokens` ⊕ the precomputed
+ * `accentFg`). `accentFg` is the ink painted over the accent fill — the portal's
+ * guide-faithful Rec.601 auto-contrast pick (`#141414` or `#ffffff`), carried
+ * pre-computed so this dumb twin never recomputes it.
+ */
+export interface ResolvedBlockTheme {
+	readonly accentColor: string
+	readonly surface: string
+	readonly cornerRadius: string
+	readonly fontSlot: RenderBlockFontSlot
+	readonly accentFg: '#141414' | '#ffffff'
+}
+
+/** The CertREV navy default theme (the un-themed face — matches the locked reference `:root`). */
+export const DEFAULT_BLOCK_THEME: ResolvedBlockTheme = {
+	accentColor: '#0a1b3f',
+	surface: '#ffffff',
+	cornerRadius: '14px',
+	fontSlot: 'sans',
+	accentFg: '#ffffff',
+}
+
+/**
+ * Re-validate a (possibly partial / untrusted) block theme at the render edge —
+ * defense in depth over the portal's fail-closed bake. Any invalid token is DROPPED
+ * to the navy default (never emitted into storefront CSS). Mirrors the
+ * `resolveRenderTheme` fail-safe posture.
+ */
+export function resolveBlockTheme(theme?: Partial<ResolvedBlockTheme>): ResolvedBlockTheme {
+	const t = theme ?? {}
+	return {
+		accentColor: t.accentColor && isOpaqueHexColor(t.accentColor) ? t.accentColor : DEFAULT_BLOCK_THEME.accentColor,
+		surface: t.surface && isOpaqueHexColor(t.surface) ? t.surface : DEFAULT_BLOCK_THEME.surface,
+		cornerRadius: t.cornerRadius && isCornerRadius(t.cornerRadius) ? t.cornerRadius : DEFAULT_BLOCK_THEME.cornerRadius,
+		fontSlot: t.fontSlot && isRenderBlockFontSlot(t.fontSlot) ? t.fontSlot : DEFAULT_BLOCK_THEME.fontSlot,
+		accentFg: t.accentFg === '#141414' || t.accentFg === '#ffffff' ? t.accentFg : DEFAULT_BLOCK_THEME.accentFg,
+	}
+}
+
+/**
+ * The locked verification ATTRIBUTION phrase, rendered grouped with the dated
+ * verification (`<name>, <credential>` → this → `on <date>`). Byte-exact; mirrors the
+ * fixed clause inside portal `buildBylineCredentialed` ("Credential verified by
+ * CertREV on …"). Never re-word without contract + legal re-review.
+ */
+export const CREDENTIAL_VERIFIED_ATTRIBUTION = 'Credential verified by CertREV'
+
+/**
+ * The extra `--certrev-*` custom-property declarations a THEMED face emits, in the
+ * engine's order (surface → radius → font; accent is emitted separately so the
+ * no-def output stays byte-identical). Returns `[]` when no theme is present, so
+ * the un-themed badge emits ZERO extra vars. The data-bearing values are already
+ * strict-validated; the font is a controlled literal stack.
+ */
+export function themeCssVarDeclarations(theme: ResolvedRenderTheme): ReadonlyArray<readonly [string, string]> {
+	const out: Array<readonly [string, string]> = []
+	if (theme.surface) out.push(['--certrev-surface', theme.surface])
+	if (theme.cornerRadius) out.push(['--certrev-radius', theme.cornerRadius])
+	if (theme.fontStack) out.push(['--certrev-font', theme.fontStack])
+	return out
+}

package/src/index.ts

@@ -36,6 +36,41 @@ export {
 	type ResolvedDisplay,
 	resolveDisplay,
 } from './components/format.js'
+// ── Cert-render BLOCK — the LOCKED 3-mode cert design as an SSR-safe HTML string ──
+export {
+	type CertBlockFacts,
+	type CertBlockMode,
+	type RenderCertBlockInput,
+	renderCertBlock,
+} from './components/render-cert-block.js'
+// ── Design-guide render-def support (WS6: themeable tokens + subtractive visibility) ──
+export {
+	type BadgeVisibilityFieldId,
+	CERT_SCOPE_LINE,
+	CERT_STRINGS_VERSION,
+	type CertRenderDef,
+	type CertThemeTokens,
+	COMPENSATED_EXPERT_CUE,
+	CREDENTIAL_VERIFIED_ATTRIBUTION,
+	DEFAULT_BLOCK_THEME,
+	FONT_SLOTS,
+	FONT_STACKS,
+	type FontSlot,
+	HIDEABLE_FIELDS,
+	isCornerRadius,
+	isFieldHidden,
+	isFontSlot,
+	isOpaqueHexColor,
+	isRenderBlockFontSlot,
+	RENDER_BLOCK_FONT_SLOTS,
+	RENDER_BLOCK_FONT_STACKS,
+	type RenderBlockFontSlot,
+	type ResolvedBlockTheme,
+	type ResolvedRenderTheme,
+	resolveBlockTheme,
+	resolveRenderTheme,
+	themeCssVarDeclarations,
+} from './components/render-def.js'
 // ── Contract surface (types + kernel) — re-export the binding point ────────────────
 // NOTE: the test/dev fixtures (makeSignedEnvelope, makeMockPayload, FIXTURE_KID) are
 // Node-only (they sign with node:crypto) and ship from the './fixtures' subpath, NOT here.

package/src/webcomponent/render-badge-html.ts

@@ -14,11 +14,25 @@
 
 import { escapeAttribute, escapeHtml, safeCssColor, safeHttpUrl } from '../components/escape.js'
 import { credentialSuffix, formatDate, resolveDisplay } from '../components/format.js'
+import {
+	CERT_SCOPE_LINE,
+	CERT_STRINGS_VERSION,
+	type CertRenderDef,
+	resolveRenderTheme,
+	themeCssVarDeclarations,
+} from '../components/render-def.js'
 import type { CertPayload } from '../contract/kernel.js'
 
 export interface RenderBadgeOptions {
 	readonly accentColor?: string
 	readonly badgeStyle?: 'full' | 'compact'
+	/**
+	 * The brand render-def (WS6). ABSENT → the badge renders the CertREV preset
+	 * default (theme output byte-identical to un-themed). PRESENT → validated
+	 * themeable tokens are emitted as `--certrev-*` CSS vars + subtractive
+	 * visibility applies. Mirrors `<CertBadge>`'s `renderDef` prop exactly.
+	 */
+	readonly renderDef?: CertRenderDef
 }
 
 const C = 'certrev-badge'
@@ -35,7 +49,8 @@ function attr(name: string, value: string | null | undefined): string {
  */
 export function renderBadgeHtml(payload: CertPayload, opts: RenderBadgeOptions = {}): string {
 	const content = payload.content
-	const display = resolveDisplay(content.display, opts.accentColor)
+	const display = resolveDisplay(content.display, opts.accentColor, opts.renderDef)
+	const theme = resolveRenderTheme(opts.renderDef)
 	const style = opts.badgeStyle ?? display.badgeStyle
 	const accent = safeCssColor(display.accentColor) ?? '#0f766e'
 	const verifyUrl = safeHttpUrl(content.verifyUrl)
@@ -91,16 +106,43 @@ export function renderBadgeHtml(payload: CertPayload, opts: RenderBadgeOptions =
 		if (dates.length) body += `<dl class="${C}__dates">${dates.join('')}</dl>`
 	}
 
+	// Design guide §3: the compensation cue + FTC scope line are LOCKED on every
+	// claim-bearing face (cert-block always carries the reviewer byline, so both
+	// render on the full AND compact styles). The compliance BASELINE — present
+	// regardless of a render-def, matching the Shopify/WordPress engine fix. The
+	// cue's "expert" links to the reviewer profile; the whole cue tag-strips to the
+	// byte-verbatim COMPENSATED_EXPERT_CUE. The scope line is byte-verbatim
+	// CERT_SCOPE_LINE (its curly apostrophe U+2019 survives escapeHtml untouched).
+	const cueInner = profileUrl
+		? `Compensated <a class="${C}__cue-link" href="${escapeAttribute(profileUrl)}" rel="noopener">expert</a>`
+		: 'Compensated expert'
+	const disclosure =
+		`<div class="${C}__disclosure">` +
+		`<span class="${C}__compensated-cue">${cueInner}</span>` +
+		`<p class="${C}__ftc" data-ftc-disclosure><span data-ftc-line>${escapeHtml(CERT_SCOPE_LINE)}</span></p>` +
+		`</div>`
+
 	const verify = verifyUrl
 		? `<a class="${C}__verify" href="${escapeAttribute(verifyUrl)}" rel="noopener" aria-label="Verify this certification on CertREV">Verify on CertREV</a>`
 		: ''
 
 	const ariaLabel = `Content reviewed by ${content.expert.displayName}${suffix ? `, ${suffix}` : ''}`
-	const rootStyle = `--certrev-accent:${accent};border-inline-start-color:${accent}`
+	// Accent LEADS so the un-themed output is byte-identical to the pre-WS6 single-var
+	// form. A THEMED brand appends surface/radius/font: the data-bearing tokens ride
+	// escaped (a no-op for validated hex/length — defense in depth), the font is a
+	// controlled literal stack emitted raw. The whole string is NOT re-escaped
+	// (the font stack's single quotes are valid inside a double-quoted attribute and
+	// re-escaping would corrupt them).
+	let rootStyle = `--certrev-accent:${escapeAttribute(accent)};border-inline-start-color:${escapeAttribute(accent)}`
+	for (const [name, value] of themeCssVarDeclarations(theme)) {
+		rootStyle += name === '--certrev-font' ? `;${name}:${value}` : `;${name}:${escapeAttribute(value)}`
+	}
 
 	return (
-		`<section class="${C} ${C}--${escapeAttribute(style)}" style="${escapeAttribute(rootStyle)}"` +
+		`<section class="${C} ${C}--${escapeAttribute(style)}" style="${rootStyle}"` +
 		attr('data-certrev-cert-id', payload.certId) +
-		` aria-label="${escapeAttribute(ariaLabel)}">${header}${body}${verify}</section>`
+		` data-certrev-strings-version="${CERT_STRINGS_VERSION}"` +
+		attr('data-certrev-def-version', theme.version != null ? String(theme.version) : null) +
+		` aria-label="${escapeAttribute(ariaLabel)}">${header}${body}${disclosure}${verify}</section>`
 	)
 }