@certrev/cert-block 0.5.4 → 1.0.0

package/src/jsonld/project.ts

@@ -9,21 +9,33 @@
  * server pre-render) produce the same structured data, and a snapshot diff is meaningful.
  *
  * DESIGN GOAL: MERGE, don't collide.
- *   A brand page usually already emits an `Article` (or `BlogPosting`) graph — Yoast on
- *   WordPress, the theme on Shopify, the framework on headless. If we emit a SECOND
- *   top-level `Article`, crawlers see two competing primary entities. Instead we emit a
- *   `@graph` whose Article node carries the SAME `@id` the page's primary article uses
- *   (the page URL + `#article`, the Yoast convention) so a consumer MERGES our
- *   `reviewedBy` / `dateModified` into the existing node by `@id` rather than duplicating
- *   it. Our own nodes (the review, the expert Person, the CertREV org) use CertREV-scoped
- *   `@id`s that cannot clash with the host page's nodes.
+ *   A brand page usually already emits a `WebPage` + `Article` (or `BlogPosting`) graph —
+ *   Yoast on WordPress, the theme on Shopify, the framework on headless. If we emit a
+ *   SECOND top-level `Article`, crawlers see two competing primary entities. Instead we
+ *   emit a `@graph` whose WebPage / Article nodes carry the SAME `@id`s the page's own
+ *   nodes use (the unmodified canonical URL for the page, the page URL + `#article` for
+ *   the article — the Yoast convention) so a consumer MERGES our `reviewedBy` /
+ *   `lastReviewed` / `dateModified` into the existing nodes by `@id` rather than
+ *   duplicating them. Our own nodes are keyed to the CERTIFICATION instead (the verify
+ *   URL, the expert's profile, the fixed CertREV organization id) — never under the host
+ *   page's `@id` namespace — so they cannot clash with the host page's nodes.
  *
  * The Person we attach is the reviewing EXPERT (schema.org `reviewedBy`), which is the
  * E-E-A-T signal CertREV exists to add — not the author. The author (content byline) is
  * attached as `author` only when present + distinct.
+ *
+ * VISIBILITY: "Don't mark up content that is not visible to readers" (Google's
+ * structured-data guidelines) is a HARD rule here, not a nicety. Every field on this
+ * graph that mirrors something the card paints behind a visibility flag — the memo, the
+ * author byline, the reviewer photo — is gated by the SAME `resolveDisplay` the card
+ * uses (which folds in the render-def's subtractive hide-set), so the graph can never
+ * assert to a crawler what the reader cannot see. Re-deriving those flags here instead
+ * of importing the card's resolver is exactly how the two would silently drift.
  */
 
-import type { CertContent, CertPayload } from '../contract/kernel.js'
+import { type ResolvedDisplay, resolveDisplay } from '../components/format.js'
+import type { CertRenderDef } from '../components/render-def.js'
+import type { CertPayload } from '../contract/kernel.js'
 
 /** A JSON-LD node/graph value. Loose by design — this is wire JSON, not a TS model. */
 export type JsonLdValue = Record<string, unknown>
@@ -31,12 +43,19 @@ export type JsonLdValue = Record<string, unknown>
 export interface ProjectJsonLdOptions {
 	/**
 	 * The canonical page URL the article renders on. Used to derive the primary
-	 * Article node `@id` (`${pageUrl}#article`) so we merge into the host page's graph
-	 * instead of colliding. When omitted, the first `subject.canonicalUrls` entry is
-	 * used; when there is none either, a CertREV-scoped article `@id` is derived from
-	 * `verifyUrl` (still mergeable, just not aligned to a host node).
+	 * WebPage / Article node `@id`s (`${pageUrl}` and `${pageUrl}#article`) so we merge
+	 * into the host page's graph instead of colliding. When omitted, the first
+	 * `subject.canonicalUrls` entry is used; when there is none either, the WebPage node
+	 * is DROPPED and a CertREV-scoped article `@id` is derived from `verifyUrl` (still
+	 * mergeable, just not aligned to a host node).
 	 */
 	readonly pageUrl?: string
+	/**
+	 * The brand render-def in force for THIS face. Read for its SUBTRACTIVE hide-set only
+	 * (its theming half means nothing to structured data): a brand that hides the memo or
+	 * the reviewer photo on the card must not have it published in the graph either.
+	 */
+	readonly renderDef?: CertRenderDef
 	/**
 	 * When true (default), emit the wrapping `{ "@context": "...", "@graph": [...] }`.
 	 * When false, return just the array of nodes — for a caller that merges them into an
@@ -47,6 +66,22 @@ export interface ProjectJsonLdOptions {
 
 const SCHEMA_CONTEXT = 'https://schema.org'
 
+/**
+ * THE CertREV organization node `@id` — a hard CONSTANT, not a per-payload derivation.
+ *
+ * It used to be `${new URL(verifyUrl).origin}/#certrev-organization` under a comment
+ * claiming "one stable CertREV organization node across all pages", which it was not: a
+ * cert served from a second verify origin (a staging/preview host, a vanity verify
+ * domain, a future regional origin) minted a SECOND CertREV org node that would never
+ * merge with the first. CertREV is ONE real-world organization; its node id must not
+ * move because of which host happened to serve a verify link. Portal must emit this
+ * exact literal for the two halves to merge — see the package README.
+ */
+export const CERTREV_ORGANIZATION_ID = 'https://certrev.com/#certrev-organization'
+
+/** CertREV's canonical homepage — the `url` of the organization node above, same reasoning. */
+export const CERTREV_ORGANIZATION_URL = 'https://certrev.com'
+
 /**
  * Strip the query AND fragment from a URL for a stable, mergeable @id. The Yoast / host
  * convention keys the primary Article node on `{path}#article` with no query — so a page
@@ -58,48 +93,73 @@ function baseUrl(url: string): string {
 	return url.slice(0, cut)
 }
 
+/**
+ * The page this face renders on — the caller's `pageUrl` first (it knows the actual
+ * request), else the payload's primary canonical. Null when neither is known, which is
+ * the ONLY honest answer: we then assert nothing about any page.
+ */
+function pageBaseUrl(payload: CertPayload, opts: ProjectJsonLdOptions): string | null {
+	const page = opts.pageUrl ?? payload.subject.canonicalUrls[0]
+	return page ? baseUrl(page) : null
+}
+
 /** Derive the primary Article `@id`, aligned to the Yoast/host convention when we can. */
 function articleId(payload: CertPayload, opts: ProjectJsonLdOptions): string {
-	const page = opts.pageUrl ?? payload.subject.canonicalUrls[0]
-	if (page) return `${baseUrl(page)}#article`
+	const page = pageBaseUrl(payload, opts)
+	if (page) return `${page}#article`
 	// No page URL known — derive a stable, mergeable id from the verify URL.
 	return `${baseUrl(payload.content.verifyUrl)}#article`
 }
 
-/** CertREV-scoped node ids — namespaced under the verify URL so they never clash. */
-function reviewId(content: CertContent): string {
-	return `${content.verifyUrl}#certrev-review`
+/** CertREV-scoped node ids — namespaced under the certification, so they never clash. */
+function reviewId(payload: CertPayload): string {
+	return `${payload.content.verifyUrl}#certrev-review`
 }
-function expertId(content: CertContent): string {
-	return content.expert.profileUrl ? `${content.expert.profileUrl}#person` : `${content.verifyUrl}#expert`
+function expertId(payload: CertPayload): string {
+	const { expert, verifyUrl } = payload.content
+	return expert.profileUrl ? `${expert.profileUrl}#person` : `${verifyUrl}#expert`
 }
-function orgId(content: CertContent): string {
-	// One stable CertREV organization node across all pages: derive from the verify
-	// URL origin so it dedupes cleanly when a page hosts multiple certified articles.
-	try {
-		return `${new URL(content.verifyUrl).origin}/#certrev-organization`
-	} catch {
-		return 'https://certrev.com/#certrev-organization'
-	}
+
+/**
+ * The `YYYY-MM-DD` head of an ISO-8601 instant, or null. `lastReviewed`'s schema.org
+ * range is `Date` — not `DateTime` — so the certified instant is truncated to its
+ * calendar day. String-sliced rather than `Date`-parsed on purpose: parsing would
+ * re-render the day in the runtime's timezone and break the determinism invariant
+ * (server and edge could disagree by a day).
+ */
+function isoDate(value: unknown): string | null {
+	if (typeof value !== 'string') return null
+	const match = /^\d{4}-\d{2}-\d{2}/.exec(value)
+	return match ? match[0] : null
 }
 
 /** Build the reviewing-expert Person node (the E-E-A-T signal). */
-function expertPersonNode(payload: CertPayload): JsonLdValue {
+function expertPersonNode(payload: CertPayload, display: ResolvedDisplay): JsonLdValue {
 	const { expert } = payload.content
 	const node: JsonLdValue = {
 		'@type': 'Person',
-		'@id': expertId(payload.content),
+		'@id': expertId(payload),
 		name: expert.displayName,
 	}
 	if (expert.profileUrl) node.url = expert.profileUrl
-	if (expert.photoUrl) node.image = expert.photoUrl
+	// The photo is a brand-toggleable (`free`) field: a face that hides the reviewer photo
+	// must not publish one either. `showExpertPhoto` already folds in the render-def's
+	// `reviewerPhoto` hide-set. Deliberately NOT gated on `badgeStyle` — a compact card
+	// omits the photo as a LAYOUT choice, and the same payload may render full elsewhere on
+	// the page, so keying the graph to it would make the projection slot-dependent.
+	if (display.showExpertPhoto && expert.photoUrl) node.image = expert.photoUrl
 	if (expert.credentials.length > 0) {
 		// hasCredential → EducationalOccupationalCredential per credential; also a flat
-		// honorificSuffix list for consumers that don't read hasCredential.
+		// honorificSuffix list for consumers that don't read hasCredential. `recognizedBy`
+		// (a Credential property whose expected type is Organization) names CertREV as the
+		// body that verified it — the structured-data form of the face's locked
+		// "Credential verified by CertREV" attribution, and what the reviewedby-schema
+		// validator looks for.
 		node.hasCredential = expert.credentials.map((c) => ({
 			'@type': 'EducationalOccupationalCredential',
 			name: c.fullName,
 			alternateName: c.abbreviation,
+			recognizedBy: { '@id': CERTREV_ORGANIZATION_ID },
 		}))
 		node.honorificSuffix = expert.credentials.map((c) => c.abbreviation).join(', ')
 	}
@@ -107,54 +167,83 @@ function expertPersonNode(payload: CertPayload): JsonLdValue {
 }
 
 /** Build the CertREV organization node (publisher of the review credential). */
-function certRevOrgNode(payload: CertPayload): JsonLdValue {
-	let url = 'https://certrev.com'
-	try {
-		url = new URL(payload.content.verifyUrl).origin
-	} catch {
-		/* keep default */
-	}
+function certRevOrgNode(): JsonLdValue {
 	return {
 		'@type': 'Organization',
-		'@id': orgId(payload.content),
+		'@id': CERTREV_ORGANIZATION_ID,
 		name: 'CertREV',
-		url,
+		url: CERTREV_ORGANIZATION_URL,
 	}
 }
 
 /** Build the Review node binding the article to its expert review. */
-function reviewNode(payload: CertPayload): JsonLdValue {
+function reviewNode(payload: CertPayload, opts: ProjectJsonLdOptions, display: ResolvedDisplay): JsonLdValue {
 	const node: JsonLdValue = {
 		'@type': 'Review',
-		'@id': reviewId(payload.content),
-		itemReviewed: { '@id': articleId(payload, {}) },
-		author: { '@id': expertId(payload.content) },
-		publisher: { '@id': orgId(payload.content) },
+		'@id': reviewId(payload),
+		// The SAME opts the Article node is built from. Passing `{}` here (as this did)
+		// pointed `itemReviewed` at the payload's canonical while the Article node carried
+		// the caller's `pageUrl` — an orphaned reference on every page whose URL differs
+		// from `canonicalUrls[0]` (locale prefix, `www`, trailing slash, a syndicated copy).
+		itemReviewed: { '@id': articleId(payload, opts) },
+		author: { '@id': expertId(payload) },
+		publisher: { '@id': CERTREV_ORGANIZATION_ID },
 		datePublished: payload.content.certifiedAt,
 		url: payload.content.verifyUrl,
 	}
-	if (payload.content.memo) node.reviewBody = payload.content.memo
+	// The memo is the one piece of REVIEW PROSE on the face, and it is brand-toggleable.
+	// Publishing `reviewBody` off a hidden memo marks up text no reader can see.
+	if (display.showMemo && payload.content.memo) node.reviewBody = payload.content.memo
 	return node
 }
 
+/**
+ * The host page node — where `lastReviewed` and `reviewedBy` actually belong: BOTH are
+ * schema.org `WebPage` properties (`lastReviewed`: "Date on which the content on this web
+ * page was last reviewed for accuracy and/or completeness", range `Date`; `reviewedBy`:
+ * "People or organizations that have reviewed the content on this web page", range
+ * `Organization`/`Person`). Keyed on the UNMODIFIED canonical URL, the Yoast WebPage
+ * convention, so this merges into the host's existing WebPage node instead of adding a
+ * competing one — and, like the Article node, it carries ONLY the certification-relevant
+ * properties so a merge never overwrites the host's richer page fields.
+ *
+ * Returns null when no page URL is known: `lastReviewed` on a page we cannot name would
+ * either be a dangling node or — worse — an assertion about the CertREV verify page,
+ * which is not the reviewed content.
+ */
+function webPageNode(payload: CertPayload, opts: ProjectJsonLdOptions): JsonLdValue | null {
+	const id = pageBaseUrl(payload, opts)
+	if (!id) return null
+	const lastReviewed = isoDate(payload.content.certifiedAt)
+	return {
+		'@type': 'WebPage',
+		'@id': id,
+		url: id,
+		...(lastReviewed ? { lastReviewed } : {}),
+		reviewedBy: { '@id': expertId(payload) },
+	}
+}
+
 /**
  * The primary Article node — carries the SAME `@id` the host page's article uses so a
  * consumer merges our `reviewedBy` / `dateModified` into the existing node rather than
  * duplicating the primary entity. We deliberately emit ONLY the certification-relevant
- * properties (reviewedBy, dateModified, plus author when distinct) — not headline, body,
- * image, etc. — so we never overwrite the host's richer Article fields on merge.
+ * properties (reviewedBy, dateModified, plus author when distinct AND shown) — not
+ * headline, body, image, etc. — so we never overwrite the host's richer Article fields
+ * on merge.
  */
-function articleNode(payload: CertPayload, opts: ProjectJsonLdOptions): JsonLdValue {
+function articleNode(payload: CertPayload, opts: ProjectJsonLdOptions, display: ResolvedDisplay): JsonLdValue {
 	const { content } = payload
 	const node: JsonLdValue = {
 		'@type': 'Article',
 		'@id': articleId(payload, opts),
-		reviewedBy: { '@id': expertId(content) },
-		review: { '@id': reviewId(content) },
+		reviewedBy: { '@id': expertId(payload) },
+		review: { '@id': reviewId(payload) },
 	}
 	if (content.contentModifiedAt) node.dateModified = content.contentModifiedAt
-	// Author only when present + distinct from the expert (don't double-attribute).
-	if (content.author.name && content.author.name !== content.expert.displayName) {
+	// Author only when the face SHOWS the byline (a `free`, brand-toggleable field) and it
+	// is present + distinct from the expert (don't double-attribute).
+	if (display.showAuthor && content.author.name && content.author.name !== content.expert.displayName) {
 		const author: JsonLdValue = { '@type': 'Person', name: content.author.name }
 		if (content.author.title) author.jobTitle = content.author.title
 		node.author = author
@@ -166,16 +255,23 @@ function articleNode(payload: CertPayload, opts: ProjectJsonLdOptions): JsonLdVa
  * Project the verified certification facts into a schema.org `@graph`.
  *
  * @param payload  The cryptographically-verified payload (the same facts the badge renders).
- * @param opts     Page URL for @id alignment + graph-wrapping control.
+ * @param opts     Page URL for @id alignment, the render-def whose hide-set gates
+ *                 visibility-bound fields, + graph-wrapping control.
  * @returns        A `{ "@context", "@graph" }` object (wrapGraph !== false) OR a bare
  *                 array of nodes (wrapGraph === false) for merge-into-existing-graph callers.
  */
 export function projectCertJsonLd(payload: CertPayload, opts: ProjectJsonLdOptions = {}): JsonLdValue | JsonLdValue[] {
+	// ONE resolution of the visibility flags, shared by every node — the same resolver
+	// (and therefore the same answer) the rendered card uses. No accent override: theming
+	// is meaningless to structured data.
+	const display = resolveDisplay(payload.content.display, undefined, opts.renderDef)
+	const page = webPageNode(payload, opts)
 	const nodes: JsonLdValue[] = [
-		articleNode(payload, opts),
-		reviewNode(payload),
-		expertPersonNode(payload),
-		certRevOrgNode(payload),
+		...(page ? [page] : []),
+		articleNode(payload, opts, display),
+		reviewNode(payload, opts, display),
+		expertPersonNode(payload, display),
+		certRevOrgNode(),
 	]
 	if (opts.wrapGraph === false) return nodes
 	return { '@context': SCHEMA_CONTEXT, '@graph': nodes }

package/src/modal/avatar-resize.ts

@@ -1,15 +1,15 @@
-// ⚠ VENDORED, BYTE-FAITHFUL relocation of portal `src/lib/cert-delivery/avatar-resize.ts`
-// (POR-10721 W2). The body is byte-identical to the source the deployed `certrev-cert.js`
-// was bundled from — keep it that way. Configurable asset origins for other headless
-// brands are a deliberate post-relocation follow-up (byte-parity takes precedence now).
+// ⚠ VENDORED, BYTE-FAITHFUL relocation of the portal's `avatar-resize` module. The body is
+// byte-identical to the source the deployed `certrev-cert.js` was bundled from — keep it that
+// way. Configurable asset origins for other headless brands are a deliberate post-relocation
+// follow-up (byte-parity takes precedence now).
 /**
- * Avatar right-sizing (POR-10470) — the SINGLE source of truth for how a cert contributor/expert
+ * Avatar right-sizing — the SINGLE source of truth for how a cert contributor/expert
  * headshot URL is rewritten to a display-sized derivative. Referenced by the cert MODAL (TS,
  * cert-modal-view.ts), mirrored by the Liquid snippet (certrev-avatar-url.liquid), and by the
- * Cloudflare size-allowlist WAF rule (infra/terraform/cloudflare). Keep the three in lockstep — the
+ * Cloudflare size-allowlist WAF rule. Keep the three in lockstep — the
  * `avatar-resize.test.ts` `SIZES`/param assertions are the tripwire.
  *
- * Architecture (Fable-reviewed): the signed cert envelope carries ONE canonical full-res photoUrl
+ * Architecture: the signed cert envelope carries ONE canonical full-res photoUrl
  * (also the JSON-LD Person.image — never shrunk). Display sizing is a PRESENTATION concern, applied
  * here via Cloudflare Image Resizing on the same zone as assets.certrev.com:
  *   https://assets.certrev.com/cdn-cgi/image/width=W,height=W,fit=cover,format=auto/<path>
@@ -17,20 +17,20 @@
  * allowlist is needed; format=auto serves webp/avif; the transform is cached + billed per-unique.
  *
  * ENABLEMENT GATE (`AVATAR_RESIZE_ENABLED`): OFF until Cloudflare Image Resizing is enabled on the
- * certrev.com zone AND a real photo is verified to resize (POR-10470 gate). While OFF, avatars use
+ * certrev.com zone AND a real photo is verified to resize. While OFF, avatars use
  * the raw canonical URL — byte-identical to today's behavior — so the extension can deploy for the
  * font de-block with ZERO avatar regression (a cdn-cgi/image URL 404s → initials fallback if the
  * feature isn't live). Going live is a one-line flip here + in certrev-avatar-url.liquid, then the
- * raw branch is removed (flag-debt: tracked as the POR-10470 avatar go-live follow-up).
+ * raw branch is removed (flag-debt: the avatar go-live follow-up).
  */
 
 /**
- * Enablement gate — LIVE as of 2026-07-20 (POR-10656). Cloudflare Image Resizing (Transformations)
- * is enabled on the certrev.com zone (`image_resizing = on`), and the size-allowlist WAF rule
- * (ruleset 7c9df62e88cb4713b18f12853651af08) is verified enforcing on `/cdn-cgi/image/` paths — a real
- * photo resizes (`width=84` → 200 image/jpeg) while a disallowed size (`width=999`) is 403-blocked.
+ * Enablement gate — LIVE as of 2026-07-20. Cloudflare Image Resizing (Transformations)
+ * is enabled on the certrev.com zone (`image_resizing = on`), and the size-allowlist WAF rule is
+ * verified enforcing on `/cdn-cgi/image/` paths — a real photo resizes (`width=84` → 200
+ * image/jpeg) while a disallowed size (`width=999`) is 403-blocked.
  * Kept as a one-line kill-switch: flip back to `false` + redeploy to instantly revert to raw URLs if
- * resizing ever misbehaves (removing the raw branch entirely is the flag-debt follow-up, POR-10680).
+ * resizing ever misbehaves (removing the raw branch entirely is the flag-debt follow-up).
  */
 export const AVATAR_RESIZE_ENABLED = true;
 

package/src/modal/cert-modal-view.ts

@@ -1,5 +1,5 @@
 /**
- * Pure envelope → modal-HTML mapping for `<certrev-cert-modal>` (POR-10102).
+ * Pure envelope → modal-HTML mapping for `<certrev-cert-modal>`.
  *
  * DOM-free and side-effect-free so it unit-tests without a browser: given the
  * signed envelope's `payload.content`, it returns the inner HTML of the certificate
@@ -11,19 +11,23 @@
  *  - Every dynamic value is `escapeHtml`'d (the envelope is signed, but a reviewer
  *    name / memo is still attacker-adjacent content).
  *  - Only `http(s)` hrefs render (mirrors the Liquid `certrev-safe-url` guard).
- *  - Verified-only fields (POR-10091): the bio binds the envelope's verified
+ *  - Verified-only fields: the bio binds the envelope's verified
  *    `background`/`bio`; this module never reaches for a raw column.
  *  - Graceful degradation: a missing article title drops the "Certifies the article"
  *    block; a missing display cert id drops that meta column; no credentials → no
  *    chips / no creds line; no bio → no bio paragraph. Nothing renders an empty gap.
- *  - WS4a (display eviction) accept-on-read: an ABSENT `display` block resolves to the
+ *  - Display-eviction accept-on-read: an ABSENT `display` block resolves to the
  *    preset default (show-all) — every read below is `display?.x !== false` / `=== false`,
  *    so `undefined` never suppresses a field. The modal is the LOCKED navy trust chrome and
  *    is deliberately NOT themeable by a brand render-def; it reads visibility off the signed
  *    envelope only, so no render-def wiring belongs here.
+ *  - Type tolerance, not just shape tolerance: `content` is a `JSON.parse(...) as` cast off an
+ *    envelope whose SIGNATURE was checked and whose SHAPE never was, so every read below goes
+ *    through `asText` before it touches a string method. `(x || '').trim()` looks defensive but
+ *    throws on a number, and a throw here is the dialog the reader just clicked failing to open.
  */
 
-import { escapeHtml } from './escape.js'
+import { asText, escapeHtml } from './escape.js'
 import { resizeAvatarUrl } from './avatar-resize.js'
 import { CERT_SCOPE_LINE, formatCertDisplayDate } from './display-strings.js'
 import { checkIcon, chevronMark, verifiedStamp } from './certrev-cert-modal.styles.js'
@@ -41,7 +45,7 @@ export interface CertModalExpert {
 	photoUrl?: string | null
 	bio?: string | null
 	background?: string | null
-	/** POR-10496: the pre-composed material-connection label ('Compensated expert') or null/absent for
+	/** The pre-composed material-connection label ('Compensated expert') or null/absent for
 	 *  a pro-bono reviewer. Present → the disclosure footer renders the label; null/absent → label omitted. */
 	compensationCue?: string | null
 }
@@ -56,12 +60,29 @@ export interface CertModalContent {
 	display?: { showExpertPhoto?: boolean | null; showBio?: boolean | null } | null
 }
 
+/**
+ * The `rel` every CertREV anchor in this module carries.
+ *
+ * `../components/rel.ts` (`CERTREV_LINK_REL`) is the SOURCE OF TRUTH for the qualification
+ * tokens and the policy reasoning behind them — read it there. The value is duplicated rather
+ * than imported because `src/modal/` is bundled standalone into the dependency-free
+ * `certrev-cert.js` IIFE (`build:modal-bundle`) and imports NOTHING from `src/components/`;
+ * crossing that boundary for a string constant would pull the SSR module graph into a
+ * storefront asset. This copy adds `noreferrer` on top of the shared tokens: both anchors here
+ * are `target="_blank"`, where it still earns its place.
+ *
+ * Keep in lockstep with `CERTREV_LINK_REL` — `nofollow` + `sponsored` are the qualification the
+ * link-spam policy names, and dropping either from one copy silently un-qualifies half the
+ * package's links.
+ */
+export const CERTREV_MODAL_LINK_REL = 'nofollow sponsored noopener noreferrer'
+
 const HONORIFIC_RE = /^(dr|prof|professor|mr|mrs|ms|mx|rev|sir|dame)\.?\s+/i
 
 /** The bare given+family name: strip the leading honorific AND the trailing post-nominal
  *  (`, MD`), so "Dr. Erik Schraga, MD" → "Erik Schraga". */
 function coreName(displayName: string): string {
-	const withoutHonorific = displayName.replace(HONORIFIC_RE, '').trim()
+	const withoutHonorific = asText(displayName).replace(HONORIFIC_RE, '').trim()
 	const comma = withoutHonorific.indexOf(',')
 	return (comma === -1 ? withoutHonorific : withoutHonorific.slice(0, comma)).trim()
 }
@@ -82,24 +103,28 @@ export function signatureName(displayName: string): string {
 
 /** `https://certrev.com/verify/x` → `certrev.com/verify/x` (footer URL line). */
 export function stripProtocol(url: string): string {
-	return url.replace(/^https?:\/\//i, '').replace(/\/$/, '')
+	return asText(url).replace(/^https?:\/\//i, '').replace(/\/$/, '')
 }
 
 /** Return the url only if it is an absolute http(s) URL, else `#` (safe-url guard). */
 export function safeHref(url: string | null | undefined): string {
-	if (!url) return '#'
-	return /^https?:\/\//i.test(url.trim()) ? url.trim() : '#'
+	const href = asText(url).trim()
+	if (!href) return '#'
+	return /^https?:\/\//i.test(href) ? href : '#'
 }
 
 /** A single credential's display label (cardLabel ?? fullName ?? abbreviation). */
-function credLabel(c: CertModalCredential): string {
-	return (c.cardLabel || c.fullName || c.abbreviation || '').trim()
+function credLabel(c: CertModalCredential | null | undefined): string {
+	return (asText(c?.cardLabel) || asText(c?.fullName) || asText(c?.abbreviation)).trim()
 }
 
 /** The verified credential labels, in order, de-duped + non-empty. */
 function credLabels(expert: CertModalExpert | null | undefined): string[] {
 	const out: string[] = []
-	for (const c of expert?.credentials ?? []) {
+	// `Array.isArray`, not `?? []`: a `credentials` that parsed as an object is not iterable, and
+	// `for…of` over one throws before any of the per-entry guards below get a chance to run.
+	const credentials = Array.isArray(expert?.credentials) ? expert.credentials : []
+	for (const c of credentials) {
 		const label = credLabel(c)
 		if (label && !out.includes(label)) out.push(label)
 	}
@@ -109,7 +134,7 @@ function credLabels(expert: CertModalExpert | null | undefined): string[] {
 /** The reviewer bio — verified background preferred, then verified bio. */
 function bioText(expert: CertModalExpert | null | undefined, display: CertModalContent['display']): string {
 	if (display?.showBio === false) return ''
-	return (expert?.background || expert?.bio || '').trim()
+	return (asText(expert?.background) || asText(expert?.bio)).trim()
 }
 
 /** An avatar cell — the cert-frozen photo (when shown) or the initials chip. */
@@ -119,9 +144,9 @@ function avatarHtml(
 	sizeClass: string,
 	showPhoto: boolean,
 ): string {
-	const photo = (expert?.photoUrl || '').trim()
+	const photo = asText(expert?.photoUrl).trim()
 	if (showPhoto && /^https?:\/\//i.test(photo)) {
-		// Display px from the size class; request the @2x derivative for retina crispness (POR-10470).
+		// Display px from the size class; request the @2x derivative for retina crispness.
 		// resizeAvatarUrl is host-guarded + enablement-gated: until Cloudflare Image Resizing is live it
 		// returns the raw canonical URL, so the modal never 404s an unresized host.
 		const displayPx = sizeClass.includes('--64') ? 64 : 56
@@ -142,14 +167,14 @@ function certifiedChip(cls: string): string {
 }
 
 /**
- * The FTC disclosure footer (POR-10496), rendered on both dialogs. The material-connection cue
+ * The FTC disclosure footer, rendered on both dialogs. The material-connection cue
  * (`expert.compensationCue`, a FINISHED string off the signed envelope) leads ONLY when the reviewer
  * was compensated; a pro-bono reviewer (null/absent cue) drops the label but keeps the scope line —
  * which makes no compensation claim, so it is true for volunteers too and renders unconditionally.
  * The scope line is the verbatim FTC copy (`CERT_SCOPE_LINE`), never re-assembled here.
  */
 function disclosureFooter(expert: CertModalExpert | null | undefined): string {
-	const cue = (expert?.compensationCue || '').trim()
+	const cue = asText(expert?.compensationCue).trim()
 	const cueHtml = cue ? `<span class="crm-disclosure__cue">${escapeHtml(cue)}</span> ` : ''
 	return `<div class="crm-disclosure">${cueHtml}${escapeHtml(CERT_SCOPE_LINE)}</div>`
 }
@@ -161,15 +186,15 @@ function disclosureFooter(expert: CertModalExpert | null | undefined): string {
  */
 export function renderCertDialogInner(content: CertModalContent): string | null {
 	const expert = content.expert ?? null
-	const name = (expert?.displayName || '').trim()
+	const name = asText(expert?.displayName).trim()
 	if (!name) return null
 
 	const showPhoto = content.display?.showExpertPhoto !== false
 	const creds = credLabels(expert).join(' · ')
 	const issued = formatCertDisplayDate(content.certifiedAt) ?? ''
-	const certId = (content.displayCertId || '').trim()
-	const title = (content.articleTitle || '').trim()
-	const verifyUrl = (content.verifyUrl || '').trim()
+	const certId = asText(content.displayCertId).trim()
+	const title = asText(content.articleTitle).trim()
+	const verifyUrl = asText(content.verifyUrl).trim()
 	const sig = signatureName(name)
 
 	const certifiesBlock = title
@@ -182,17 +207,17 @@ export function renderCertDialogInner(content: CertModalContent): string | null
 
 	const urlLine = verifyUrl ? `<div class="crm-sig__url">${escapeHtml(stripProtocol(verifyUrl))}</div>` : ''
 
-	return `${CLOSE_BUTTON}${headHtml('Certificate of Expert Review')}<div class="crm-body--cert"><div class="crm-expert-row">${avatarHtml(expert, name, 'crm-avatar--56', showPhoto)}<div class="crm-expert-row__info"><div class="crm-expert-row__eyebrow">Reviewing Expert</div><div class="crm-expert-row__name">${escapeHtml(name)}</div>${creds ? `<div class="crm-expert-row__creds">${escapeHtml(creds)}</div>` : ''}</div></div>${certifiesBlock}<div class="crm-meta"><div class="crm-meta__col"><div class="crm-meta__label">Issued</div><div class="crm-meta__value">${escapeHtml(issued)}</div></div>${certIdCol}<div class="crm-meta__col"><div class="crm-meta__label">Status</div><div class="crm-meta__status">${certifiedChip('crm-chip')}</div></div></div><div class="crm-sig"><div><div class="crm-sig__name">${escapeHtml(sig)}</div><div class="crm-sig__rule"></div>${urlLine}</div>${verifiedStamp('cert')}</div>${disclosureFooter(expert)}<div class="crm-actions"><a class="crm-cta" href="${escapeHtml(safeHref(verifyUrl))}" target="_blank" rel="noopener noreferrer">View full certificate</a><button type="button" class="crm-ghost" data-certrev-modal-close>Close</button></div></div>`
+	return `${CLOSE_BUTTON}${headHtml('Certificate of Expert Review')}<div class="crm-body--cert"><div class="crm-expert-row">${avatarHtml(expert, name, 'crm-avatar--56', showPhoto)}<div class="crm-expert-row__info"><div class="crm-expert-row__eyebrow">Reviewing Expert</div><div class="crm-expert-row__name">${escapeHtml(name)}</div>${creds ? `<div class="crm-expert-row__creds">${escapeHtml(creds)}</div>` : ''}</div></div>${certifiesBlock}<div class="crm-meta"><div class="crm-meta__col"><div class="crm-meta__label">Issued</div><div class="crm-meta__value">${escapeHtml(issued)}</div></div>${certIdCol}<div class="crm-meta__col"><div class="crm-meta__label">Status</div><div class="crm-meta__status">${certifiedChip('crm-chip')}</div></div></div><div class="crm-sig"><div><div class="crm-sig__name">${escapeHtml(sig)}</div><div class="crm-sig__rule"></div>${urlLine}</div>${verifiedStamp('cert')}</div>${disclosureFooter(expert)}<div class="crm-actions"><a class="crm-cta" href="${escapeHtml(safeHref(verifyUrl))}" target="_blank" rel="${CERTREV_MODAL_LINK_REL}">View full certificate</a><button type="button" class="crm-ghost" data-certrev-modal-close>Close</button></div></div>`
 }
 
 /**
- * The reviewer/profile modal (4b) inner HTML. Returns `null` when there is no
- * reviewer name (fail-closed). The affiliation subtitle is intentionally omitted
- * (no verified data source — POR-10102 decision).
+ * The reviewer/profile modal inner HTML. Returns `null` when there is no
+ * reviewer name (fail-closed). The affiliation subtitle is intentionally omitted:
+ * there is no verified data source for it.
  */
 export function renderExpertDialogInner(content: CertModalContent): string | null {
 	const expert = content.expert ?? null
-	const name = (expert?.displayName || '').trim()
+	const name = asText(expert?.displayName).trim()
 	if (!name) return null
 
 	const showPhoto = content.display?.showExpertPhoto !== false
@@ -206,5 +231,5 @@ export function renderExpertDialogInner(content: CertModalContent): string | nul
 	const bioHtml = bio ? `<p class="crm-bio">${escapeHtml(bio)}</p>` : ''
 	const trustText = date ? `Independently reviewed · Certified ${escapeHtml(date)}` : 'Independently reviewed'
 
-	return `${CLOSE_BUTTON}${headHtml('Verified reviewer')}<div class="crm-body--expert"><div class="crm-id">${avatarHtml(expert, name, 'crm-avatar--64', showPhoto)}<div class="crm-id__info"><div class="crm-id__name">${escapeHtml(name)}</div></div></div>${chipsHtml}${bioHtml}<div class="crm-trust">${certifiedChip('crm-trust__chip')}<span class="crm-trust__text">${trustText}</span></div>${disclosureFooter(expert)}<div class="crm-actions"><a class="crm-cta" href="${escapeHtml(safeHref(expert?.profileUrl))}" target="_blank" rel="noopener noreferrer">View full profile on CertREV</a><button type="button" class="crm-ghost" data-certrev-modal-close>Close</button></div></div>`
+	return `${CLOSE_BUTTON}${headHtml('Verified reviewer')}<div class="crm-body--expert"><div class="crm-id">${avatarHtml(expert, name, 'crm-avatar--64', showPhoto)}<div class="crm-id__info"><div class="crm-id__name">${escapeHtml(name)}</div></div></div>${chipsHtml}${bioHtml}<div class="crm-trust">${certifiedChip('crm-trust__chip')}<span class="crm-trust__text">${trustText}</span></div>${disclosureFooter(expert)}<div class="crm-actions"><a class="crm-cta" href="${escapeHtml(safeHref(expert?.profileUrl))}" target="_blank" rel="${CERTREV_MODAL_LINK_REL}">View full profile on CertREV</a><button type="button" class="crm-ghost" data-certrev-modal-close>Close</button></div></div>`
 }

package/src/modal/certrev-cert-modal.styles.ts

@@ -1,8 +1,7 @@
 /**
- * Scoped styles + inline SVGs for the `<certrev-cert-modal>` Shadow-DOM element
- * (POR-10102). The single source of truth for the certificate (3a) + reviewer (4b)
- * modal look, ported byte-faithfully from the Claude Design reference
- * (`docs/claude/design/certificate-modals/`, footer variant 3a + reviewer 4b).
+ * Scoped styles + inline SVGs for the `<certrev-cert-modal>` Shadow-DOM element.
+ * The single source of truth for the certificate + reviewer modal look, ported
+ * byte-faithfully from the approved design reference.
  *
  * Because the element renders inside a shadow root, this CSS is fully scoped: the
  * brand storefront theme cannot bleed in, and these rules never leak out — so the
@@ -16,7 +15,8 @@
 import { LOGO_PATHS } from './logo-paths.js'
 
 /** The four-chevron CertREV mark (viewBox 0 0 375 375), tinted via the passed fill. Path data is
- * single-sourced from src/lib/design-guide/logo.ts (the SOT the codegen mirrors into every twin). */
+ * single-sourced from the portal design-guide's logo module (the SOT the codegen mirrors into
+ * every twin). */
 export function chevronMark(size: number, fill: string): string {
 	const paths = LOGO_PATHS.map((d) => `<path fill="${fill}" d="${d}"/>`).join('')
 	return `<svg width="${size}" height="${size}" viewBox="0 0 375 375" aria-hidden="true" style="display:block;flex-shrink:0">${paths}</svg>`
@@ -52,7 +52,7 @@ export const CERT_MODAL_FONT_FAMILIES = [
 	'Allura',
 ] as const
 
-// The modal's fonts are self-hosted (POR-10657): the standalone loader (certrev-cert-modal.ts)
+// The modal's fonts are self-hosted: the standalone loader (certrev-cert-modal.ts)
 // injects the shared CERT_FONT_FACE_CSS @font-face block (R2 URLs) instead of a render-blocking
 // Google Fonts stylesheet. In the theme-app-extension the host page already declares these via
 // certrev-cert.css, so `data-fonts="host"` suppresses the injection entirely.
@@ -96,7 +96,7 @@ export const CERT_MODAL_CSS = `
 	background: var(--cr-white);
 	color: var(--cr-navy);
 	font-family: var(--cr-sans);
-	/* fixed, NOT relative (POR-10473): a :modal dialog (showModal) renders in the TOP LAYER; a
+	/* fixed, NOT relative: a :modal dialog (showModal) renders in the TOP LAYER; a
 	 * relative dialog anchors to its scrolled document position, so once the page is scrolled the
 	 * panel renders off-screen while the ::backdrop still covers the viewport (measured top -1972 at
 	 * scrollY 2537). fixed is viewport-anchored (the UA inset:0 + margin:auto centers it) and still
@@ -462,7 +462,7 @@ export const CERT_MODAL_CSS = `
 	color: var(--cr-navy-50);
 }
 
-/* FTC disclosure footer (POR-10496) — material-connection cue (compensated only) + scope line
+/* FTC disclosure footer — material-connection cue (compensated only) + scope line
  * (always). Rendered on both the certificate + reviewer dialogs, immediately above the actions. */
 .crm-disclosure {
 	margin-top: 14px;