@certrev/cert-block 0.3.0 → 0.5.1

package/src/modal/ftc-guard.ts

@@ -0,0 +1,119 @@
+/**
+ * FTC disclosure tamper guard for the NATIVE Shopify cert render (iframe→native parity).
+ *
+ * In the cross-origin iframe model the expert-memo embed inlined `ftcTamperGuardScript()`
+ * (src/lib/embed/ftc-disclosure.ts): a kill switch that blanks the memo if the verbatim FTC
+ * material-connection disclosure is stripped, hidden, or altered — making the MSA §3
+ * anti-stripping covenant TECHNICALLY enforced, not just contractual. The native memo renders
+ * in the host theme's DOM (no sandbox), so without this it would lose that runtime enforcement.
+ * This module restores it: on load + on later DOM mutation it verifies the in-DOM
+ * `[data-ftc-line]` is present, carries the EXACT verbatim text, and is actually visible; if not,
+ * it neutralizes the memo with a neutral notice so the memo NEVER renders without its disclosure.
+ *
+ * Native-specific semantics (differ from the iframe, which only existed when a memo did):
+ *   - Enforcement is keyed on the MEMO element (`.certrev-memo`). A certified article with NO
+ *     memo legitimately has no `.certrev-memo` and no disclosure — the guard does NOT fire
+ *     (no false positive on the no-memo path).
+ *   - On tamper it neutralizes ONLY the memo (never `document.body` — we're in the host page).
+ *   - The contributors card is governed by the badge re-verify (`revalidate.ts`), not this guard;
+ *     the card carries only the one-word "Compensated" cue, never the guarded disclosure.
+ *
+ * Pure DOM, no crypto, no network. The expected text is the single source of truth
+ * `FTC_DISCLOSURE_LINE` (imported, not copied — so a reword can never desync this guard).
+ */
+
+import { FTC_DISCLOSURE_LINE } from './ftc-disclosure.js'
+
+export const FTC_LINE_SELECTOR = '[data-ftc-line]'
+export const MEMO_SELECTOR = '.certrev-memo'
+export const MEMO_WRAP_SELECTOR = '.certrev-memo-wrap'
+/** Marker on the neutral notice node that replaces a tampered memo (testable / idempotent). */
+export const FTC_NEUTRALIZED_ATTR = 'data-certrev-ftc-neutralized'
+
+/** Documents already guarded, so a double script-load can't double-bind. */
+const guardedDocs = new WeakSet<Document>()
+
+/** Visible = not display:none / visibility:hidden / opacity:0 and a non-zero box. */
+function isVisible(el: Element): boolean {
+	const win = el.ownerDocument.defaultView
+	// No view (detached / SSR): we can't measure, so don't treat as hidden — the text/presence
+	// checks still apply; only the layout-based hide vector is skipped.
+	if (!win) return true
+	const s = win.getComputedStyle(el)
+	if (s.display === 'none' || s.visibility === 'hidden' || Number.parseFloat(s.opacity || '1') === 0) return false
+	const r = el.getBoundingClientRect()
+	return r.width > 0 && r.height > 0
+}
+
+/** True when a memo's disclosure line is present, exactly verbatim, and visible. */
+export function isDisclosureIntact(memo: Element): boolean {
+	const line = memo.querySelector(FTC_LINE_SELECTOR)
+	if (!line) return false
+	if ((line.textContent || '').trim() !== FTC_DISCLOSURE_LINE) return false
+	return isVisible(line)
+}
+
+/**
+ * Replace a tampered memo with a neutral, self-contained notice — no reviewer attribution, no
+ * seal — so the surface can never read as an endorsement without its required disclosure.
+ */
+export function neutralizeMemo(memo: Element): void {
+	const doc = memo.ownerDocument
+	const notice = doc.createElement('div')
+	notice.setAttribute(FTC_NEUTRALIZED_ATTR, '')
+	notice.style.cssText =
+		'font-family:system-ui,-apple-system,sans-serif;font-size:12px;color:#555;padding:12px;line-height:1.4'
+	notice.innerHTML =
+		'This CertREV verification cannot be displayed because its required disclosure was not shown. ' +
+		'<a href="https://certrev.com" style="color:#555" target="_blank" rel="noopener noreferrer">Learn more</a>.'
+	memo.replaceWith(notice)
+}
+
+/**
+ * Enforce the disclosure across every memo in the doc: neutralize any whose disclosure isn't
+ * intact. A doc with no `.certrev-memo` (no-memo article) is a no-op. Returns true if all memos
+ * present were intact (or none existed).
+ */
+export function enforceFtcDisclosure(doc: Document): boolean {
+	let allIntact = true
+	for (const memo of Array.from(doc.querySelectorAll(MEMO_SELECTOR))) {
+		if (!isDisclosureIntact(memo)) {
+			allIntact = false
+			neutralizeMemo(memo)
+		}
+	}
+	return allIntact
+}
+
+/**
+ * Install the guard once per document: enforce now (on DOM ready) and re-enforce on later DOM
+ * mutations within the memo wrap(s) — so a host script that strips / hides / edits the disclosure
+ * after load still trips the kill switch. Scoping the observer to the small `.certrev-memo-wrap`
+ * subtree(s) keeps it cheap on a busy storefront page (cf. the iframe, which observed its whole
+ * — tiny — body). Idempotent.
+ */
+export function installFtcGuard(doc: Document): void {
+	if (guardedDocs.has(doc)) return
+	guardedDocs.add(doc)
+
+	const run = (): void => {
+		enforceFtcDisclosure(doc)
+	}
+
+	const start = (): void => {
+		run()
+		const MO = doc.defaultView?.MutationObserver
+		if (!MO) return
+		// Observe the stable memo wrap(s) — placement.js relocates the wrap as a node, so the
+		// observer tracks it wherever it moves. Fall back to <body> only if no wrap exists.
+		const wraps = Array.from(doc.querySelectorAll(MEMO_WRAP_SELECTOR))
+		const scope = wraps.length ? wraps : doc.body ? [doc.body] : []
+		for (const node of scope) {
+			const mo = new MO(run)
+			mo.observe(node, { childList: true, subtree: true, characterData: true, attributes: true })
+		}
+	}
+
+	if (doc.readyState === 'loading') doc.addEventListener('DOMContentLoaded', start, { once: true })
+	else start()
+}

