@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/faq/project/src/pages/faq.astro

@@ -0,0 +1,39 @@
+---
+// FAQ page — data fetched SERVER-SIDE (SEO: every question and answer is in the HTML, collapsed) and
+// handed to the islands as DTO props. Keep this frontmatter (the fetch, the JSON-LD, the category
+// pre-selection); swap the island imports to YOUR components. The three islands share one module-scope
+// store, so they can stay separate or be merged into one — your call.
+import SiteLayout from "../layouts/SiteLayout.astro";
+import FaqSearch from "../components/faq/FaqSearch";
+import FaqCategoryNav from "../components/faq/FaqCategoryNav";
+import FaqAccordion from "../components/faq/FaqAccordion";
+import { fetchFaq } from "../wix/faq/faq";
+import { faqJsonLd, parseDeepLink } from "../wix/faq/faq-core";
+import type { FaqData } from "../wix/faq/types";
+
+let data: FaqData = { categories: [], questions: [], truncated: false };
+try {
+  data = await fetchFaq();
+} catch {
+  // An unguarded SSR throw truncates the response mid-stream; the islands render the empty state instead.
+}
+
+// Behind Wix's proxy the request URL is internal — the public page URL arrives on x-wix-forwarded-url.
+const forwarded = Astro.request.headers.get("x-wix-forwarded-url");
+const pageUrl =
+  forwarded && URL.canParse(forwarded) && /^https?:$/.test(new URL(forwarded).protocol) ? forwarded : Astro.url.href;
+// `?category=` is server-visible (pre-select the nav so SSR and the first paint agree); `#q-…` is not — the store applies it in the browser.
+const { categoryId } = parseDeepLink(Astro.url.search, "");
+const initialCategoryId = categoryId && data.categories.some((c) => c.id === categoryId) ? categoryId : null;
+// The whole FAQ, not the filtered view: every marked-up answer is on the page (collapsed panels are still in the DOM).
+const jsonLd = JSON.stringify(faqJsonLd(data.questions, pageUrl.split("#")[0].split("?")[0])).replace(/</g, "\\u003c");
+const description = data.questions.slice(0, 3).map((q) => q.question).join(" · ");
+---
+
+<SiteLayout title="FAQ" description={description}>
+  <script type="application/ld+json" is:inline slot="seo-tags" set:html={jsonLd} />
+  <h1 class="mb-8 text-3xl font-semibold tracking-tight">Frequently asked questions</h1>
+  <FaqSearch client:load initialData={data} initialCategoryId={initialCategoryId} />
+  <FaqCategoryNav client:load initialData={data} initialCategoryId={initialCategoryId} />
+  <FaqAccordion client:load initialData={data} initialCategoryId={initialCategoryId} />
+</SiteLayout>

package/skills/wix-headless-templates/faq/project/src/pages/index.astro

@@ -0,0 +1,8 @@
+---
+import Hero from '../components/Hero.astro';
+import Layout from '../layouts/Layout.astro';
+---
+
+<Layout>
+	<Hero />
+</Layout>

package/skills/wix-headless-templates/faq/project/src/styles/global.css

