From 8baca79cdcfac39ef4c137f2c3b32f62ae05c2b3 Mon Sep 17 00:00:00 2001
From: Ruslan <rvasylkiv@thingsboard.io>
Date: Wed, 8 Jul 2026 11:59:36 +0300
Subject: [PATCH 1/2] refactor(faq): make FaqSection self-contained; emit
 FAQPage JSON-LD

Move the generic FAQ behavior (accordion, category tabs, load more,
copy-link, hash deep-link) into a script co-located with the component;
delete the duplicated copies (pricing inline handlers, iot-hub-faq.ts).
The pricing page keeps only its page-specific parts and opens items
through the new window.__tbFaqOpen API after activating the owning
product tab.

- New util builds schema.org FAQPage JSON (HTML stripped to plain text,
  entities decoded, `<` escaped so answer content can never terminate
  the script element); FaqSection emits it via a jsonLd prop. IoT Hub
  pages keep their existing schema (FaqJsonLd.astro absorbed);
  /pricing/ gains one block for the default-visible Public Cloud
  context.
- A11y: copy-link is a real button (was span[role=button] nested inside
  the question button - invalid nesting, and keyboard-dead on pricing);
  the heading wraps only the toggle so its accessible name is the
  question alone; aria-controls wired to new answer ids; aria-current
  SSR'd on active category tabs; focus-visible styles on both buttons.
- Analytics via an opt-in prop: pricing keeps faq_copy_link /
  faq_node_interaction, iot-hub stays silent (both as before). One
  deliberate change: repeat jumps to an already-open item no longer
  re-push faq_node_interaction (opens only, matching the accordion
  handler's documented semantics).
- Fix a duplicate DOM id in the self-managed FAQ data (the second item
  was unreachable by deep link and blocked aria-controls).
---
 src/components/IotHub/CategoryFaq.astro |  11 +-
 src/components/IotHub/FaqJsonLd.astro   |  32 ---
 src/components/IotHub/iot-hub-faq.ts    | 127 -----------
 src/components/Pricing/FaqSection.astro | 279 +++++++++++++++++++++---
 src/data/pricing/faq/tb-self-managed.ts |   4 +-
 src/pages/pricing/index.astro           | 161 ++++----------
 src/util/faq-schema.ts                  |  49 +++++
 7 files changed, 342 insertions(+), 321 deletions(-)
 delete mode 100644 src/components/IotHub/FaqJsonLd.astro
 delete mode 100644 src/components/IotHub/iot-hub-faq.ts
 create mode 100644 src/util/faq-schema.ts

diff --git a/src/components/IotHub/CategoryFaq.astro b/src/components/IotHub/CategoryFaq.astro
index 670afe7cc7..2aa2cdaee3 100644
--- a/src/components/IotHub/CategoryFaq.astro
+++ b/src/components/IotHub/CategoryFaq.astro
@@ -1,6 +1,5 @@
 ---
 import FaqSection from '@components/Pricing/FaqSection.astro';
-import FaqJsonLd from '@components/IotHub/FaqJsonLd.astro';
 import { getCategoryFaq } from '@data/iot-hub/sections';
 import { IOT_HUB_STRINGS } from '@models/iot-hub';
 
@@ -14,10 +13,9 @@ const groups = getCategoryFaq(categorySlug);
 
 {
 	groups && (
-		<section class="ih-faq" data-iot-hub-faq>
+		<section class="ih-faq">
 			<h2 class="ih-faq__title">{IOT_HUB_STRINGS.faqHeading}</h2>
-			<FaqSection contextId={`iot-hub-${categorySlug}`} categories={groups} />
-			<FaqJsonLd groups={groups} />
+			<FaqSection contextId={`iot-hub-${categorySlug}`} categories={groups} jsonLd />
 		</section>
 	)
 }
@@ -38,8 +36,3 @@ const groups = getCategoryFaq(categorySlug);
 		@include iot-hub-section-title;
 	}
 </style>