package/src/modal/index.ts

@@ -0,0 +1,34 @@
+/**
+ * `@certrev/cert-block/modal` — the browser cert MODAL + badge-revalidation Web Component
+ * (POR-10721 W2). A BYTE-FAITHFUL relocation of portal `src/lib/cert-delivery/wc/`; the IIFE
+ * built from `certrev-cert.entry.ts` (`build:modal-bundle`) is structurally byte-identical to the
+ * Shopify-deployed `certrev-cert.js`, so a headless brand can drop the SAME verified modal onto its
+ * storefront (`<script src=".../dist/modal/certrev-cert.js">`) instead of vendoring a copy.
+ *
+ * Importing this module as ESM has the SAME side effect as loading the IIFE: it registers the
+ * `<certrev-cert-modal>` element and (in a browser) runs placement + interactions + FTC guard +
+ * badge revalidation. Bundler users: `import '@certrev/cert-block/modal'`.
+ */
+
+// Side-effect: register the element + (in a browser) kick off the DOM passes.
+import "./certrev-cert.entry.js";
+
+// The published issuer PUBLIC key — re-exported so a portal-side test can assert the package's
+// bundled key matches portal's signer (`CERT_ENVELOPE_*`) after portal re-points at this package
+// (the cross-repo "published key sync" guard that used to live in wc/revalidate.test.ts).
+export {
+	CERT_ISSUER_KID,
+	CERT_ISSUER_PUBLIC_KEY_PEM,
+} from "./certrev-cert.entry.js";
+
+// Composable entry points for advanced consumers (the IIFE wires these itself).
+export { CERT_MODAL_TAG } from "./certrev-cert-modal.js";
+export { installFtcGuard } from "./ftc-guard.js";
+export { initCertInteractionsOnReady } from "./interactions.js";
+export { initCertPlacement } from "./placement.js";
+export {
+	initBadgeRevalidation,
+	type RevalidateDeps,
+	revalidateBadge,
+} from "./revalidate.js";
+export { createDeliveryVerifier } from "./verify-client.js";

package/src/modal/interactions.test.ts