@@ -0,0 +1,57 @@
+@import url('https://fonts.googleapis.com/css2?family=Wix+Madefor+Text:wght@400;500;600;700;800&display=swap');
+@import 'tailwindcss';
+
+/* ─── THE design system ─────────────────────────────────────────────────────────────────
+   Theme the entire store by editing THIS @theme block (same token family as the official
+   Wix headless templates). Every shipped component styles itself from these via Tailwind
+   utilities (bg-primary, text-muted-foreground, text-destructive, rounded-lg, …) — change a token, everything
+   follows. A dark theme is just flipped values (dark background/foreground, adjusted
+   secondary/border). Don't restyle shipped component markup; restyle the tokens.
+
+   Choosing values: argue polarity from the business — light is not "cheap" (wellness/food
+   usually read better light); never dark-by-default for "premium". Palette: one dominant +
+   accents from ADJACENT hues (~30° arc), 2-4 colors total. Every background/foreground pair
+   you set must hit WCAG 4.5:1 (3:1 for text ≥24px); body copy never below 16px/1.5. Derive
+   from THIS brand — a look repeated across projects is a failure, not a shortcut. The user's
+   explicit direction beats all of this except the contrast floor. */
+@theme {
+  --color-background: hsl(0 0% 100%);
+  --color-foreground: hsl(230 24% 14%);
+  --color-primary: hsl(230 24% 14%);
+  --color-primary-foreground: hsl(0 0% 100%);
+  --color-secondary: hsl(228 24% 96%);
+  --color-secondary-foreground: hsl(230 24% 14%);
+  --color-muted-foreground: hsl(228 8% 46%);
+  --color-border: hsl(220 14% 90%);
+  --color-destructive: hsl(0 72% 51%);
+
+  --radius-lg: 12px;
+  --radius-md: 8px;
+  --radius-sm: 6px;
+  /* Buttons, chips, labels, steppers and the progress bar. Follows --radius-md unless the brand
+     wants otherwise: 9999px is the pill, 0 is square. Genuine circles (swatches, avatars, dots)
+     stay rounded-full and do not read this. */
+  --radius-control: var(--radius-md);
+
+  --font-sans: 'Wix Madefor Text', system-ui, sans-serif;
+}
+
+@layer base {
+  body {
+    background-color: var(--color-background);
+    color: var(--color-foreground);
+    font-family: var(--font-sans);
+    -webkit-font-smoothing: antialiased;
+    font-feature-settings: 'cv02', 'cv03', 'cv04', 'cv11';
+  }
+}
+
+@layer utilities {
+  .eyebrow {
+    font-size: 0.8125rem;
+    font-weight: 600;
+    letter-spacing: 0.1em;
+    text-transform: uppercase;
+    color: var(--color-muted-foreground);
+  }
+}

package/skills/wix-headless-templates/faq/project/src/wix/config.ts

@@ -0,0 +1,16 @@
+// Wix connection config — written by the skill's deploy step (install/deploy.mjs).
+//
+// WIX_CLIENT_ID = null  → ambient auth (a Wix-managed Astro project: `@wix/astro` authenticates
+//                         every SDK call automatically; there is no client and nothing to set).
+// WIX_CLIENT_ID = "..." → manual visitor client (any other React setup): the public OAuth client id.
+//                         It is NOT a secret — it only mints anonymous visitor tokens — so
+//                         hardcoding and committing it is fine. deploy.mjs copies it from `.env.local`
+//                         (`WIX_CLIENT_ID`, what `wix env pull` writes): the CONTENT site's app — on a
+//                         migration preview the site being migrated, while wix.config.json names
+//                         only the deploy target.
+export const WIX_CLIENT_ID: string | null = null;
+
+// Kept for projects deployed before the Members vertical moved onto the shared seam; the shipped
+// members code no longer reads it (ambient Astro uses the built-in /api/auth routes, manual mode
+// uses the shared client above). deploy.mjs still fills it so older code keeps compiling.
+export const WIX_MEMBERS_CLIENT_ID: string | null = null;

package/skills/wix-headless-templates/faq/project/src/wix/faq/faq-core.ts

