@certrev/cert-block 0.3.0 → 0.5.0

package/src/builder/cert-chrome-data.ts

@@ -0,0 +1,159 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * `BuilderCertChromeData` — the CANONICAL headless cert-chrome wire type
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * The brand-render projection of the cert envelope (portal POR-10091) — the OPTIONS
+ * of a brand's native cert component (e.g. e.l.f.'s registered `CertReviewCard`) on
+ * a headless blocks-mode entry (Builder.io). CertREV serves the data + the ready-made
+ * strings; the brand renders it within the design-guide ladder (enforced live by the
+ * crawl monitor + the MSA anti-stripping teeth).
+ *
+ * SINGLE SOURCE (POR-10721 W1): this type is HOMED HERE so the portal exporter
+ * (`src/lib/builder/cert-chrome.ts`) and the kit component (`CertReviewCard`) +
+ * `BUILDER_REGISTRATION.inputs` all reference ONE definition — killing the drift the
+ * hand-rolled Hydrogen-replica component suffered (it carried a stale separate
+ * `credential`/`credentialVerifiedAt` shape from before the fused-pair projection).
+ * Keep byte-for-byte in sync with the portal interface until the portal migrates to
+ * import THIS (that migration is gated on publishing the package that carries it).
+ *
+ * PURITY: types + a pure key tuple only — no runtime deps, tree-shakeable.
+ */
+
+/**
+ * The baked render-def projection (the Shopify `render_def` metafield shape) the
+ * exporter delivers so a brand's Builder face themes byte-identically to its Shopify
+ * face. The component maps `{ tokens, version }` onto `renderCertBlock`'s theme +
+ * `data-certrev-def-version` stamp. Structurally matches the portal's
+ * `ShopifyRenderDefMetafield` (single-sourcing that metafield type too is a follow-up).
+ */
+export interface CertChromeRenderDef {
+	/** Monotonic per-brand def version → the `data-certrev-def-version` stamp. */
+	readonly v: number
+	readonly preset: string
+	readonly rung: string
+	/**
+	 * The resolved themeable tokens (the baked metafield's `tokens`) — includes the v2
+	 * `barInk`/`inkColor`, so this is a superset of the input `CertThemeTokens` (which
+	 * predates brand-ink theming). Inlined structurally to match what the exporter bakes.
+	 */
+	readonly tokens: {
+		readonly accentColor?: string
+		readonly surface?: string
+		readonly cornerRadius?: string
+		readonly fontSlot?: string
+		readonly barInk?: string
+		readonly inkColor?: string
+	}
+	/** The auto-contrast bar foreground — present only on a barInk-themed face (v2). */
+	readonly barInkFg?: '#141414' | '#ffffff'
+	/** The subtractive field-visibility hide-set. */
+	readonly hidden: readonly string[]
+	/** v2 layout axis. Omitted ⇒ 'banner'. */
+	readonly layout?: string
+	/** Custom-face composition — present only when layout === 'custom'. */
+	readonly customFace?: { readonly placedFields: readonly string[] }
+}
+
+/**
+ * The OPTIONS a brand's native cert component receives. Delivered per certified
+ * article; until the brand registers the component the block renders nothing.
+ */
+export interface BuilderCertChromeData {
+	/**
+	 * The credentialed byline — credential + dated CertREV verification as ONE
+	 * inseparable string. Null when the R1 gate fails (a displayed credential is
+	 * unverified / missing `verified_at`); the brand then has only `bylinePlain`.
+	 */
+	bylineCredentialed: string | null
+	/**
+	 * The RAW verified credential welded to its dated verification, delivered as ONE
+	 * INSEPARABLE PAIR (present together) or `null` (omitted together). The WHOLE
+	 * point: the type hands the brand `credential` and `verifiedAt` only as the two
+	 * keys of one object, so a bare credential without its dated verification is
+	 * UNCONSTRUCTIBLE — the fused-verification invariant enforced by construction, not
+	 * a hopeful side rule. Non-null iff `bylineCredentialed` is. The sidebar/banner
+	 * faces map this to their `credential` + `credentialVerifiedAt` inputs.
+	 */
+	credentialVerification: { credential: string; verifiedAt: string } | null
+	/** The name-only byline (`Reviewed [date] by [Name].`). Always present. */
+	bylinePlain: string
+	/** The reviewer's resolved professional name (QA-safe), raw, for a name-only layout. */
+	reviewerName: string
+	/** Reviewer's short verified bio, or null (verified-only). */
+	bio: string | null
+	/** Reviewer's longer verified background, or null (verified-only). */
+	background: string | null
+	/** The QA-SCREENED `verifiedExpertMemo` (never the raw in-flight `expertMemo`), or null. */
+	memo: string | null
+	/** The compensation cue (`Compensated expert`). Null for a pro-bono reviewer. */
+	compensationCue: string | null
+	/** The verbatim FTC scope disclaimer. Always present. */
+	scopeLine: string
+	/** Reviewer photo URL (cert-frozen override ?? live), or null. */
+	reviewerPhoto: string | null
+	/** The CertREV expert-profile URL (`certrev.com/expert/{id}`) — never LinkedIn. */
+	reviewerProfileUrl: string | null
+	/** The public certificate-verification URL (`/verify/{id}`). */
+	verifyUrl: string
+	/** When the article was certified (ISO 8601) — the same date baked into the bylines. */
+	certifiedAt: string
+	/** The last real content change after certification (ISO 8601), or null. */
+	contentModifiedAt: string | null
+	/** The article's AUTHOR (a different person from the reviewer; carries no verification claim). */
+	authorName: string | null
+	authorTitle: string | null
+	/** Brand display prefs the rendering component honors. */
+	display: {
+		showExpertPhoto: boolean
+		/** When false the component renders `bylinePlain` even if the credentialed form was delivered. */
+		showCredentials: boolean
+	}
+	/** The brand's ACTIVE resolved render-def projection, or null (⇒ preset default). */
+	renderDef: CertChromeRenderDef | null
+	/** Version of the delivered string set (`data-certrev-strings-version` for the crawl monitor). */
+	stringsVersion: string
+}
+
+/**
+ * The ordered keys of `BuilderCertChromeData` — the SINGLE SOURCE the Builder
+ * `inputs` array and the W3 exporter⇄inputs⇄wire-type parity lock derive from, so
+ * the three can never silently drift again (POR-10721 W3). Adding a field to the
+ * interface without adding it here (or vice-versa) fails the `keyof` exhaustiveness
+ * check in `assertChromeKeysExhaustive` below.
+ */
+export const BUILDER_CERT_CHROME_KEYS = [
+	'bylineCredentialed',
+	'credentialVerification',
+	'bylinePlain',
+	'reviewerName',
+	'bio',
+	'background',
+	'memo',
+	'compensationCue',
+	'scopeLine',
+	'reviewerPhoto',
+	'reviewerProfileUrl',
+	'verifyUrl',
+	'certifiedAt',
+	'contentModifiedAt',
+	'authorName',
+	'authorTitle',
+	'display',
+	'renderDef',
+	'stringsVersion',
+] as const
+
+export type BuilderCertChromeKey = (typeof BUILDER_CERT_CHROME_KEYS)[number]
+
+/**
+ * Compile-time proof that `BUILDER_CERT_CHROME_KEYS` === `keyof BuilderCertChromeData`
+ * exactly (both directions). If a field is added/removed on the interface without the
+ * matching key edit, ONE of these two assignments stops type-checking — so the tuple
+ * can never drift from the type silently.
+ */
+const _keysCoverType: Record<keyof BuilderCertChromeData, true> = Object.fromEntries(
+	BUILDER_CERT_CHROME_KEYS.map((k) => [k, true]),
+) as Record<BuilderCertChromeKey, true>
+const _typeCoversKeys: Record<BuilderCertChromeKey, true> = _keysCoverType
+void _typeCoversKeys