@@ -0,0 +1,250 @@
+// @vitest-environment jsdom
+/**
+ * Unit tests for the cert-card interactions layer — accordion contributor bios (POR-9827 chevron
+ * model) + the in-page certificate/profile modals. Pure DOM, delegated handlers.
+ */
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+	initCertInteractions,
+	modalTargetKind,
+	openCertModal,
+	openModal,
+	swapBrokenAvatar,
+	sweepBrokenAvatars,
+	toggleAccordion,
+} from "./interactions.js";
+
+beforeEach(() => {
+	document.head.innerHTML = "";
+	document.body.innerHTML = "";
+	// Fresh document flag each test isn't possible (same global doc), so the install guard is
+	// exercised explicitly in its own test; other tests call initCertInteractions once.
+});
+
+/** A contributors card with an accordion reviewer row (name/credentials split + hidden acc-bio)
+ *  and the footer "Compensated expert" modal trigger — the POR-9827 chevron-model markup. */
+function mountCard(): {
+	card: HTMLElement;
+	row: HTMLElement;
+	bio: HTMLElement;
+} {
+	const card = document.createElement("section");
+	card.className = "certrev-badge certrev-card";
+	card.innerHTML = `
+		<div class="card-body">
+			<div class="contributors">
+				<div class="contributor clickable" data-certrev-acc role="button" tabindex="0" aria-expanded="false">
+					<div class="person-row"><div class="info">
+						<div class="name">Jane Doe <svg class="name-caret"></svg></div>
+						<div class="credentials">RDN, PhD</div>
+						<div class="label expert">Reviewed by</div>
+						<div class="acc-bio">Twenty years in clinical nutrition.</div>
+					</div></div>
+				</div>
+			</div>
+			<div class="card-footer"><span class="compensated-cue">Compensated <a class="cert-link" href="https://certrev.com/experts/jane" data-certrev-modal-open="expert">expert</a></span></div>
+		</div>`;
+	document.body.appendChild(card);
+	return {
+		card,
+		row: card.querySelector("[data-certrev-acc]")!,
+		bio: card.querySelector(".acc-bio")!,
+	};
+}
+
+type StubModal = HTMLElement & { open: ReturnType<typeof vi.fn> };
+
+/** A stand-in `<certrev-cert-modal>` with a controllable `open()` — the interactions layer only
+ *  routes to the element's `.open(kind)`; the element itself owns rendering (tested separately). */
+function mountModalElement(returns = true): StubModal {
+	const el = document.createElement("certrev-cert-modal") as StubModal;
+	el.open = vi.fn(() => returns);
+	document.body.appendChild(el);
+	return el;
+}
+
+describe("toggleAccordion (pure)", () => {
+	it("toggles the row open and mirrors the state on aria-expanded", () => {
+		const { row } = mountCard();
+		toggleAccordion(row);
+		expect(row.classList.contains("open")).toBe(true);
+		expect(row.getAttribute("aria-expanded")).toBe("true");
+		toggleAccordion(row);
+		expect(row.classList.contains("open")).toBe(false);
+		expect(row.getAttribute("aria-expanded")).toBe("false");
+	});
+});
+
+describe("openCertModal", () => {
+	it('routes to the <certrev-cert-modal> element open("cert")', () => {
+		const el = mountModalElement(true);
+		expect(openCertModal(document)).toBe(true);
+		expect(el.open).toHaveBeenCalledWith("cert");
+	});
+
+	it("returns false (caller falls back to the link) when no modal element exists", () => {
+		expect(openCertModal(document)).toBe(false);
+	});
+
+	it("returns whatever the element.open returns — false lets the link href fall back", () => {
+		mountModalElement(false);
+		expect(openCertModal(document)).toBe(false);
+	});
+});
+
+describe("modal routing (POR-10102 — unified element)", () => {
+	it('modalTargetKind routes "expert" to the reviewer and everything else to the certificate', () => {
+		expect(modalTargetKind("expert")).toBe("expert");
+		expect(modalTargetKind("cert")).toBe("cert");
+		expect(modalTargetKind("")).toBe("cert");
+		expect(modalTargetKind(null)).toBe("cert");
+	});
+
+	it("openModal opens the reviewer dialog via the element (and returns false when it is absent)", () => {
+		expect(openModal(document, "expert")).toBe(false);
+		const el = mountModalElement(true);
+		expect(openModal(document, "expert")).toBe(true);
+		expect(el.open).toHaveBeenCalledWith("expert");
+	});
+
+	it('the "Compensated expert" cue opens the reviewer modal and prevents navigation', () => {
+		const { card, row } = mountCard();
+		const el = mountModalElement(true);
+		initCertInteractions(document);
+		const link = card.querySelector(
+			'[data-certrev-modal-open="expert"]',
+		) as HTMLElement;
+		const evt = new MouseEvent("click", { bubbles: true, cancelable: true });
+		link.dispatchEvent(evt);
+		expect(el.open).toHaveBeenCalledWith("expert");
+		expect(evt.defaultPrevented).toBe(true);
+		// The modal open is NOT an accordion toggle.
+		expect(row.classList.contains("open")).toBe(false);
+	});
+});
+
+describe("broken avatar → initials fallback", () => {
+	it("swapBrokenAvatar replaces a broken img with the matching initials span", () => {
+		const img = document.createElement("img");
+		img.className = "avatar";
+		img.setAttribute("data-certrev-initials", "JS");
+		img.src = "https://broken.example/x.jfif";
+		document.body.appendChild(img);
+		swapBrokenAvatar(img);
+		const span = document.body.querySelector("span.avatar.avatar--initials");
+		expect(span).not.toBeNull();
+		expect(span!.textContent).toBe("JS");
+		expect(span!.getAttribute("aria-hidden")).toBe("true");
+		expect(document.body.querySelector("img")).toBeNull();
+	});
+
+	it("uses the memo base class when that is what the img carries", () => {
+		const memoImg = document.createElement("img");
+		memoImg.className = "certrev-memo__avatar";
+		memoImg.setAttribute("data-certrev-initials", "CY");
+		document.body.appendChild(memoImg);
+		swapBrokenAvatar(memoImg);
+		expect(
+			document.body.querySelector(
+				"span.certrev-memo__avatar.certrev-memo__avatar--initials",
+			)?.textContent,
+		).toBe("CY");
+	});
+
+	it("does nothing for an img without the initials attribute", () => {
+		const img = document.createElement("img");
+		img.className = "avatar";
+		document.body.appendChild(img);
+		swapBrokenAvatar(img);
+		expect(document.body.querySelector("img")).not.toBeNull();
+	});
+
+	it("sweepBrokenAvatars swaps an avatar that already failed before init (no error event re-fires)", () => {
+		const img = document.createElement("img");
+		img.className = "avatar";
+		img.setAttribute("data-certrev-initials", "ZZ");
+		// Simulate an image that 404'd during parse: complete=true, naturalWidth=0, no future error.
+		Object.defineProperty(img, "complete", { value: true });
+		Object.defineProperty(img, "naturalWidth", { value: 0 });
+		document.body.appendChild(img);
+		sweepBrokenAvatars(document);
+		expect(
+			document.body.querySelector("span.avatar--initials")?.textContent,
+		).toBe("ZZ");
+	});
+
+	it("sweepBrokenAvatars leaves a successfully-loaded avatar alone", () => {
+		const img = document.createElement("img");
+		img.className = "avatar";
+		img.setAttribute("data-certrev-initials", "OK");
+		Object.defineProperty(img, "complete", { value: true });
+		Object.defineProperty(img, "naturalWidth", { value: 56 }); // loaded
+		document.body.appendChild(img);
+		sweepBrokenAvatars(document);
+		expect(
+			document.body.querySelector("img[data-certrev-initials]"),
+		).not.toBeNull();
+		expect(document.body.querySelector("span.avatar--initials")).toBeNull();
+	});
+
+	it("the capture-phase error listener swaps a broken avatar on its error event", () => {
+		const img = document.createElement("img");
+		img.className = "avatar";
+		img.setAttribute("data-certrev-initials", "AB");
+		document.body.appendChild(img);
+		initCertInteractions(document);
+		img.dispatchEvent(new Event("error")); // error doesn't bubble → handler is capture-phase
+		expect(
+			document.body.querySelector("span.avatar--initials")?.textContent,
+		).toBe("AB");
+	});
+});
+
+describe("initCertInteractions — delegated accordion + modal", () => {
+	it("a row click opens the accordion; a second click closes it", () => {
+		const { row } = mountCard();
+		initCertInteractions(document);
+		row.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+		expect(row.classList.contains("open")).toBe(true);
+		expect(row.getAttribute("aria-expanded")).toBe("true");
+		row.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+		expect(row.classList.contains("open")).toBe(false);
+		expect(row.getAttribute("aria-expanded")).toBe("false");
+	});
+
+	it("a click on a LINK inside the card does not toggle the accordion (the link has its own action)", () => {
+		const { card, row } = mountCard();
+		// Give the row an inner link to prove the guard (e.g. a future inline control).
+		const a = document.createElement("a");
+		a.href = "https://certrev.com/x";
+		a.textContent = "link";
+		row.querySelector(".info")!.appendChild(a);
+		initCertInteractions(document);
+		a.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+		expect(row.classList.contains("open")).toBe(false);
+		expect(card.querySelector("[data-certrev-acc].open")).toBeNull();
+	});
+
+	it("Enter on the role=button row toggles the accordion (a div fires no native click)", () => {
+		const { row } = mountCard();
+		initCertInteractions(document);
+		row.dispatchEvent(
+			new KeyboardEvent("keydown", { key: "Enter", bubbles: true }),
+		);
+		expect(row.classList.contains("open")).toBe(true);
+		row.dispatchEvent(
+			new KeyboardEvent("keydown", { key: " ", bubbles: true }),
+		);
+		expect(row.classList.contains("open")).toBe(false);
+	});
+
+	it("install is idempotent (second call does not double-bind — one click toggles exactly once)", () => {
+		const { row } = mountCard();
+		initCertInteractions(document);
+		initCertInteractions(document); // no-op second install
+		row.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+		// A double-bound handler would toggle twice (open → closed); one binding leaves it open.
+		expect(row.classList.contains("open")).toBe(true);
+	});
+});