@@ -0,0 +1,428 @@
+// FAQ rules and DTO mapping — transport-agnostic, imported by BOTH transports: ./faq.ts (the SDK,
+// managed Astro and React) and the REST twin in templates/faq/rest/faq.ts (fetch, a static site or a
+// port to another language). Every rule about ordering, grouping, search, deep links, the answer's
+// Ricos-to-HTML rendering, the FAQPage structured data, and the wire spelling of a query lives HERE,
+// once. A raw entity may come from the SDK (`_id`) or from REST (`id`); the mappers accept both.
+// Imports are type-only so a strip to JS emits no imports.
+import type { FaqCategory, FaqData, FaqQuestion, FaqQuestionPage, FaqSection, FetchQuestionsOptions } from "./types";
+
+/** A raw FAQ entity (Category, QuestionEntry) as either transport returns it. */
+export type Raw = Record<string, any>;
+/** Media value + size → https URL. Injected: the SDK transport scales through @wix/sdk, REST through the URL form. */
+export type ImgSrc = (value: any, width: number, height: number) => string;
+
+/** The Wix FAQ app id — what the seed installs and read-site.mjs checks for. */
+export const FAQ_APP_ID = "14c92d28-031e-7910-c9a8-a670011e062d";
+/** The API's page cap: CursorPaging.limit is at most 100 on both services. */
+export const PAGE_LIMIT = 100;
+/** fetchFaq stops after this many questions and sets `truncated` — a guard, not a feature (an FAQ is small). */
+export const MAX_QUESTIONS = 500;
+/** Ask for the Ricos answer (the format the Wix dashboard writes) and the share links (only returned when asked). */
+export const CONTENT_FORMAT = "RICH_CONTENT" as const;
+export const FIELD_SET = ["SHARE_LINKS"] as const;
+/** Owner order for categories AND questions: "lower sort order values appear first" (both entities). */
+export const SORT = [{ fieldName: "sortOrder", order: "ASC" }] as const;
+/** Size an answer's inline image is resolved at — one URL per image, wide enough for a prose column. */
+export const ANSWER_IMAGE_WIDTH = 1200;
+export const ANSWER_IMAGE_HEIGHT = 800;
+/** The synthetic section for a question whose categoryId matches no loaded category. */
+export const OTHER_CATEGORY_ID = "uncategorized";
+export const OTHER_CATEGORY_TITLE = "Other";
+
+export const rawId = (r: Raw | null | undefined): string => r?._id ?? r?.id ?? "";
+
+const numberOrNull = (v: unknown): number | null => (typeof v === "number" && Number.isFinite(v) ? v : null);
+
+// ---- DTO mapping --------------------------------------------------------------------------------
+
+export function toCategory(raw: Raw): FaqCategory {
+  return { id: rawId(raw), title: raw.title ?? "", sortOrder: numberOrNull(raw.sortOrder), questionCount: 0 };
+}
+
+/**
+ * The answer is a oneof — richContent | plainText | draftjs — and the request's `contentFormat`
+ * decides which one the response carries. Priority here: richContent (what we ask for), then
+ * plainText, then a minimal Draft.js read (legacy content; the request never asks for DRAFTJS, but a
+ * conversion the backend declines could still arrive that way), then an empty answer.
+ */
+export function toQuestion(raw: Raw, imgSrc: ImgSrc): FaqQuestion {
+  let answerHtml = "";
+  let answerText = "";
+  if (raw.richContent?.nodes) {
+    answerHtml = richContentToHtml(raw.richContent, imgSrc);
+    answerText = richContentToText(raw.richContent);
+  } else if (typeof raw.plainText === "string" && raw.plainText) {
+    answerHtml = plainTextToHtml(raw.plainText);
+    answerText = raw.plainText.trim();
+  } else if (typeof raw.draftjs === "string" && raw.draftjs) {
+    const blocks = draftjsBlocks(raw.draftjs);
+    answerHtml = draftjsToHtml(blocks);
+    answerText = blocks.map((b) => b.text).join("\n").trim();
+  }
+  return {
+    id: rawId(raw),
+    slug: raw.slug ?? "",
+    question: raw.question ?? "",
+    answerHtml,
+    answerText,
+    categoryId: raw.categoryId ?? "",
+    sortOrder: numberOrNull(raw.sortOrder),
+    shareLink: raw.shareLink ?? "",
+    labels: Array.isArray(raw.labels) ? raw.labels.map((l: Raw) => l?.title ?? "").filter(Boolean) : [],
+  };
+}
+
+// ---- ordering and grouping -------------------------------------------------------------------------
+
+const bySortOrder = (a: number | null, b: number | null): number => {
+  if (a === null && b === null) return 0;
+  if (a === null) return 1; // unnumbered after the numbered ones
+  if (b === null) return -1;
+  return a - b;
+};
+
+/** sortOrder ascending, nulls last, then title — a stable order whatever the API returned. */
+export function sortCategories(cs: FaqCategory[]): FaqCategory[] {
+  return [...cs].sort((a, b) => bySortOrder(a.sortOrder, b.sortOrder) || a.title.localeCompare(b.title));
+}
+
+/** sortOrder ascending, nulls last, then question text. */
+export function sortQuestions(qs: FaqQuestion[]): FaqQuestion[] {
+  return [...qs].sort((a, b) => bySortOrder(a.sortOrder, b.sortOrder) || a.question.localeCompare(b.question));
+}
+
+/** Categories with `questionCount` filled from ALL loaded questions (not the filtered view). */
+export function withCounts(cats: FaqCategory[], qs: FaqQuestion[]): FaqCategory[] {
+  const counts = new Map<string, number>();
+  for (const q of qs) counts.set(q.categoryId, (counts.get(q.categoryId) ?? 0) + 1);
+  return cats.map((c) => ({ ...c, questionCount: counts.get(c.id) ?? 0 }));
+}
+
+/**
+ * Sections in category order, each with its questions in owner order; categories with no question
+ * in `qs` are omitted. A question whose categoryId matches no category lands in a synthetic "Other"
+ * section at the end (every question must have a category, so this is a stale-reference guard).
+ */
+export function groupByCategory(cats: FaqCategory[], qs: FaqQuestion[]): FaqSection[] {
+  const buckets = new Map<string, FaqQuestion[]>();
+  for (const q of qs) {
+    const list = buckets.get(q.categoryId) ?? [];
+    list.push(q);
+    buckets.set(q.categoryId, list);
+  }
+  const sections: FaqSection[] = [];
+  for (const c of sortCategories(cats)) {
+    const list = buckets.get(c.id);
+    if (list?.length) sections.push({ category: { ...c, questionCount: list.length }, questions: sortQuestions(list) });
+    buckets.delete(c.id);
+  }
+  const orphans = [...buckets.values()].flat();
+  if (orphans.length) {
+    sections.push({
+      category: { id: OTHER_CATEGORY_ID, title: OTHER_CATEGORY_TITLE, sortOrder: null, questionCount: orphans.length },
+      questions: sortQuestions(orphans),
+    });
+  }
+  return sections;
+}
+
+/** Categories (sorted, counted) + questions (sorted) → the page's data unit. Both transports end here. */
+export function assembleFaq(cats: FaqCategory[], qs: FaqQuestion[], truncated: boolean): FaqData {
+  const questions = sortQuestions(qs);
+  return { categories: sortCategories(withCounts(cats, questions)), questions, truncated };
+}
+
+/**
+ * Every question, paged until the API says there is no next page or MAX_QUESTIONS is reached. Takes
+ * the transport's fetchQuestions so the drain rule lives once; `truncated` says the cap was hit.
+ */
+export async function loadAllQuestions(
+  fetchPage: (o: FetchQuestionsOptions) => Promise<FaqQuestionPage>,
+): Promise<{ questions: FaqQuestion[]; truncated: boolean }> {
+  const questions: FaqQuestion[] = [];
+  let cursor: string | null = null;
+  do {
+    const page: FaqQuestionPage = await fetchPage({ limit: PAGE_LIMIT, cursor });
+    questions.push(...page.questions);
+    cursor = page.nextCursor;
+    if (cursor && questions.length >= MAX_QUESTIONS) return { questions: questions.slice(0, MAX_QUESTIONS), truncated: true };
+  } while (cursor);
+  return { questions, truncated: false };
+}
+
+// ---- search (client-side by design) -----------------------------------------------------------------
+// The API filters `question` with $startsWith only (the query spec: no $contains, no full-text), so
+// visitor search is a substring match over the loaded set — question AND answer text, case-insensitive
+// — the rule the Wix FAQ widget applies. Never re-implement it against the API.
+
+/** Trim, lowercase, collapse whitespace. */
+export const normalizeQuery = (q: string): string => q.trim().toLowerCase().replace(/\s+/g, " ");
+
+export function matches(q: FaqQuestion, needle: string): boolean {
+  if (!needle) return true;
+  return normalizeQuery(q.question).includes(needle) || normalizeQuery(q.answerText).includes(needle);
+}
+
+/** "" → qs unchanged. */
+export function search(qs: FaqQuestion[], query: string): FaqQuestion[] {
+  const needle = normalizeQuery(query);
+  return needle ? qs.filter((q) => matches(q, needle)) : qs;
+}
+
+/** Category filter first, then search; sorted. What the accordion renders. */
+export function visibleQuestions(data: FaqData | null, activeCategoryId: string | null, query: string): FaqQuestion[] {
+  if (!data) return [];
+  const inCategory = activeCategoryId ? data.questions.filter((q) => q.categoryId === activeCategoryId) : data.questions;
+  return sortQuestions(search(inCategory, query));
+}
+
+// ---- deep links -----------------------------------------------------------------------------------------
+// `/faq?category=<id>#q-<slug>`: the category pre-selects the nav, the fragment expands one question. The
+// slug is the API's readonly slug; the id is the fallback so a question without one still has an anchor.
+
+export const anchorId = (q: Pick<FaqQuestion, "slug" | "id">): string => `q-${q.slug || q.id}`;
+
+export function faqDeepLink(q: Pick<FaqQuestion, "slug" | "id">, base = "/faq", categoryId?: string | null): string {
+  return `${base}${categoryId ? `?category=${encodeURIComponent(categoryId)}` : ""}#${anchorId(q)}`;
+}
+
+/** location.search + location.hash → the deep link's parts (either null when absent). */
+export function parseDeepLink(search: string, hash: string): { categoryId: string | null; anchor: string | null } {
+  let categoryId: string | null = null;
+  try {
+    categoryId = new URLSearchParams(search).get("category") || null;
+  } catch {
+    /* malformed query string — no category */
+  }
+  const h = hash.startsWith("#") ? hash.slice(1) : hash;
+  let anchor: string | null = null;
+  if (h.startsWith("q-") && h.length > 2) {
+    try {
+      anchor = decodeURIComponent(h.slice(2));
+    } catch {
+      anchor = h.slice(2);
+    }
+  }
+  return { categoryId, anchor };
+}
+
+/** The question an anchor names — by slug, then by id (a slug can change when the question is edited). */
+export function findByAnchor(qs: FaqQuestion[], anchor: string): FaqQuestion | undefined {
+  return qs.find((q) => q.slug && q.slug === anchor) ?? qs.find((q) => q.id === anchor);
+}
+
+// ---- structured data ----------------------------------------------------------------------------------
+
+/** schema.org FAQPage over the questions. Answer.text carries the sanitized HTML (Google accepts limited HTML there). */
+export function faqJsonLd(qs: FaqQuestion[], pageUrl?: string): Record<string, unknown> {
+  return {
+    "@context": "https://schema.org",
+    "@type": "FAQPage",
+    mainEntity: qs.map((q) => ({
+      "@type": "Question",
+      name: q.question,
+      ...(pageUrl ? { url: `${pageUrl}#${anchorId(q)}` } : {}),
+      acceptedAnswer: { "@type": "Answer", text: q.answerHtml },
+    })),
+  };
+}
+
+// ---- Ricos → HTML / text --------------------------------------------------------------------------------
+// The subset FAQ answers use. Text is always escaped, attribute values are escaped, no inline styles, no
+// event attributes; a node type outside the table degrades to its text; `htmlData` is never emitted.
+
+export function escapeHtml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+
+const isHttpUrl = (u: unknown): u is string => typeof u === "string" && /^https?:\/\//i.test(u);
+
+/** Ricos Link → the anchor's attributes, or null when the URL is not http(s) (javascript:, data:, relative). */
+function linkAttrs(link: Raw | undefined): string | null {
+  if (!link) return null;
+  if (isHttpUrl(link.url)) {
+    const rel = ["noopener", "noreferrer"];
+    if (link.rel?.nofollow) rel.push("nofollow");
+    if (link.rel?.sponsored) rel.push("sponsored");
+    if (link.rel?.ugc) rel.push("ugc");
+    const target = link.target === "BLANK" ? ` target="_blank"` : "";
+    return `href="${escapeHtml(link.url)}" rel="${rel.join(" ")}"${target}`;
+  }
+  if (typeof link.anchor === "string" && link.anchor) return `href="#${escapeHtml(link.anchor)}"`;
+  return null;
+}
+
+/** One TEXT node → inline HTML: escaped text wrapped by its decorations (unknown decorations keep the text). */
+function textNodeToHtml(node: Raw): string {
+  let html = escapeHtml(String(node.textData?.text ?? ""));
+  for (const d of (node.textData?.decorations ?? []) as Raw[]) {
+    switch (d?.type) {
+      case "BOLD":
+        // The editor writes fontWeightValue 700 for bold and a lighter weight to un-bold inside a bold block.
+        if (typeof d.fontWeightValue !== "number" || d.fontWeightValue >= 600) html = `<strong>${html}</strong>`;
+        break;
+      case "ITALIC":
+        if (d.italicData !== false) html = `<em>${html}</em>`;
+        break;
+      case "UNDERLINE": html = `<u>${html}</u>`; break;
+      case "STRIKETHROUGH": html = `<s>${html}</s>`; break;
+      case "SUPERSCRIPT": html = `<sup>${html}</sup>`; break;
+      case "SUBSCRIPT": html = `<sub>${html}</sub>`; break;
+      case "LINK": {
+        const attrs = linkAttrs(d.linkData?.link);
+        if (attrs) html = `<a ${attrs}>${html}</a>`;
+        break;
+      }
+      case "ANCHOR":
+        if (typeof d.anchorData?.anchor === "string" && d.anchorData.anchor) html = `<a href="#${escapeHtml(d.anchorData.anchor)}">${html}</a>`;
+        break;
+      default:
+        break; // COLOR, FONT_SIZE, FONT_FAMILY, MENTION, SPOILER, SKETCH, EXTERNAL — text kept, styling dropped
+    }
+  }
+  return html;
+}
+
+/**
+ * The media value in the form imgSrc scales: `wix:image://v1/<id>/<id>#originWidth=W&originHeight=H`
+ * (the Ricos FileSource has no filename; the id stands in — the scaler reads only the id). An absolute
+ * https URL passes through; anything else is no image.
+ */
+export function imageValue(image: Raw | undefined): string {
+  const src = image?.src;
+  if (!src) return "";
+  if (typeof src.id === "string" && src.id) {
+    const size = image?.width && image?.height ? `#originWidth=${image.width}&originHeight=${image.height}` : "";
+    return `wix:image://v1/${src.id}/${src.id}${size}`;
+  }
+  return isHttpUrl(src.url) ? src.url : "";
+}
+
+function childrenToHtml(node: Raw, imgSrc: ImgSrc): string {
+  return ((node.nodes ?? []) as Raw[]).map((n) => nodeToHtml(n, imgSrc)).join("");
+}
+
+function nodeToHtml(node: Raw, imgSrc: ImgSrc): string {
+  switch (node?.type) {
+    case "TEXT": return textNodeToHtml(node);
+    case "PARAGRAPH": return `<p>${childrenToHtml(node, imgSrc)}</p>`;
+    // Every answer heading renders as h4: the page's h1 is the FAQ title, h2 the category, h3 the question.
+    case "HEADING": return `<h4>${childrenToHtml(node, imgSrc)}</h4>`;
+    case "BULLETED_LIST": return `<ul>${childrenToHtml(node, imgSrc)}</ul>`;
+    case "ORDERED_LIST": return `<ol>${childrenToHtml(node, imgSrc)}</ol>`;
+    case "LIST_ITEM": return `<li>${childrenToHtml(node, imgSrc)}</li>`;
+    case "BLOCKQUOTE": return `<blockquote>${childrenToHtml(node, imgSrc)}</blockquote>`;
+    case "CODE_BLOCK": return `<pre><code>${childrenToHtml(node, imgSrc)}</code></pre>`;
+    case "DIVIDER": return "<hr>";
+    case "IMAGE": {
+      const src = imgSrc(imageValue(node.imageData?.image), ANSWER_IMAGE_WIDTH, ANSWER_IMAGE_HEIGHT);
+      if (!src) return "";
+      const alt = escapeHtml(String(node.imageData?.altText ?? ""));
+      const img = `<img src="${escapeHtml(src)}" alt="${alt}" loading="lazy" decoding="async">`;
+      const attrs = linkAttrs(node.imageData?.link);
+      return attrs ? `<a ${attrs}>${img}</a>` : img;
+    }
+    default: {
+      // TABLE, COLLAPSIBLE_LIST, VIDEO, GIF, GALLERY, HTML, EMBED, APP_EMBED, BUTTON, … — text only.
+      const text = nodeToText(node).trim();
+      return text ? `<p>${escapeHtml(text)}</p>` : "";
+    }
+  }
+}
+
+/** Sanitized HTML for a Ricos document ("" for none). */
+export function richContentToHtml(rc: Raw | null | undefined, imgSrc: ImgSrc): string {
+  return ((rc?.nodes ?? []) as Raw[]).map((n) => nodeToHtml(n, imgSrc)).join("");
+}
+
+const INLINE_TYPES = new Set(["TEXT"]);
+
+function nodeToText(node: Raw): string {
+  if (node?.type === "TEXT") return String(node.textData?.text ?? "");
+  if (node?.type === "BUTTON") return String(node.buttonData?.text ?? "");
+  const children = (node?.nodes ?? []) as Raw[];
+  const parts = children.map(nodeToText);
+  // Blocks join with newlines; inline runs concatenate.
+  return children.every((c) => INLINE_TYPES.has(c?.type)) ? parts.join("") : parts.filter(Boolean).join("\n");
+}
+
+/** Plain text of a Ricos document — one line per block ("" for none). */
+export function richContentToText(rc: Raw | null | undefined): string {
+  return ((rc?.nodes ?? []) as Raw[]).map(nodeToText).filter(Boolean).join("\n").trim();
+}
+
+/** A plainText answer → one <p> per blank-line paragraph, single newlines as <br>. */
+export function plainTextToHtml(text: string): string {
+  return text
+    .trim()
+    .split(/\n\s*\n/)
+    .map((p) => p.trim())
+    .filter(Boolean)
+    .map((p) => `<p>${escapeHtml(p).replace(/\n/g, "<br>")}</p>`)
+    .join("");
+}
+
+// ---- Draft.js (legacy answers) — a minimal read: block text and block type, no inline styles or entities.
+interface DraftBlock { text: string; type: string }
+
+/** The `blocks[]` of a Draft.js raw content string; [] when it is not one. */
+export function draftjsBlocks(raw: string): DraftBlock[] {
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed?.blocks)
+      ? parsed.blocks.map((b: Raw) => ({ text: String(b?.text ?? ""), type: String(b?.type ?? "unstyled") }))
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+export function draftjsToHtml(blocks: DraftBlock[]): string {
+  let html = "";
+  let openList: "ul" | "ol" | null = null;
+  const closeList = () => { if (openList) { html += `</${openList}>`; openList = null; } };
+  for (const b of blocks) {
+    const text = escapeHtml(b.text);
+    const list = b.type === "unordered-list-item" ? "ul" : b.type === "ordered-list-item" ? "ol" : null;
+    if (list) {
+      if (openList !== list) { closeList(); html += `<${list}>`; openList = list; }
+      html += `<li>${text}</li>`;
+      continue;
+    }
+    closeList();
+    if (!b.text.trim()) continue;
+    if (b.type.startsWith("header-")) html += `<h4>${text}</h4>`;
+    else if (b.type === "blockquote") html += `<blockquote><p>${text}</p></blockquote>`;
+    else if (b.type === "code-block") html += `<pre><code>${text}</code></pre>`;
+    else html += `<p>${text}</p>`;
+  }
+  closeList();
+  return html;
+}
+
+// ---- the REST spelling of a query -------------------------------------------------------------------
+// The SDK's query builder serializes these itself; the REST twin sends them literally. A cursor encodes
+// the original filter+sort, so a cursor request carries ONLY cursorPaging; the first page carries the
+// sort and the filter. contentFormat and fieldSet sit beside `query`, not inside it.
+
+/** POST /faq/v2/categories/query body: every category, owner order, one page (a site has few). */
+export function categoriesQueryBody(): Raw {
+  return { query: { sort: SORT, cursorPaging: { limit: PAGE_LIMIT } } };
+}
+
+/** POST /faq/v2/question-entries/query body for one page. */
+export function questionsQueryBody({ categoryId = null, limit = PAGE_LIMIT, cursor = null }: FetchQuestionsOptions = {}): Raw {
+  const size = Math.min(Math.max(1, limit), PAGE_LIMIT);
+  const query: Raw = cursor
+    ? { cursorPaging: { limit: size, cursor } }
+    : { ...(categoryId ? { filter: { categoryId: { $eq: categoryId } } } : {}), sort: SORT, cursorPaging: { limit: size } };
+  return { query, contentFormat: CONTENT_FORMAT, fieldSet: [...FIELD_SET] };
+}
+
+/** POST /faq/v2/question-entries/query body for one question by id — the same read (and permission) as the page. */
+export function questionByIdBody(id: string): Raw {
+  return { query: { filter: { _id: { $eq: id } }, cursorPaging: { limit: 1 } }, contentFormat: CONTENT_FORMAT, fieldSet: [...FIELD_SET] };
+}
+
+/** `pagingMetadata` → the next cursor, or null when the response says there is no next page. */
+export const nextCursor = (pm: Raw | undefined | null): string | null => (pm?.hasNext ? pm.cursors?.next ?? null : null);