-
-<script>
-	import { initIotHubFaq } from '@components/IotHub/iot-hub-faq';
-	initIotHubFaq();
-</script>
diff --git a/src/components/IotHub/FaqJsonLd.astro b/src/components/IotHub/FaqJsonLd.astro
deleted file mode 100644
index c72c620e24..0000000000
--- a/src/components/IotHub/FaqJsonLd.astro
+++ /dev/null
@@ -1,32 +0,0 @@
----
-import type { FaqGroup } from '@models/iot-hub-sections';
-
-interface Props {
-	groups: FaqGroup[];
-}
-
-const { groups } = Astro.props;
-
-const stripHtml = (s: string) =>
-	s
-		.replace(/<[^>]+>/g, '')
-		.replace(/\s+/g, ' ')
-		.trim();
-
-const jsonLd = {
-	'@context': 'https://schema.org',
-	'@type': 'FAQPage',
-	mainEntity: groups.flatMap((group) =>
-		group.items.map((item) => ({
-			'@type': 'Question',
-			name: item.question,
-			acceptedAnswer: {
-				'@type': 'Answer',
-				text: stripHtml(item.answer),
-			},
-		}))
-	),
-};
----
-
-<script type="application/ld+json" set:html={JSON.stringify(jsonLd)} is:inline />
diff --git a/src/components/IotHub/iot-hub-faq.ts b/src/components/IotHub/iot-hub-faq.ts
deleted file mode 100644
index 5ca5323323..0000000000
--- a/src/components/IotHub/iot-hub-faq.ts
+++ /dev/null
@@ -1,127 +0,0 @@
-// Self-contained interactivity for the reused Pricing/FaqSection markup on IoT
-// Hub pages: accordion toggle, "Load more", category tabs, copy-link, and
-// hash deep-linking. Kept local (not shared with the pricing page's inline
-// script) so the IoT Hub FAQ owns its own behavior.
-
-export function initIotHubFaq(): void {
-	const root = document.querySelector<HTMLElement>('[data-iot-hub-faq]');
-	if (!root) return;
-
-	const copyFaqLink = (copyLink: HTMLElement): void => {
-		const faqId = copyLink.dataset.faqId;
-		if (!faqId?.trim()) return;
-		const url = new URL(window.location.href);
-		url.hash = faqId;
-		navigator.clipboard
-			.writeText(url.toString())
-			.then(() => {
-				copyLink.classList.add('copied');
-				setTimeout(() => copyLink.classList.remove('copied'), 2000);
-			})
-			.catch(() => {});
-	};
-
-	root.addEventListener('click', (e) => {
-		// `e.target` can be a non-Element (e.g. a Text node); `.closest()` only
-		// exists on Element, so bail out otherwise.
-		if (!(e.target instanceof Element)) return;
-		const target = e.target;
-
-		// Copy link to a question
-		const copyLink = target.closest<HTMLElement>('.faq-copy-link');
-		if (copyLink) {
-			e.stopPropagation();
-			copyFaqLink(copyLink);
-			return;
-		}
-
-		// Accordion toggle
-		const question = target.closest<HTMLElement>('.faq-question');
-		if (question) {
-			const item = question.closest('.faq-item');
-			if (item) {
-				item.classList.toggle('expanded');
-				question.setAttribute('aria-expanded', String(item.classList.contains('expanded')));
-			}
-			return;
-		}
-
-		// "Load more"
-		const loadMore = target.closest<HTMLElement>('.faq-load-more');
-		if (loadMore) {
-			const content = loadMore.closest('.faq-category-content');
-			if (content) {
-				content
-					.querySelectorAll('.faq-item--hidden')
-					.forEach((el) => el.classList.remove('faq-item--hidden'));
-				loadMore.classList.add('faq-load-more--used');
-			}
-			return;
-		}
-
-		// Category tabs
-		const catTab = target.closest<HTMLElement>('.faq-cat-tab');
-		if (catTab) {
-			const section = catTab.closest('.faq-section');
-			if (section) {
-				const catId = catTab.dataset.faqCat;
-				section.querySelectorAll<HTMLElement>('.faq-cat-tab').forEach((t) => {
-					const isActive = t.dataset.faqCat === catId;
-					t.classList.toggle('active', isActive);
-					t.setAttribute('aria-current', isActive ? 'true' : 'false');
-				});
-				section
-					.querySelectorAll<HTMLElement>('.faq-category-content')
-					.forEach((c) => c.classList.toggle('active', c.dataset.faqCatContent === catId));
-			}
-			return;
-		}
-	});
-
-	// The copy-link is a span[role="button"][tabindex="0"]; mirror native button
-	// keyboard activation (Enter/Space) so it's operable without a pointer.
-	root.addEventListener('keydown', (e) => {
-		if (e.key !== 'Enter' && e.key !== ' ') return;
-		if (!(e.target instanceof Element)) return;
-		const copyLink = e.target.closest<HTMLElement>('.faq-copy-link');
-		if (!copyLink) return;
-		e.preventDefault();
-		copyFaqLink(copyLink);
-	});
-
-	// Deep-link: open the FAQ item referenced by the URL hash. Deferred to idle
-	// so the hash walk + scrollIntoView never block first paint.
-	const performHashWalk = (): void => {
-		const hash = window.location.hash.slice(1);
-		if (!hash) return;
-		const item = document.getElementById(hash);
-		if (!item?.classList.contains('faq-item')) return;
-
-		const content = item.closest<HTMLElement>('.faq-category-content');
-		const section = item.closest('.faq-section');
-		if (content && section) {
-			const catId = content.dataset.faqCatContent;
-			section.querySelectorAll<HTMLElement>('.faq-cat-tab').forEach((t) => {
-				const isActive = t.dataset.faqCat === catId;
-				t.classList.toggle('active', isActive);
-				t.setAttribute('aria-current', isActive ? 'true' : 'false');
-			});
-			section
-				.querySelectorAll<HTMLElement>('.faq-category-content')
-				.forEach((c) => c.classList.toggle('active', c === content));
-		}
-		item.classList.remove('faq-item--hidden');
-		item.classList.add('expanded');
-		item.querySelector('.faq-question')?.setAttribute('aria-expanded', 'true');
-		item.scrollIntoView({ block: 'center' });
-	};
-
-	// Bounded idle: a #hash deep-link should still open promptly even on a
-	// busy main thread, and the later the scrollIntoView lands the more
-	// jarring it is.
-	if ('requestIdleCallback' in window) {
-		requestIdleCallback(performHashWalk, { timeout: 500 });
-	} else {
-		setTimeout(performHashWalk, 200);
-	}
-}
diff --git a/src/components/Pricing/FaqSection.astro b/src/components/Pricing/FaqSection.astro
index ee3bc3bd0e..ef7fe185ff 100644
--- a/src/components/Pricing/FaqSection.astro
+++ b/src/components/Pricing/FaqSection.astro
@@ -1,27 +1,39 @@
 ---
 import type { FaqCategory } from '@data/pricing/types.ts';
+import { buildFaqPageSchema, serializeJsonLd } from '@util/faq-schema';
 
-// This `.faq-*` markup contract is driven by two separate scripts: the pricing
-// page's own inline script, and `@components/IotHub/iot-hub-faq.ts` for IoT Hub
-// pages. Keep the class names / data attributes stable, or update both.
+// Self-contained FAQ section: markup, styles, and behavior (accordion, category
+// tabs, "Load more", copy-link, hash deep-link) all live here. Page scripts may
+// still target the `.faq-*` markup contract (the pricing page activates its
+// product tabs around it and calls `window.__tbFaqOpen`), so keep the class
+// names / data attributes stable, or update those consumers too.
 
 interface Props {
 	contextId: string;
 	categories: FaqCategory[];
 	/** Number of items visible per category before "Load more" (default: 6) */
 	visibleCount?: number;
+	/** Push `faq_*` events to the GTM dataLayer on interaction (marketing-owned). */
+	analytics?: boolean;
+	/** Emit a schema.org FAQPage block for this section. At most one per page. */
+	jsonLd?: boolean;
 }
 
-const { contextId, categories, visibleCount = 6 } = Astro.props;
+const { contextId, categories, visibleCount = 6, analytics = false, jsonLd = false } = Astro.props;
 ---
 