package/src/modal/interactions.ts

@@ -0,0 +1,166 @@
+/**
+ * Cert-card INTERACTIONS for the native Shopify cert experience.
+ *
+ * Progressive enhancement, delegated from the document (one listener, survives the placement
+ * reposition). Two behaviours (POR-9827 chevron model):
+ *
+ *   • Accordion bios — a contributor row carrying `[data-certrev-acc]` toggles its `.open` class
+ *     (revealing the row's `.acc-bio` in place; the name caret rotates via CSS) and mirrors the
+ *     state on `aria-expanded`. A click on a link inside the row (e.g. the "Compensated expert"
+ *     cue) is NOT a toggle. Keyboard: Enter/Space on the role=button row.
+ *   • In-page modals: a `[data-certrev-modal-open]` control opens the unified
+ *     `<certrev-cert-modal>` element (POR-10102) via its `.open('cert'|'expert')` method. Bare /
+ *     `"cert"` opens the certificate dialog; `"expert"` opens the reviewer dialog. With no JS / no
+ *     element / no envelope a link control falls back to its href (the certificate or the CertREV
+ *     profile page). The element owns its OWN close plumbing (× / Close / backdrop / Esc) inside its
+ *     shadow root — a shadow click is retargeted to the host, so a document delegate can't see it.
+ *
+ * No crypto, no network — pure DOM. Idempotent install (guarded so a double-load can't double-bind).
+ */
+
+import { CERT_MODAL_TAG } from './certrev-cert-modal.js'
+
+export const ACC_ATTR = 'data-certrev-acc'
+export const MODAL_OPEN_ATTR = 'data-certrev-modal-open'
+export const INITIALS_ATTR = 'data-certrev-initials'
+export const CARD_SELECTOR = '.certrev-card'
+
+/** The dialog a `data-certrev-modal-open` control targets. */
+export type ModalKind = 'cert' | 'expert'
+
+/** The `<certrev-cert-modal>` element's public surface (defined in certrev-cert-modal.ts). */
+interface CertModalElement extends HTMLElement {
+	open(kind: ModalKind): boolean
+}
+
+/** Avatar base classes whose `--initials` variant is the SSR no-photo fallback (kept in lockstep
+ *  with certrev-badge.liquid / certrev-memo.liquid). A broken <img> is swapped to `{base} {base}--initials`. */
+const AVATAR_BASE_CLASSES = ['avatar', 'certrev-memo__avatar'] as const
+
+/** Documents that already have the delegated handlers, so a double script-load can't double-bind. */
+const installedDocs = new WeakSet<Document>()
+
+/** Toggle a contributor row's accordion bio open/closed (the `.open` class drives the CSS reveal +
+ *  caret rotation) and mirror the state on aria-expanded. */
+export function toggleAccordion(row: Element): void {
+	const open = row.classList.toggle('open')
+	row.setAttribute('aria-expanded', open ? 'true' : 'false')
+}
+
+/** Resolve a `data-certrev-modal-open` value to the dialog it opens. `"expert"` opens the reviewer
+ *  modal; anything else (the bare attribute, or `"cert"`) opens the certificate modal. */
+export function modalTargetKind(value: string | null): ModalKind {
+	return value === 'expert' ? 'expert' : 'cert'
+}
+
+/** Open a cert dialog via the `<certrev-cert-modal>` element. Returns false (so the caller lets an
+ *  href fall back) when the element is absent or declines (no envelope + no fetch source). */
+export function openModal(doc: Document, kind: ModalKind): boolean {
+	const el = doc.querySelector(CERT_MODAL_TAG) as CertModalElement | null
+	if (el && typeof el.open === 'function') return el.open(kind)
+	return false
+}
+
+/** Open the page's certificate modal (backward-compatible wrapper over openModal). */
+export function openCertModal(doc: Document): boolean {
+	return openModal(doc, 'cert')
+}
+
+function asElement(target: EventTarget | null): Element | null {
+	return target && (target as Element).closest ? (target as Element) : null
+}
+
+/**
+ * Replace a broken avatar `<img>` with its initials placeholder — the SAME markup the Liquid emits
+ * when no photo URL is present. The SSR can't know a present URL will 404 (the canary's expert photo
+ * does), so without this a broken-image icon shows instead of the clean initials circle.
+ */
+export function swapBrokenAvatar(img: HTMLImageElement): void {
+	const initials = img.getAttribute(INITIALS_ATTR)
+	if (initials == null) return
+	const base = AVATAR_BASE_CLASSES.find((c) => img.classList.contains(c))
+	if (!base) return
+	const span = img.ownerDocument.createElement('span')
+	span.className = `${base} ${base}--initials`
+	span.setAttribute('aria-hidden', 'true')
+	span.textContent = initials
+	img.replaceWith(span)
+}
+
+/**
+ * Swap every avatar that has ALREADY failed to load. A 404 fires `error` during parse — often
+ * before this bundle runs — and `error` doesn't re-fire, so the live `error` listener alone misses
+ * pre-init failures (observed on the canary). Safe to call repeatedly; only acts on broken imgs.
+ */
+export function sweepBrokenAvatars(doc: Document): void {
+	for (const img of Array.from(doc.querySelectorAll<HTMLImageElement>(`img[${INITIALS_ATTR}]`))) {
+		if (img.complete && img.naturalWidth === 0) swapBrokenAvatar(img)
+	}
+}
+
+/** Install the delegated click + keydown handlers on the document, once. */
+export function initCertInteractions(doc: Document): void {
+	if (installedDocs.has(doc)) return
+	installedDocs.add(doc)
+
+	doc.addEventListener('click', (e) => {
+		const el = asElement(e.target)
+		if (!el) return
+
+		// Modal open — intercept only when the element actually shows the dialog; else let the link navigate.
+		// (Close is owned by the <certrev-cert-modal> element inside its shadow root.)
+		const opener = el.closest(`[${MODAL_OPEN_ATTR}]`)
+		if (opener) {
+			if (openModal(doc, modalTargetKind(opener.getAttribute(MODAL_OPEN_ATTR)))) e.preventDefault()
+			return
+		}
+
+		// Accordion — but never when a link inside the row was clicked (it has its own action).
+		const row = el.closest(`[${ACC_ATTR}]`)
+		if (row && !el.closest('a, button')) toggleAccordion(row)
+	})
+
+	// Broken avatar photos → initials placeholder. `error` events don't bubble, so listen in the
+	// CAPTURE phase. One-shot per img (replaceWith removes it, so it can't re-fire).
+	doc.addEventListener(
+		'error',
+		(e) => {
+			const t = e.target as Element | null
+			if (t && t.tagName === 'IMG' && t.hasAttribute(INITIALS_ATTR)) swapBrokenAvatar(t as HTMLImageElement)
+		},
+		true,
+	)
+
+	// Catch avatars that already failed before this listener attached (see sweepBrokenAvatars).
+	sweepBrokenAvatars(doc)
+
+	// Keyboard parity: Enter/Space activates a role=button accordion row or a modal-open row (a <div>
+	// fires no native click on Enter). Native <a>/<button> triggers handle their own activation
+	// (their click reaches the click handler above), so skip those here to avoid a double-fire.
+	doc.addEventListener('keydown', (e) => {
+		if (e.key !== 'Enter' && e.key !== ' ' && e.key !== 'Spacebar') return
+		const el = asElement(e.target)
+		if (!el || el.closest('a, button')) return
+
+		const opener = el.closest(`[${MODAL_OPEN_ATTR}]`)
+		if (opener) {
+			if (openModal(doc, modalTargetKind(opener.getAttribute(MODAL_OPEN_ATTR)))) {
+				e.preventDefault()
+				return
+			}
+		}
+
+		const row = el.closest(`[${ACC_ATTR}]`)
+		if (row) {
+			e.preventDefault()
+			toggleAccordion(row)
+		}
+	})
+}
+
+/** Run interactions setup once the DOM is parsed. */
+export function initCertInteractionsOnReady(doc: Document): void {
+	const run = (): void => initCertInteractions(doc)
+	if (doc.readyState === 'loading') doc.addEventListener('DOMContentLoaded', run, { once: true })
+	else run()
+}