package/src/builder/cert-review-card.tsx

@@ -0,0 +1,177 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * `CertReviewCard` — the ready-to-register Builder.io PUSH cert component (W1)
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * A headless brand (e.l.f.) registers `BUILDER_REGISTRATION` in its Builder
+ * `customComponents` and CertREV's exporter emits a block whose options are the
+ * `BuilderCertChromeData` projection — so the visible cert chrome renders itself,
+ * design-identical to the Shopify Liquid + WordPress PHP faces (same `renderCertBlock`
+ * string renderer). This REPLACES the ~200-line hand-rolled component every headless
+ * brand copied from the demo (POR-10721 W1).
+ *
+ * Improvements over the canary demo's hand-rolled version:
+ *  - consumes the CANONICAL `BuilderCertChromeData` (the fused `credentialVerification`
+ *    pair — a credential is UNCONSTRUCTIBLE without its dated verification), not the
+ *    demo's stale separate `credential`/`credentialVerifiedAt` fields;
+ *  - maps v2 `barInk`/`inkColor` into the theme (the demo predated brand-ink theming);
+ *  - honors `display.showCredentials`.
+ */
+
+import { type CertBlockMode, renderCertBlock } from '../components/render-cert-block.js'
+import type { ResolvedBlockTheme } from '../components/render-def.js'
+import type { BuilderCertChromeData } from './cert-chrome-data.js'
+import { BUILDER_CERT_CHROME_KEYS } from './cert-chrome-data.js'
+
+/**
+ * The canonical Builder block name. A brand's registration + the portal
+ * `certComponent` connection field default to THIS; config exists only for
+ * deviation (portal `client-for-brand.ts` gains the default in a follow-up).
+ */
+export const CERT_COMPONENT_NAME = 'CertREV Cert'
+
+export interface CertReviewCardProps extends Partial<BuilderCertChromeData> {
+	/** Placement face — the ENTRY/editor chooses this, NOT the exporter (not a wire-type field). */
+	mode?: CertBlockMode | null
+	/**
+	 * Banner memo placement (not a wire-type field — the ENTRY/editor chooses it). Passed
+	 * straight through to `renderCertBlock`'s first-class `part` (POR-10741): `'full'`
+	 * (default) renders header + memo in one block; `'header'`/`'memo'` render only that
+	 * card so the memo can be placed as its own block under the article body. The old
+	 * string-splitting shim is gone — `renderCertBlock` composes each part directly.
+	 */
+	part?: 'full' | 'header' | 'memo' | null
+}
+
+export function CertReviewCard(props: CertReviewCardProps) {
+	const { reviewerName, verifyUrl } = props
+	if (!reviewerName || !verifyUrl) return null // no chrome pre-cert
+
+	// The credential + its verification date arrive ONLY as the fused pair, so we can
+	// never obtain one without the other (name-only face when the pair is null, or when
+	// the brand set showCredentials:false). This IS the R1 gate, enforced by the type.
+	const cv = props.credentialVerification ?? null
+	const showCred = props.display?.showCredentials !== false
+	const withCred = cv && showCred ? cv : null
+
+	const tokens = props.renderDef?.tokens
+	const theme: Partial<ResolvedBlockTheme> | undefined = tokens
+		? {
+				accentColor: tokens.accentColor,
+				surface: tokens.surface,
+				cornerRadius: tokens.cornerRadius,
+				fontSlot: tokens.fontSlot as ResolvedBlockTheme['fontSlot'] | undefined,
+				// v2 brand-ink (post-demo): the bar + free-content ink follow the def.
+				barInk: tokens.barInk,
+				inkColor: tokens.inkColor,
+			}
+		: undefined
+
+	const html = renderCertBlock({
+		mode: (props.mode as CertBlockMode) ?? 'banner',
+		theme,
+		// First-class banner memo split (POR-10741) — renderCertBlock composes the requested
+		// part directly; no string-splitting. Ignored outside banner mode.
+		...(props.part ? { part: props.part } : {}),
+		facts: {
+			authorName: props.authorName ?? 'Editorial',
+			authorTitle: props.authorTitle ?? undefined,
+			reviewerName,
+			credential: withCred ? withCred.credential : '',
+			credentialVerifiedAt: withCred ? withCred.verifiedAt : '',
+			certifiedAt: props.certifiedAt ?? '',
+			memo: props.memo ?? '',
+			bio: props.bio ?? undefined,
+			profileUrl: props.reviewerProfileUrl ?? '',
+			certificateUrl: verifyUrl,
+			// Locked strings default byte-verbatim inside renderCertBlock; pass the
+			// delivered cue/scope through so a pro-bono (null-cue) delivery is honored.
+			...(props.compensationCue ? { compensationCue: props.compensationCue } : {}),
+			...(props.scopeLine ? { scopeLine: props.scopeLine } : {}),
+		},
+	})
+
+	return (
+		<div
+			data-certrev-cert-chrome=""
+			data-certrev-strings-version={props.stringsVersion ?? undefined}
+			data-certrev-def-version={props.renderDef?.v ?? undefined}
+			// biome-ignore lint/security/noDangerouslySetInnerHtml: renderCertBlock is the escaping-safe SSR string renderer
+			dangerouslySetInnerHTML={{ __html: html }}
+		/>
+	)
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Builder.io registration — inputs SINGLE-SOURCED from the wire-type keys (W1/W3)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** The subset of the Builder.io input schema this kit emits. */
+export interface BuilderInput {
+	readonly name: string
+	readonly type: 'string' | 'longText' | 'object' | 'boolean' | 'number'
+	readonly friendlyName?: string
+	readonly helperText?: string
+}
+
+/** Builder input TYPE per wire-type key — the exporter serializes these option values. */
+const WIRE_INPUT_TYPE: Record<(typeof BUILDER_CERT_CHROME_KEYS)[number], BuilderInput['type']> = {
+	bylineCredentialed: 'string',
+	credentialVerification: 'object',
+	bylinePlain: 'string',
+	reviewerName: 'string',
+	bio: 'longText',
+	background: 'longText',
+	memo: 'longText',
+	compensationCue: 'string',
+	scopeLine: 'string',
+	reviewerPhoto: 'string',
+	reviewerProfileUrl: 'string',
+	verifyUrl: 'string',
+	certifiedAt: 'string',
+	contentModifiedAt: 'string',
+	authorName: 'string',
+	authorTitle: 'string',
+	display: 'object',
+	renderDef: 'object',
+	stringsVersion: 'string',
+}
+
+/**
+ * The wire-type inputs — DERIVED from `BUILDER_CERT_CHROME_KEYS`, so the 19-field
+ * option set can never drift from the type (the W3 lock asserts name-parity). This
+ * kills the demo's hand-maintained 17-entry array.
+ */
+export const WIRE_INPUTS: readonly BuilderInput[] = BUILDER_CERT_CHROME_KEYS.map((name) => ({
+	name,
+	type: WIRE_INPUT_TYPE[name],
+}))
+
+/** Placement inputs — chosen by the entry/editor, NOT emitted by the exporter (not wire-type keys). */
+export const PLACEMENT_INPUTS: readonly BuilderInput[] = [
+	{
+		name: 'mode',
+		type: 'string',
+		friendlyName: 'Placement',
+		helperText: 'banner (default) · sidebar · floating',
+	},
+	{ name: 'part', type: 'string', friendlyName: 'Banner part', helperText: 'full (default) · header · memo' },
+]
+
+/** A Builder.io custom-component registration (the general shape; the anchor uses the same). */
+export interface CertBlockBuilderRegistration {
+	readonly name: string
+	readonly component: typeof CertReviewCard
+	readonly inputs: readonly BuilderInput[]
+}
+
+/**
+ * Ready to spread into a brand's Builder `customComponents`:
+ * `Builder.registerComponent(BUILDER_REGISTRATION.component, BUILDER_REGISTRATION)`.
+ * The exporter-emitted option keys === these `inputs` === the wire type — locked by W3.
+ */
+export const BUILDER_REGISTRATION: CertBlockBuilderRegistration = {
+	name: CERT_COMPONENT_NAME,
+	component: CertReviewCard,
+	inputs: [...PLACEMENT_INPUTS, ...WIRE_INPUTS],
+}

package/src/builder/index.tsx

@@ -120,3 +120,21 @@ export const certRevAnchorComponent: CertRevBuilderRegistration = {
 	name: 'CertREV Review',
 	inputs: [],
 }
+
+// ── POR-10721 W1/W3: the Builder.io PUSH kit (CertReviewCard) + single-sourced wire type ──
+export {
+	BUILDER_CERT_CHROME_KEYS,
+	type BuilderCertChromeData,
+	type BuilderCertChromeKey,
+	type CertChromeRenderDef,
+} from './cert-chrome-data.js'
+export {
+	BUILDER_REGISTRATION,
+	type BuilderInput,
+	CERT_COMPONENT_NAME,
+	type CertBlockBuilderRegistration,
+	CertReviewCard,
+	type CertReviewCardProps,
+	PLACEMENT_INPUTS,
+	WIRE_INPUTS,
+} from './cert-review-card.js'

package/src/components/preview-block.ts

@@ -0,0 +1,74 @@
+/**
+ * `renderPreviewBlock` — a STATIC, NON-DELIVERY preview of the cert block for pre-sales
+ * look-demos (POR-10743, from the e.l.f. Builder demo).
+ *
+ * The visual is BYTE-FOR-BYTE `renderCertBlock` (pixel-parity — "see it on your own site
+ * today"), wrapped in a `[data-certrev-preview]` container carrying a REQUIRED expiry.
+ *
+ * Why it is safe by construction — and can NEVER be delivery:
+ *  - A preview has NO signed envelope and NO modal. CertREV's verify / badge-revalidation /
+ *    crawl-audit all key off a signed `CertDeliveryEnvelope`; an unsigned block is SUPPRESSED
+ *    on any live verify, never rendered as a certification. So a preview literally cannot pass
+ *    as a delivered cert — the "never delivery" property is structural, not a policy.
+ *  - The container marker (`data-certrev-preview="1"`) + the default-on visible label make it
+ *    unmistakable to humans AND tooling; the required `data-certrev-preview-expires` bounds its
+ *    life so a stale snapshot can be refused downstream.
+ *  - It is NOT revocable — the kill-switch cannot reach a static HTML snapshot — so it must stay
+ *    demo / draft-only. That is the CALLER's duty; this renderer bakes the markers that let the
+ *    surrounding systems enforce it.
+ */
+
+import { escapeAttribute, escapeHtml } from './escape.js'
+import { type RenderCertBlockInput, renderCertBlock } from './render-cert-block.js'
+
+export interface PreviewBlockOptions {
+	/**
+	 * REQUIRED — when this preview expires (ISO 8601). A preview MUST be time-bounded so a stale
+	 * snapshot can be refused downstream; there is deliberately NO default (an unbounded preview
+	 * is the drift-into-shadow-delivery risk this option exists to prevent).
+	 */
+	readonly expiresAt: string
+	/**
+	 * Show the visible caption. Default `true` — the SAFE default. Opt out (`false`) ONLY for a
+	 * true pixel-parity look-demo; the machine marker + expiry + non-delivery guarantee remain.
+	 */
+	readonly showLabel?: boolean
+	/** Override the caption text (default below). */
+	readonly labelText?: string
+}
+
+const DEFAULT_LABEL = 'Preview — not a verified certification'
+
+/** Extract a preview block's baked expiry (ISO), or null if the HTML isn't a preview block. */
+export function previewExpiry(html: string): string | null {
+	const m = html.match(/data-certrev-preview-expires="([^"]*)"/)
+	return m ? m[1] : null
+}
+
+/**
+ * Render a static, clearly-labeled, time-bounded preview of the cert block. See the module doc
+ * for the safety model. `expiresAt` is required; throws without it.
+ */
+export function renderPreviewBlock(input: RenderCertBlockInput, options: PreviewBlockOptions): string {
+	const expires = options.expiresAt.trim()
+	if (!expires) {
+		throw new Error('renderPreviewBlock: `expiresAt` is required — a preview must be time-bounded.')
+	}
+	// The bound must be REAL — an unparseable expiry is a toothless bound (downstream can't refuse a
+	// stale preview it can't date). Reject anything Date can't parse, so `previewExpiry()` consumers
+	// always get a usable timestamp.
+	if (Number.isNaN(new Date(expires).getTime())) {
+		throw new Error(`renderPreviewBlock: \`expiresAt\` must be a parseable date (got "${expires}").`)
+	}
+	const showLabel = options.showLabel !== false
+	const label = showLabel
+		? `<div data-certrev-preview-label style="font:500 11px/1.4 ui-monospace,SFMono-Regular,Menlo,monospace;letter-spacing:.08em;text-transform:uppercase;color:#9a9a9a;margin-bottom:8px;">${escapeHtml(options.labelText ?? DEFAULT_LABEL)}</div>`
+		: ''
+	return (
+		`<!-- CertREV PREVIEW — static, non-revocable, NOT a verified certification. Expires ${escapeHtml(expires)}. Never use as delivery. -->` +
+		`<div data-certrev-preview="1" data-certrev-preview-expires="${escapeAttribute(expires)}">` +
+		label +
+		renderCertBlock(input) +
+		`</div>`
+	)
+}