-<div class={`faq-section ${categories.length > 1 ? 'faq-section--with-sidebar' : ''}`} data-faq-context={contextId}>
+<div
+	class={`faq-section ${categories.length > 1 ? 'faq-section--with-sidebar' : ''}`}
+	data-faq-context={contextId}
+	data-faq-analytics={analytics ? '' : undefined}
+>
 	{categories.length > 1 && (
 		<div class="faq-cat-sidebar">
 			{categories.map((cat, i) => (
 				<button
 					type="button"
 					class={`faq-cat-tab ${i === 0 ? 'active' : ''}`}
+					aria-current={i === 0 ? 'true' : 'false'}
 					data-faq-cat={cat.id}
 				>
 					{cat.label}
@@ -41,13 +53,24 @@ const { contextId, categories, visibleCount = 6 } = Astro.props;
 				>
 					{visible.map((item) => (
 						<div class="faq-item" id={item.id}>
-							<button type="button" class="faq-question" aria-expanded="false">
-								<h3 class="faq-question-text">{item.question}
-									<span class="faq-copy-link" data-faq-id={item.id} role="button" tabindex="0" aria-label={`Copy link to: ${item.question}`}></span>
+							<div class="faq-question">
+								<h3 class="faq-question-heading">
+									<button
+										type="button"
+										class="faq-question-toggle"
+										aria-expanded="false"
+										aria-controls={`${item.id}-answer`}
+									>{item.question}</button>
 								</h3>
+								<button
+									type="button"
+									class="faq-copy-link"
+									data-faq-id={item.id}
+									aria-label={`Copy link to: ${item.question}`}
+								></button>
 								<span class="faq-chevron" aria-hidden="true"></span>
-							</button>
-							<div class="faq-answer">
+							</div>
+							<div class="faq-answer" id={`${item.id}-answer`}>
 								<div class="faq-answer-overflow">
 									<div class="faq-answer-content" set:html={item.answer} />
 								</div>
@@ -63,13 +86,24 @@ const { contextId, categories, visibleCount = 6 } = Astro.props;
 
 					{overflow.map((item) => (
 						<div class="faq-item faq-item--hidden" id={item.id}>
-							<button type="button" class="faq-question" aria-expanded="false">
-								<h3 class="faq-question-text">{item.question}
-									<span class="faq-copy-link" data-faq-id={item.id} role="button" tabindex="0" aria-label={`Copy link to: ${item.question}`}></span>
+							<div class="faq-question">
+								<h3 class="faq-question-heading">
+									<button
+										type="button"
+										class="faq-question-toggle"
+										aria-expanded="false"
+										aria-controls={`${item.id}-answer`}
+									>{item.question}</button>
 								</h3>
+								<button
+									type="button"
+									class="faq-copy-link"
+									data-faq-id={item.id}
+									aria-label={`Copy link to: ${item.question}`}
+								></button>
 								<span class="faq-chevron" aria-hidden="true"></span>
-							</button>
-							<div class="faq-answer">
+							</div>
+							<div class="faq-answer" id={`${item.id}-answer`}>
 								<div class="faq-answer-overflow">
 									<div class="faq-answer-content" set:html={item.answer} />
 								</div>
@@ -82,6 +116,148 @@ const { contextId, categories, visibleCount = 6 } = Astro.props;
 	</div>
 </div>
 
+{jsonLd && (
+	<script
+		type="application/ld+json"
+		set:html={serializeJsonLd(buildFaqPageSchema(categories))}
+		is:inline
+	/>
+)}
+
+<script>
+	// Runs once per page (Astro dedupes the bundled module) and drives every
+	// `.faq-section` instance via document-level delegation — the pricing page
+	// renders eight at once. All branches require a `.faq-section` ancestor:
+	// other pages (partners, Trendz) reuse `.faq-*` class names with their own
+	// incompatible markup and must stay untouched.
+
+	declare global {
+		interface Window {
+			/** Open + scroll to a FAQ item by id (used by the pricing page). */
+			__tbFaqOpen?: (faqId: string) => void;
+		}
+	}
+
+	const trackFaq = (event: string, faqId: string, origin: Element): void => {
+		// Marketing owns the GTM triggers + GA4 tags for these events; only
+		// sections that opt in via the `analytics` prop push them.
+		if (origin.closest('.faq-section[data-faq-analytics]')) {
+			window.dataLayer?.push({ event, faq_node_id: faqId });
+		}
+	};
+
+	const copyFaqLink = (copyLink: HTMLElement): void => {
+		const faqId = copyLink.dataset.faqId;
+		if (!faqId?.trim()) return;
+		trackFaq('faq_copy_link', faqId, copyLink);
+		const url = new URL(window.location.href);
+		url.hash = faqId;
+		navigator.clipboard
+			.writeText(url.toString())
+			.then(() => {
+				copyLink.classList.add('copied');
+				setTimeout(() => copyLink.classList.remove('copied'), 2000);
+			})
+			.catch(() => {});
+	};
+
+	const activateCategoryTab = (section: Element, catId: string | undefined): void => {
+		if (!catId) return;
+		section.querySelectorAll<HTMLElement>('.faq-cat-tab').forEach((tab) => {
+			const isActive = tab.dataset.faqCat === catId;
+			tab.classList.toggle('active', isActive);
+			tab.setAttribute('aria-current', isActive ? 'true' : 'false');
+		});
+		section
+			.querySelectorAll<HTMLElement>('.faq-category-content')
+			.forEach((c) => c.classList.toggle('active', c.dataset.faqCatContent === catId));
+	};
+
+	const setExpanded = (item: Element, expanded: boolean): void => {
+		item.classList.toggle('expanded', expanded);
+		item.querySelector('.faq-question-toggle')?.setAttribute('aria-expanded', String(expanded));
+	};
+
+	const revealCategoryOverflow = (content: Element): void => {
+		content
+			.querySelectorAll('.faq-item--hidden')
+			.forEach((el) => el.classList.remove('faq-item--hidden'));
+		content.querySelector('.faq-load-more')?.classList.add('faq-load-more--used');
+	};
+
+	const openFaqItem = (faqId: string): void => {
+		const item = document.getElementById(faqId);
+		if (!item?.classList.contains('faq-item')) return;
+		const section = item.closest('.faq-section');
+		const content = item.closest<HTMLElement>('.faq-category-content');
+		if (!section || !content) return;
+		activateCategoryTab(section, content.dataset.faqCatContent);
+		if (item.classList.contains('faq-item--hidden')) revealCategoryOverflow(content);
+		if (!item.classList.contains('expanded')) {
+			setExpanded(item, true);
+			trackFaq('faq_node_interaction', faqId, item);
+		}
+		// Let the expand animation start so centering lands on the final layout.
+		setTimeout(() => item.scrollIntoView({ behavior: 'smooth', block: 'center' }), 100);
+	};
+	window.__tbFaqOpen = openFaqItem;
+
+	document.addEventListener('click', (e) => {
+		// `e.target` can be a non-Element (e.g. a Text node); `.closest()` only
+		// exists on Element, so bail out otherwise.
+		if (!(e.target instanceof Element)) return;
+		const target = e.target;
+
+		const copyLink = target.closest<HTMLElement>('.faq-copy-link');
+		if (copyLink) {
+			if (copyLink.closest('.faq-section')) copyFaqLink(copyLink);
+			return;
+		}
+
+		const toggle = target.closest<HTMLElement>('.faq-question-toggle');
+		if (toggle) {
+			const item = toggle.closest('.faq-item');
+			if (item && toggle.closest('.faq-section')) {
+				const nowExpanded = !item.classList.contains('expanded');
+				setExpanded(item, nowExpanded);
+				// Track opens only (not collapses).
+				if (nowExpanded && item.id) trackFaq('faq_node_interaction', item.id, item);
+			}
+			return;
+		}
+
+		const loadMore = target.closest<HTMLElement>('.faq-load-more');
+		if (loadMore) {
+			const content = loadMore.closest('.faq-category-content');
+			if (content && loadMore.closest('.faq-section')) revealCategoryOverflow(content);
+			return;
+		}
+
+		const catTab = target.closest<HTMLElement>('.faq-cat-tab');
+		if (catTab) {
+			const section = catTab.closest('.faq-section');
+			if (section) activateCategoryTab(section, catTab.dataset.faqCat);
+		}
+	});
+
+	// Deep-link: open the FAQ item referenced by the URL hash. Deferred to idle
+	// (bounded — a late scrollIntoView is jarring) so the walk never blocks
+	// first paint. Skips items a page script already opened via __tbFaqOpen.
+	const performHashWalk = (): void => {
+		const hash = window.location.hash.slice(1);
+		if (!hash) return;
+		const item = document.getElementById(hash);
+		if (!item?.classList.contains('faq-item') || !item.closest('.faq-section')) return;
+		if (item.classList.contains('expanded')) return;
+		openFaqItem(hash);
+	};
+	if ('requestIdleCallback' in window) {
+		requestIdleCallback(performHashWalk, { timeout: 500 });
+	} else {
+		setTimeout(performHashWalk, 200);
+	}
+</script>
+
 <style lang="scss" is:global>
 	@use '../../styles/variables' as *;
 
@@ -186,32 +362,62 @@ const { contextId, categories, visibleCount = 6 } = Astro.props;
 	}
 
 	// ─── Question row ───
+	// The row is a plain div; the heading wraps ONLY the toggle so its
+	// accessible name is just the question. The toggle's stretched ::after
+	// overlay makes the whole row clickable while the copy-link stays a real
+	// sibling button — no interactive nesting.
 	.faq-question {
-		width: 100%;
+		position: relative;
 		display: flex;
 		align-items: center;
 		gap: $spacing-4;
+		margin: 0;
 		padding: $spacing-4 $spacing-5;
-		border: none;
-		background: none;
-		cursor: pointer;
-		text-align: left;
+		font-size: $font-size-base;
+		font-weight: $font-weight-medium;
+		line-height: 1.5;
 		color: var(--color-text);
+		cursor: pointer;
 
-		&:hover .faq-question-text {
+		&:hover .faq-question-toggle {
 			color: var(--color-primary);
 		}
 	}
 
-	.faq-question-text {
-		// Element is h3 for SEO — reset browser defaults to keep original row styling.
+	.faq-question-heading {
 		flex: 1;
+		min-width: 0;
 		margin: 0;
-		font-size: $font-size-base;
-		font-weight: $font-weight-medium;
-		line-height: 1.5;
-		color: var(--color-text);
+		font: inherit;
+	}
+
+	.faq-question-toggle {
+		width: 100%;
+		padding: 0;
+		border: none;
+		background: none;
+		font: inherit;
+		color: inherit;
+		text-align: left;
+		cursor: pointer;
 		transition: color 0.15s ease;
+
+		// Stretch the hit area over the whole question row.
+		&::after {
+			content: '';
+			position: absolute;
+			inset: 0;
+		}
+
+		&:focus-visible {
+			outline: none;
+
+			&::after {
+				outline: 2px solid var(--color-primary);
+				outline-offset: -2px;
+				border-radius: $radius-lg;
+			}
+		}
 	}
 
 	// Drawn as CSS masks so ~500 FAQ rows share one icon definition instead of
@@ -229,15 +435,21 @@ const { contextId, categories, visibleCount = 6 } = Astro.props;
 		mask: $faq-chevron-icon no-repeat center / contain;
 		-webkit-mask: $faq-chevron-icon no-repeat center / contain;
 		flex-shrink: 0;
+		// Clicks fall through to the toggle's stretched hit-area overlay.
+		pointer-events: none;
 		transition: transform 0.25s ease;
 	}
 
-	// ─── Copy link (inline right after question text) ───
+	// ─── Copy link (right rail, before the chevron) ───
 	.faq-copy-link {
 		position: relative;
+		// Above the toggle's stretched hit-area overlay.
+		z-index: 1;
 		display: inline-flex;
-		vertical-align: baseline;
-		margin-left: 6px;
+		flex-shrink: 0;
+		padding: 0;
+		border: none;
+		background: none;
 		cursor: pointer;
 		opacity: 0;
 		color: var(--color-primary);
@@ -265,6 +477,13 @@ const { contextId, categories, visibleCount = 6 } = Astro.props;
 			opacity: 1 !important;
 		}
 
+		&:focus-visible {
+			opacity: 1;
+			outline: 2px solid currentColor;
+			outline-offset: 2px;
+			border-radius: 2px;
+		}
+
 		// Tooltip
 		&::after {
 			content: 'Copy link';
diff --git a/src/data/pricing/faq/tb-self-managed.ts b/src/data/pricing/faq/tb-self-managed.ts
index ab24ebe566..d75b9b6722 100644
--- a/src/data/pricing/faq/tb-self-managed.ts
+++ b/src/data/pricing/faq/tb-self-managed.ts
@@ -270,7 +270,9 @@ export const tbSelfManagedFaq: FaqCategory[] = [
 				answer: '<p>Yes, the Maker plan ($10/month) is a low-cost way to explore the platform. It also includes trial license for Edge and Trendz products, so you can fully test the ThingsBoard ecosystem.</p>',
 			},
 			{
-				id: 'pe-pay-as-you-go-cancel-subscription',
+				// Not 'pe-pay-as-you-go-cancel-subscription': that id belongs to the
+				// "Billing & Payments" item above, and item ids are DOM ids.
+				id: 'pe-pay-as-you-go-cancel-consequences',
 				question: 'What happens if I cancel my subscription?',
 				answer: '<p>Your license will become inactive, and your ThingsBoard instance will be stopped.</p>',
 			},
diff --git a/src/pages/pricing/index.astro b/src/pages/pricing/index.astro
index 0c8b2a9da9..b6aa01226a 100644
--- a/src/pages/pricing/index.astro
+++ b/src/pages/pricing/index.astro
@@ -43,6 +43,12 @@ import cloudIcon from '../../assets/pricing/cloud-icon.svg?raw';
 import pcIcon from '../../assets/pricing/private-cloud-icon.svg?raw';
 import smIcon from '../../assets/pricing/self-icon.svg?raw';
 
+// One FAQPage schema block per page: emit it only for the context that is
+// visible by default (Public Cloud). The other seven contexts stay
+// display:none until a pricing tab reveals them, so marking them up would
+// describe content Google considers absent.
+const FAQ_JSONLD_CONTEXT = 'thingsboard-cloud';
+
 // Build a faqId → answer lookup from all FAQ data (strip HTML, truncate for tooltip)
 const faqAnswerMap = new Map<string, string>();
 for (const section of pricingFaqData) {
@@ -516,7 +522,12 @@ const tbmqSubTabs = enrichTabs([
 				pricingFaqData.map((faq) => (
 					<div class="pricing-faq-block" data-faq-context={faq.contextId}>
 						<h2 class="faq-main-title">{faq.title}</h2>
-						<FaqSection contextId={faq.contextId} categories={faq.categories} />
+						<FaqSection
+							contextId={faq.contextId}
+							categories={faq.categories}
+							analytics
+							jsonLd={faq.contextId === FAQ_JSONLD_CONTEXT}
+						/>
 					</div>
 				))
 			}
@@ -827,12 +838,13 @@ const tbmqSubTabs = enrichTabs([
 
 		// `.sub-tab` click is delegated above on `main.pricing-page`.
 
-		// ─── Helper: scroll to FAQ item (handles hidden, category, expand) ───
+		// ─── Helper: scroll to FAQ item (activates the owning pricing tab first) ───
 		function scrollToFaqItem(faqId: string) {
 			const targetItem = document.getElementById(faqId);
 			if (!targetItem?.classList.contains('faq-item')) return;
 
-			// Activate the sub-tab whose FAQ context contains this item
+			// Activate the sub-tab whose FAQ context contains this item — the
+			// FAQ block is display:none until its owning tab is active.
 			const faqBlock = targetItem.closest('.pricing-faq-block') as HTMLElement;
 			if (faqBlock) {
 				const ctx = faqBlock.dataset.faqContext;
@@ -852,35 +864,20 @@ const tbmqSubTabs = enrichTabs([
 				}
 			}
 
-			const faqSection = targetItem.closest('.faq-section') as HTMLElement;
-			const catContent = targetItem.closest('.faq-category-content') as HTMLElement;
-			if (!faqSection || !catContent) return;
-
-			// Activate the right FAQ category tab
-			const catId = catContent.dataset.faqCatContent;
-			if (catId) {
-				$$('.faq-cat-tab', faqSection).forEach((t) =>
-					t.classList.toggle('active', (t as HTMLElement).dataset.faqCat === catId)
-				);
-				$$('.faq-category-content', faqSection).forEach((c) =>
-					c.classList.toggle('active', (c as HTMLElement).dataset.faqCatContent === catId)
+			// The shared FaqSection script owns category-tab activation, hidden
+			// reveal, expand, and scroll. Module eval order between this script
+			// and the component's isn't guaranteed during load, so the initial
+			// deep-link falls back to an idle retry.
+			if (window.__tbFaqOpen) {
+				window.__tbFaqOpen(faqId);
+			} else {
+				(window.requestIdleCallback || ((cb: () => void) => setTimeout(cb, 200)))(
+					() => {
+						window.__tbFaqOpen?.(faqId);
+					},
+					{ timeout: 2000 }
 				);
 			}
-
-			// Reveal if hidden behind "Show more"
-			if (targetItem.classList.contains('faq-item--hidden')) {
-				$$('.faq-item--hidden', catContent).forEach((el) => el.classList.remove('faq-item--hidden'));
-				const loadMoreBtn = catContent.querySelector('.faq-load-more');
-				if (loadMoreBtn) loadMoreBtn.classList.add('faq-load-more--used');
-			}
-
-			// Expand and scroll
-			targetItem.classList.add('expanded');
-			const questionBtn = targetItem.querySelector('.faq-question');
-			if (questionBtn) questionBtn.setAttribute('aria-expanded', 'true');
-			// Track FAQ open from deep link (same event as accordion-open handler).
-			window.dataLayer?.push({ event: 'faq_node_interaction', faq_node_id: targetItem.id });
-			setTimeout(() => targetItem.scrollIntoView({ behavior: 'smooth', block: 'center' }), 100);
 		}
 
 		// `.sub-tab-info` click (FAQ scroll) is delegated above on `main.pricing-page`.
@@ -1221,7 +1218,11 @@ const tbmqSubTabs = enrichTabs([
 		// `.plan-card-cta[data-product-id][data-plan-id]` click is delegated above.
 		// `.topup-header` click (accordion) is delegated above.
 
-		// ─── FAQ — single delegated listener for all FAQ interactions ───
+		// ─── FAQ answers: calculator-open links ───
+		// Generic FAQ behavior (accordion, category tabs, copy-link, load-more,
+		// hash deep-link) lives in the shared FaqSection component script; only
+		// the pricing-specific calculator links inside answer HTML are handled
+		// here (they replace a former inline onclick).
 		// Guard: register this document-level listener only once. initPricing()
 		// runs a single time per page load (no ClientRouter / View Transitions),
 		// but the flag keeps registration idempotent if it's ever invoked again —
@@ -1230,56 +1231,6 @@ const tbmqSubTabs = enrichTabs([
 			(window as any)._pricingClickInit = true;
 			document.addEventListener('click', (e) => {
 				const target = e.target as HTMLElement;
-
-				// FAQ copy link (check BEFORE question toggle — it's nested inside .faq-question)
-				const copyLink = target.closest('.faq-copy-link') as HTMLElement | null;
-				if (copyLink) {
-					e.stopPropagation();
-					e.preventDefault();
-					const faqId = copyLink.dataset.faqId;
-					if (!faqId?.trim()) return;
-					// Track copy-link clicks (GTM trigger + GA4 tag owned by marketing).
-					window.dataLayer?.push({ event: 'faq_copy_link', faq_node_id: copyLink.dataset.faqId });
-					const url = new URL(window.location.href);
-					url.hash = faqId;
-					navigator.clipboard
-						.writeText(url.toString())
-						.then(() => {
-							copyLink.classList.add('copied');
-							setTimeout(() => copyLink.classList.remove('copied'), 2000);
-						})
-						.catch(() => {});
-					return;
-				}
-
-				// FAQ accordion toggle
-				const question = target.closest('.faq-question') as HTMLElement | null;
-				if (question) {
-					const item = question.closest('.faq-item');
-					if (item) {
-						const nowExpanded = item.classList.toggle('expanded');
-						question.setAttribute('aria-expanded', String(nowExpanded));
-						// Track FAQ opens only (not collapses). Marketing owns the
-						// GTM trigger + GA4 tag (event `faq_node_interaction`).
-						if (nowExpanded && item.id) {
-							window.dataLayer?.push({ event: 'faq_node_interaction', faq_node_id: item.id });
-						}
-					}
-					return;
-				}
-
-				// FAQ "Show more"
-				const loadMore = target.closest('.faq-load-more') as HTMLElement | null;
-				if (loadMore) {
-					const content = loadMore.closest('.faq-category-content');
-					if (content) {
-						$$('.faq-item--hidden', content).forEach((el) => el.classList.remove('faq-item--hidden'));
-						loadMore.classList.add('faq-load-more--used');
-					}
-					return;
-				}
-
-				// FAQ calculator-open link (replaces former inline onclick in FAQ HTML)
 				const calcLink = target.closest('[data-open-calc]') as HTMLElement | null;
 				if (calcLink) {
 					e.preventDefault();
@@ -1287,33 +1238,14 @@ const tbmqSubTabs = enrichTabs([
 					const fnName = which === 'pc' ? 'openTbPcCalc' :  'openTbPaygCalc';
 					(window as any)[fnName]?.();
 					window.scrollTo({ top: 0, behavior: 'smooth' });
-					return;
-				}
-
-				// FAQ category tabs
-				const catTab = target.closest('.faq-cat-tab') as HTMLElement | null;
-				if (catTab) {
-					const section = catTab.closest('.faq-section');
-					if (section) {
-						const catId = catTab.dataset.faqCat;
-						$$('.faq-cat-tab', section).forEach((t) => {
-							const isActive = (t as HTMLElement).dataset.faqCat === catId;
-							t.classList.toggle('active', isActive);
-							t.setAttribute('aria-current', isActive ? 'true' : 'false');
-						});
-						$$('.faq-category-content', section).forEach((c) =>
-							c.classList.toggle('active', (c as HTMLElement).dataset.faqCatContent === catId)
-						);
-					}
-					return;
 				}
 			});
 		}
 
 		// ─── FAQ category from URL (?faqSection=…) ───
 		// Deferred to idle — activating a category tab below the fold isn't
-		// LCP-critical. The hash-based deep-link below stays SYNCHRONOUS so
-		// `/pricing/#faq-foo` URLs land on the right item without jank.
+		// LCP-critical. The hash-based deep-link below reads the hash
+		// SYNCHRONOUSLY (updateUrl() strips it during init).
 		const faqSectionParam = params.get('faqSection');
 		if (faqSectionParam) {
 			const activateFaqCategory = () => {
@@ -1327,30 +1259,15 @@ const tbmqSubTabs = enrichTabs([
 			(window.requestIdleCallback || ((cb: () => void) => setTimeout(cb, 200)))(activateFaqCategory, { timeout: 2000 });
 		}
 
-		// ─── FAQ deep-link on load (synchronous — preserves /pricing/#faq-id) ───
+		// ─── FAQ deep-link on load ───
+		// The hash is read synchronously — updateUrl()'s replaceState strips it
+		// from the address bar during init, so a deferred read would find
+		// nothing. scrollToFaqItem activates the owning product/sub-tab here,
+		// then hands off to the shared FaqSection script for reveal + scroll.
 		const hash = window.location.hash.slice(1);
 		if (hash) {
 			const targetItem = document.getElementById(hash);
 			if (targetItem?.classList.contains('faq-item')) {
-				// Find which FAQ section this belongs to and activate the right product/sub-tab
-				const faqBlock = targetItem.closest('.pricing-faq-block') as HTMLElement;
-				if (faqBlock) {
-					const ctx = faqBlock.dataset.faqContext;
-					if (ctx) {
-						for (const [tabId, contexts] of Object.entries(faqContextMap)) {
-							if (contexts.includes(ctx)) {
-								if (tabId.startsWith('tbmq')) {
-									activateProductTab('tbmq');
-								} else {
-									activateProductTab('thingsboard');
-								}
-								activateSubTab(tabId);
-								break;
-							}
-						}
-					}
-				}
-				// scrollToFaqItem handles category tab, hidden reveal, expand, and scroll
 				scrollToFaqItem(hash);
 			}
 
diff --git a/src/util/faq-schema.ts b/src/util/faq-schema.ts
new file mode 100644
index 0000000000..1078f6c731
--- /dev/null
+++ b/src/util/faq-schema.ts
@@ -0,0 +1,49 @@
+// schema.org FAQPage builder shared by every FaqSection consumer.
+
+import type { FaqCategory } from '@data/pricing/types';
+
+// Answers are HTML strings; the schema wants plain text. Entities are decoded
+// because `<script>` raw text is never entity-decoded by the browser — a
+// literal `&rarr;` would otherwise surface verbatim in search results.
+const ENTITIES: Record<string, string> = {
+	'&amp;': '&',
+	'&lt;': '<',
+	'&gt;': '>',
+	'&quot;': '"',
+	'&#39;': "'",
+	'&nbsp;': ' ',
+	'&rarr;': '→',
+};
+
+function toPlainText(html: string): string {
+	return html
+		// Tags become spaces, not nothing — '</p><p>' must not fuse adjacent
+		// words; the whitespace collapse below normalizes the spacing.
+		.replace(/<[^>]+>/g, ' ')
+		.replace(/&[a-z0-9#]+;/gi, (entity) => ENTITIES[entity.toLowerCase()] ?? entity)
+		.replace(/\s+/g, ' ')
+		.trim();
+}
+
+export function buildFaqPageSchema(categories: FaqCategory[]) {
+	return {
+		'@context': 'https://schema.org',
+		'@type': 'FAQPage',
+		mainEntity: categories.flatMap((cat) =>
+			cat.items.map((item) => ({
+				'@type': 'Question',
+				name: item.question,
+				acceptedAnswer: {
+					'@type': 'Answer',
+					text: toPlainText(item.answer),
+				},
+			}))
+		),
+	};
+}
+
+// `<` is escaped so hand-edited answer content can never terminate the
+// surrounding `<script type="application/ld+json">` element.
+export function serializeJsonLd(schema: unknown): string {
+	return JSON.stringify(schema).replace(/</g, '\\u003c');
+}

From 7f8142da3b7acd1d26a161520284d2e11fffafa9 Mon Sep 17 00:00:00 2001
From: Vladyslav_Prykhodko <vprykhodko@thingsboard.io>
Date: Tue, 14 Jul 2026 13:51:51 +0300
Subject: [PATCH 2/2] fix(faq): address review feedback on FaqSection refactor

- #4 copy-link is non-interactive (pointer-events:none) until revealed via
  hover/focus, so on fine pointers a tap in the right rail can't silently copy
  a link instead of expanding the row; coarse pointers show it persistently
  (opacity 0.6, interactive) as a visible affordance rather than a hidden trap
- #3 skip scheduling the deep-link idle walk entirely when there's no #hash
  (parity with the removed iot-hub-faq.ts)
- #6 reword the pricing FAQPage JSON-LD comment: it's a one-block-per-page cap,
  not a visibility filter
- #1 extract the duplicated FAQ-row markup into FaqItem.astro, used by both the
  visible and 'Load more' overflow maps so the two can't drift apart
- #5 faq-schema: decode numeric entities generically (decimal + hex), extend
  the named-entity allowlist, and warn at build time on any unrecognized entity
  instead of silently emitting it verbatim
- #2 hoist the .faq-section guard out of every click branch into one check
---
 src/components/Pricing/FaqItem.astro    | 39 ++++++++++
 src/components/Pricing/FaqSection.astro | 99 ++++++++++---------------
 src/pages/pricing/index.astro           | 10 ++-
 src/util/faq-schema.ts                  | 48 +++++++++++-
 4 files changed, 128 insertions(+), 68 deletions(-)
 create mode 100644 src/components/Pricing/FaqItem.astro

diff --git a/src/components/Pricing/FaqItem.astro b/src/components/Pricing/FaqItem.astro
new file mode 100644
index 0000000000..9482b5dde2
--- /dev/null
+++ b/src/components/Pricing/FaqItem.astro
@@ -0,0 +1,39 @@
+---
+import type { FaqItem } from '@data/pricing/types.ts';
+
+// One FAQ row (question toggle + copy-link + collapsible answer). Rendered by
+// FaqSection for both the initially-visible items and the "Load more" overflow;
+// the two differ only by `hidden`, so the markup lives here in one place.
+interface Props {
+	item: FaqItem;
+	/** Part of the "Load more" overflow — hidden until the button reveals it. */
+	hidden?: boolean;
+}
+
+const { item, hidden = false } = Astro.props;
+---
+
+<div class={`faq-item ${hidden ? 'faq-item--hidden' : ''}`} id={item.id}>
+	<div class="faq-question">
+		<h3 class="faq-question-heading">
+			<button
+				type="button"
+				class="faq-question-toggle"
+				aria-expanded="false"
+				aria-controls={`${item.id}-answer`}
+			>{item.question}</button>
+		</h3>
+		<button
+			type="button"
+			class="faq-copy-link"
+			data-faq-id={item.id}
+			aria-label={`Copy link to: ${item.question}`}
+		></button>
+		<span class="faq-chevron" aria-hidden="true"></span>
+	</div>
+	<div class="faq-answer" id={`${item.id}-answer`}>
+		<div class="faq-answer-overflow">
+			<div class="faq-answer-content" set:html={item.answer} />
+		</div>
+	</div>
+</div>
diff --git a/src/components/Pricing/FaqSection.astro b/src/components/Pricing/FaqSection.astro
index ef7fe185ff..f7d93846fe 100644
--- a/src/components/Pricing/FaqSection.astro
+++ b/src/components/Pricing/FaqSection.astro
@@ -1,6 +1,7 @@
 ---
 import type { FaqCategory } from '@data/pricing/types.ts';
 import { buildFaqPageSchema, serializeJsonLd } from '@util/faq-schema';
+import FaqItem from '@components/Pricing/FaqItem.astro';
 
 // Self-contained FAQ section: markup, styles, and behavior (accordion, category
 // tabs, "Load more", copy-link, hash deep-link) all live here. Page scripts may
@@ -51,32 +52,7 @@ const { contextId, categories, visibleCount = 6, analytics = false, jsonLd = fal
 					class={`faq-category-content ${i === 0 ? 'active' : ''}`}
 					data-faq-cat-content={cat.id}
 				>
-					{visible.map((item) => (
-						<div class="faq-item" id={item.id}>
-							<div class="faq-question">
-								<h3 class="faq-question-heading">
-									<button
-										type="button"
-										class="faq-question-toggle"
-										aria-expanded="false"
-										aria-controls={`${item.id}-answer`}
-									>{item.question}</button>
-								</h3>
-								<button
-									type="button"
-									class="faq-copy-link"
-									data-faq-id={item.id}
-									aria-label={`Copy link to: ${item.question}`}
-								></button>
-								<span class="faq-chevron" aria-hidden="true"></span>
-							</div>
-							<div class="faq-answer" id={`${item.id}-answer`}>
-								<div class="faq-answer-overflow">
-									<div class="faq-answer-content" set:html={item.answer} />
-								</div>
-							</div>
-						</div>
-					))}
+					{visible.map((item) => <FaqItem item={item} />)}
 
 					{overflow.length > 0 && (
 						<button type="button" class="faq-load-more">
@@ -84,32 +60,7 @@ const { contextId, categories, visibleCount = 6, analytics = false, jsonLd = fal
 						</button>
 					)}
 
-					{overflow.map((item) => (
-						<div class="faq-item faq-item--hidden" id={item.id}>
-							<div class="faq-question">
-								<h3 class="faq-question-heading">
-									<button
-										type="button"
-										class="faq-question-toggle"
-										aria-expanded="false"
-										aria-controls={`${item.id}-answer`}
-									>{item.question}</button>
-								</h3>
-								<button
-									type="button"
-									class="faq-copy-link"
-									data-faq-id={item.id}
-									aria-label={`Copy link to: ${item.question}`}
-								></button>
-								<span class="faq-chevron" aria-hidden="true"></span>
-							</div>
-							<div class="faq-answer" id={`${item.id}-answer`}>
-								<div class="faq-answer-overflow">
-									<div class="faq-answer-content" set:html={item.answer} />
-								</div>
-							</div>
-						</div>
-					))}
+					{overflow.map((item) => <FaqItem item={item} hidden />)}
 				</div>
 			);
 		})}
@@ -208,16 +159,23 @@ const { contextId, categories, visibleCount = 6, analytics = false, jsonLd = fal
 		if (!(e.target instanceof Element)) return;
 		const target = e.target;
 
+		// Every interactive control below lives inside a `.faq-section`. Enforce
+		// that invariant once here — so no branch has to re-check it, and a
+		// future branch can't forget to (which would let clicks in an unrelated
+		// `.faq-*` implementation leak into this handler).
+		const section = target.closest('.faq-section');
+		if (!section) return;
+
 		const copyLink = target.closest<HTMLElement>('.faq-copy-link');
 		if (copyLink) {
-			if (copyLink.closest('.faq-section')) copyFaqLink(copyLink);
+			copyFaqLink(copyLink);
 			return;
 		}
 
 		const toggle = target.closest<HTMLElement>('.faq-question-toggle');
 		if (toggle) {
 			const item = toggle.closest('.faq-item');
-			if (item && toggle.closest('.faq-section')) {
+			if (item) {
 				const nowExpanded = !item.classList.contains('expanded');
 				setExpanded(item, nowExpanded);
 				// Track opens only (not collapses).
@@ -229,14 +187,13 @@ const { contextId, categories, visibleCount = 6, analytics = false, jsonLd = fal
 		const loadMore = target.closest<HTMLElement>('.faq-load-more');
 		if (loadMore) {
 			const content = loadMore.closest('.faq-category-content');
-			if (content && loadMore.closest('.faq-section')) revealCategoryOverflow(content);
+			if (content) revealCategoryOverflow(content);
 			return;
 		}
 
 		const catTab = target.closest<HTMLElement>('.faq-cat-tab');
 		if (catTab) {
-			const section = catTab.closest('.faq-section');
-			if (section) activateCategoryTab(section, catTab.dataset.faqCat);
+			activateCategoryTab(section, catTab.dataset.faqCat);
 		}
 	});
 
@@ -251,10 +208,14 @@ const { contextId, categories, visibleCount = 6, analytics = false, jsonLd = fal
 		if (item.classList.contains('expanded')) return;
 		openFaqItem(hash);
 	};
-	if ('requestIdleCallback' in window) {
-		requestIdleCallback(performHashWalk, { timeout: 500 });
-	} else {
-		setTimeout(performHashWalk, 200);
+	// Only deep-link visits need the walk at all — skip scheduling (and the
+	// deferred scroll jump) entirely when there's no hash.
+	if (window.location.hash) {
+		if ('requestIdleCallback' in window) {
+			requestIdleCallback(performHashWalk, { timeout: 500 });
+		} else {
+			setTimeout(performHashWalk, 200);
+		}
 	}
 </script>
 
@@ -452,6 +413,12 @@ const { contextId, categories, visibleCount = 6, analytics = false, jsonLd = fal
 		background: none;
 		cursor: pointer;
 		opacity: 0;
+		// Hidden until revealed (hover/focus), and non-interactive while hidden:
+		// it sits above the toggle's hit-area in the right rail, so an invisible
+		// tap target here would silently copy a link the user never sees instead
+		// of expanding the row. Coarse pointers (no hover) get a persistent
+		// visible affordance instead — see the @media (pointer: coarse) block.
+		pointer-events: none;
 		color: var(--color-primary);
 		transition:
 			opacity 0.15s ease,
@@ -471,6 +438,7 @@ const { contextId, categories, visibleCount = 6, analytics = false, jsonLd = fal
 
 		.faq-question:hover & {
 			opacity: 0.6;
+			pointer-events: auto;
 		}
 
 		&:hover {
@@ -479,11 +447,20 @@ const { contextId, categories, visibleCount = 6, analytics = false, jsonLd = fal
 
 		&:focus-visible {
 			opacity: 1;
+			pointer-events: auto;
 			outline: 2px solid currentColor;
 			outline-offset: 2px;
 			border-radius: 2px;
 		}
 
+		// Touch/coarse pointers have no hover to reveal the button, so show it
+		// persistently and keep it interactive. Being visible, it now reads as
+		// its own control rather than an invisible trap beside the chevron.
+		@media (pointer: coarse) {
+			opacity: 0.6;
+			pointer-events: auto;
+		}
+
 		// Tooltip
 		&::after {
 			content: 'Copy link';
diff --git a/src/pages/pricing/index.astro b/src/pages/pricing/index.astro
index b6aa01226a..9f7f6b84fd 100644
--- a/src/pages/pricing/index.astro
+++ b/src/pages/pricing/index.astro
@@ -43,10 +43,12 @@ import cloudIcon from '../../assets/pricing/cloud-icon.svg?raw';
 import pcIcon from '../../assets/pricing/private-cloud-icon.svg?raw';
 import smIcon from '../../assets/pricing/self-icon.svg?raw';
 
-// One FAQPage schema block per page: emit it only for the context that is
-// visible by default (Public Cloud). The other seven contexts stay
-// display:none until a pricing tab reveals them, so marking them up would
-// describe content Google considers absent.
+// Exactly one FAQPage schema block per page — emitted for the default tab's
+// context (Public Cloud). This is a per-page cap, not a visibility filter: the
+// emitted block intentionally includes items behind inactive category tabs and
+// "Load more" (also display:none at load, both click-reachable). Don't "fix"
+// this by adding the other seven product contexts, nor by trimming to the
+// first category's visible items.
 const FAQ_JSONLD_CONTEXT = 'thingsboard-cloud';
 
 // Build a faqId → answer lookup from all FAQ data (strip HTML, truncate for tooltip)
diff --git a/src/util/faq-schema.ts b/src/util/faq-schema.ts
index 1078f6c731..e39cee10df 100644
--- a/src/util/faq-schema.ts
+++ b/src/util/faq-schema.ts
@@ -5,22 +5,64 @@ import type { FaqCategory } from '@data/pricing/types';
 // Answers are HTML strings; the schema wants plain text. Entities are decoded
 // because `<script>` raw text is never entity-decoded by the browser — a
 // literal `&rarr;` would otherwise surface verbatim in search results.
-const ENTITIES: Record<string, string> = {
+// Named entities beyond HTML's five predefined ones have no algorithmic
+// mapping, so the common ones authors reach for are listed here; anything else
+// is flagged at build time (see `decodeEntity`) rather than passed through.
+const NAMED_ENTITIES: Record<string, string> = {
 	'&amp;': '&',
 	'&lt;': '<',
 	'&gt;': '>',
 	'&quot;': '"',
-	'&#39;': "'",
+	'&apos;': "'",
 	'&nbsp;': ' ',
 	'&rarr;': '→',
+	'&larr;': '←',
+	'&mdash;': '—',
+	'&ndash;': '–',
+	'&hellip;': '…',
+	'&trade;': '™',
+	'&copy;': '©',
+	'&reg;': '®',
+	'&times;': '×',
+	'&deg;': '°',
 };
 
+function fromCodePoint(cp: number): string | null {
+	// Reject NaN and out-of-range values that would make String.fromCodePoint
+	// throw; surrogate halves (0xD800–0xDFFF) are technically invalid too but
+	// harmless as a lone char, so we don't special-case them.
+	return Number.isInteger(cp) && cp >= 0 && cp <= 0x10ffff ? String.fromCodePoint(cp) : null;
+}
+
+// Decode a single HTML entity to its character. Numeric entities decode
+// generically; named entities use the allowlist above. Unknown entities are
+// left verbatim AND logged, turning a silent structured-data bug into a
+// visible build warning.
+function decodeEntity(entity: string): string {
+	const lower = entity.toLowerCase();
+
+	// Numeric: &#8594; (decimal) or &#x2192; (hex).
+	const numeric = /^&#(x)?([0-9a-f]+);$/i.exec(entity);
+	if (numeric) {
+		const cp = parseInt(numeric[2], numeric[1] ? 16 : 10);
+		const char = fromCodePoint(cp);
+		if (char !== null) return char;
+	} else if (lower in NAMED_ENTITIES) {
+		return NAMED_ENTITIES[lower];
+	}
+
+	console.warn(
+		`[faq-schema] Unrecognized HTML entity "${entity}" in a FAQ answer — it will appear verbatim in the FAQPage structured data. Add it to NAMED_ENTITIES in src/util/faq-schema.ts.`
+	);
+	return entity;
+}
+
 function toPlainText(html: string): string {
 	return html
 		// Tags become spaces, not nothing — '</p><p>' must not fuse adjacent
 		// words; the whitespace collapse below normalizes the spacing.
 		.replace(/<[^>]+>/g, ' ')
-		.replace(/&[a-z0-9#]+;/gi, (entity) => ENTITIES[entity.toLowerCase()] ?? entity)
+		.replace(/&#?[a-z0-9]+;/gi, decodeEntity)
 		.replace(/\s+/g, ' ')
 		.trim();
 }