package/src/modal/logo-paths.ts

@@ -0,0 +1,23 @@
+// ⚠ VENDORED, BYTE-FAITHFUL copy of portal `src/lib/design-guide/logo.ts` `LOGO_PATHS`
+// (POR-10721 W2). Byte-identical to `../components/render-cert-block.ts`'s private copy;
+// kept modal-local so the browser bundle never pulls in the SSR renderer. Unifying the
+// package's two copies onto one shared leaf module is a post-publish follow-up.
+/**
+ * The CertREV 4-chevron logo mark — the canonical SVG path data (the four `d`
+ * attributes, drawn in a `0 0 375 375` viewBox). This is the SINGLE SOURCE for
+ * the mark across every cert-render surface (the standalone /embed renderers,
+ * the <certrev-cert-modal> web component, the Shopify Liquid snippets, the
+ * WordPress PHP renderer, and @certrev/cert-block).
+ *
+ * The paths were previously hand-copied into ~13 files; each of those should
+ * import THIS instead of re-declaring them. The codegen
+ * (`scripts/build-cert-design-artifacts.ts`) stamps these into
+ * `generated/design-tokens.json` + the WordPress `class-certrev-design-tokens.php`
+ * so the Liquid/PHP twins can never drift from this array.
+ */
+export const LOGO_PATHS = [
+	"M67.59 221.77L138.77 292.95C145.8 299.98 145.8 311.44 138.77 318.47L123.02 334.22C116 341.25 104.54 341.25 97.5 334.22L26.32 263.04C19.29 256.01 19.29 244.55 26.32 237.52L42.07 221.77C49.1 214.74 60.56 214.74 67.59 221.77Z",
+	"M96.79 335.08L81.12 319.42C73.8 312.1 73.8 300.23 81.12 292.92L315.88 58.16C323.2 50.85 335.06 50.85 342.38 58.16L358.04 73.83C365.36 81.14 365.36 93.01 358.04 100.33L123.29 335.08C115.97 342.4 104.1 342.4 96.79 335.08Z",
+	"M203.5 335.14L187.83 319.48C180.52 312.16 180.52 300.29 187.83 292.98L315.88 164.93C323.2 157.62 335.06 157.62 342.38 164.93L358.04 180.6C365.36 187.92 365.36 199.78 358.04 207.1L230 335.14C222.68 342.46 210.82 342.46 203.5 335.14Z",
+	"M310.21 335.2L294.54 319.54C287.23 312.22 287.23 300.36 294.54 293.04L315.88 271.71C323.2 264.39 335.06 264.39 342.38 271.71L358.04 287.37C365.36 294.69 365.36 306.55 358.04 313.87L336.71 335.2C329.39 342.52 317.53 342.52 310.21 335.2Z",
+] as const;