@bettercms-ai/richtext 0.12.1 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/richtext",
-  "version": "0.12.1",
+  "version": "0.16.0",
   "type": "module",
   "sideEffects": false,
   "description": "The one Portable Text contract for BetterCMS: schema, converters, and rendering. Shared by the backend, the dashboard and every delivery SDK.",
@@ -26,11 +26,14 @@
     "test:watch": "vitest"
   },
   "dependencies": {
+    "@bettercms-ai/image-url": "^0.4.1",
+    "@bettercms-ai/types": "^1.57.0",
     "@portabletext/to-html": "^6.0.0",
     "@portabletext/html": "^2.0.0",
     "@portabletext/schema": "^3.0.0"
   },
   "devDependencies": {
+    "fast-check": "^4.10.2",
     "tsup": "^8.5.1",
     "vitest": "^4.1.4"
   },

package/src/accept.ts

@@ -1,3 +1,11 @@
+import {
+  RICHTEXT_ADVANCED_ELEMENTS,
+  RICHTEXT_BLOCK_ELEMENTS,
+  RICHTEXT_CORE_ELEMENTS,
+  RICHTEXT_ELEMENTS,
+  normaliseRichTextFeatures,
+  type RichTextFeature as FeatureName,
+} from '@bettercms-ai/types'
 import { RICH_TEXT_CAPABILITY_MANIFEST, type RichTextFeature } from './features'
 import type { AllowEntry } from './features'
 import { STYLED_TAGS } from './styled'
@@ -12,21 +20,23 @@ import { STYLED_TAGS } from './styled'
  * moment content arrives by paste, from the AI hook, or from before the list was narrowed.
  */
 
-/** The elements Prismic exposes — the default-visible set. */
-export const CORE_ELEMENTS = [
-  'p', 'pre', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
-  'b', 'i', 'link', 'image', 'code', 'ul', 'ol', 'rtl',
-] as const
+/** The elements Prismic exposes — the default-visible set. (Names: @bettercms-ai/types.) */
+export const CORE_ELEMENTS = RICHTEXT_CORE_ELEMENTS
 
 /**
  * What this repo can do beyond Prismic. Behind "Advanced" so the panel reads like the spec at
  * rest, but present so enabling them is not a capability deletion.
  */
-export const ADVANCED_ELEMENTS = [
-  'u', 'mark', 's', 'checklist', 'table', 'columns', 'embed', 'internalLink',
-] as const
+export const ADVANCED_ELEMENTS = RICHTEXT_ADVANCED_ELEMENTS
 
-export const ALL_ELEMENTS = [...CORE_ELEMENTS, ...ADVANCED_ELEMENTS] as const
+/**
+ * The V2 blocks' elements (RT2–RT8). Each one has its Portable Text type, both renderers, the
+ * ingest and the write check, so each is in the panel, the defaults and the sanitiser like any
+ * other capability.
+ */
+export const BLOCK_ELEMENTS = RICHTEXT_BLOCK_ELEMENTS
+
+export const ALL_ELEMENTS = RICHTEXT_ELEMENTS
 export type AcceptElement = (typeof ALL_ELEMENTS)[number]
 
 /** Labels name the CAPABILITY, never the key — an author reads "Headings", not `accept.h1`. */
@@ -37,6 +47,8 @@ export const ELEMENT_LABELS: Record<AcceptElement, string> = {
   ul: 'Bulleted list', ol: 'Numbered list', rtl: 'Right-to-left',
   u: 'Underline', mark: 'Highlight', s: 'Strikethrough', checklist: 'Checklist',
   table: 'Table', columns: 'Columns', embed: 'Video embed', internalLink: 'Internal link',
+  gallery: 'Gallery', providerEmbed: 'Embed', tableOfContents: 'Table of contents', relatedPosts: 'Related posts',
+  authorBio: 'Author bio', footnotes: 'Footnotes', button: 'Button',
 }
 
 /**
@@ -49,6 +61,8 @@ export const ELEMENT_GROUPS: { id: string; label: string; elements: AcceptElemen
   // `internalLink` stays in ALL_ELEMENTS for stored-config compatibility, but is intentionally
   // absent here: new authoring uses the ordinary URL Link until a real internal-entry contract exists.
   { id: 'insert', label: 'Insert', elements: ['link', 'image', 'table', 'columns', 'embed', 'checklist'] },
+  // The V2 article blocks (RT2–RT8), each with its type, renderers, ingest and write check.
+  { id: 'blocks', label: 'Article blocks', elements: ['button', 'providerEmbed', 'gallery', 'tableOfContents', 'footnotes', 'relatedPosts', 'authorBio'] },
   // `rtl` stays in ALL_ELEMENTS for stored-config compatibility. There is no editor command
   // for it yet, so new schema authoring must not advertise an inert toggle.
 ]
@@ -76,6 +90,22 @@ const ELEMENT_TAGS: Record<AcceptElement, string[]> = {
   checklist: ['ul', 'li', 'input'], table: ['table', 'thead', 'tbody', 'tr', 'th', 'td'],
   columns: ['section', 'div', 'p', 'br'],
   embed: ['figure', 'iframe', 'video', 'source', 'figcaption'],
+  // Each V2 block's tags are exactly what its ingest reads back: a tag the sanitiser lets through
+  // and the ingest cannot read is content an author loses on save.
+  // RT3: the embed's figure and what it draws. Never `script`: X's widget script is written by the
+  // renderer for a site that opted in, and no submitted markup may bring one.
+  providerEmbed: ['figure', 'iframe', 'audio', 'a', 'blockquote', 'p', 'footer'],
+  // RT4: the gallery's figure, its list and each image's own figure.
+  gallery: ['figure', 'ul', 'li', 'img', 'figcaption'],
+  // RT5: the contents' nav, its title and its (nested) list of links.
+  tableOfContents: ['nav', 'p', 'ol', 'li', 'a'],
+  // RT6: a footnote's marker and link, and the end list its notes make.
+  footnotes: ['sup', 'a', 'ol', 'li'],
+  // RT8: related posts' aside, title and list of links; an author bio's aside, avatar and lines.
+  relatedPosts: ['aside', 'p', 'ul', 'li', 'a'],
+  authorBio: ['aside', 'img', 'p'],
+  // RT2: a button is an `<a data-button>`; the ingest reads it back (buttonLinkRule).
+  button: ['a'],
 }
 
 /**
@@ -122,6 +152,35 @@ export const DEFAULT_RICHTEXT_CONFIG: RichTextConfig = {
   allowMultipleParagraphs: true,
 }
 
+/**
+ * Each feature → the elements it grants. Total over the vocabulary (`satisfies` fails the build on
+ * a feature with no row); an alias (`headings`) has none, it is expanded before the lookup. Quote
+ * and divider grant nothing: `p` carries them, as `featuresFor` has always given both to any field
+ * with paragraphs.
+ */
+const FEATURE_ELEMENTS = {
+  bold: ['b'], italic: ['i'], underline: ['u'], strikethrough: ['s'], code: ['code'], highlight: ['mark'],
+  blockquote: [], horizontalRule: [],
+  orderedList: ['ol'], unorderedList: ['ul'], checklist: ['checklist'],
+  link: ['link'], internalLink: ['internalLink'], inlineImage: ['image'], videoEmbed: ['embed'],
+  codeBlock: ['pre'], table: ['table'], columns: ['columns'],
+  h1: ['h1'], h2: ['h2'], h3: ['h3'], h4: ['h4'], h5: ['h5'], h6: ['h6'],
+  gallery: ['gallery'], embed: ['providerEmbed'], tableOfContents: ['tableOfContents'], relatedPosts: ['relatedPosts'],
+  authorBio: ['authorBio'], footnotes: ['footnotes'], button: ['button'],
+} as const satisfies Record<FeatureName, readonly AcceptElement[]>
+
+/**
+ * A field's features → the elements it accepts: the ONE projection the sanitiser, the PT schema
+ * (`ptSchemaFor`), the dashboard codec and the kit consume, so `features` is the only stored gate.
+ * Aliases are expanded first (`headings` → the six levels) and unknown names grant nothing. `p` is
+ * the floor and never a feature, so `[]` is a field of paragraphs.
+ */
+export function acceptFor(features: readonly string[]): AcceptElement[] {
+  const granted = new Set<AcceptElement>(['p'])
+  for (const f of normaliseRichTextFeatures(features).features) for (const e of FEATURE_ELEMENTS[f]) granted.add(e)
+  return ALL_ELEMENTS.filter((e) => granted.has(e))
+}
+
 /** The tag allowlist the sanitiser enforces for a given Accept set. */
 export function allowedTags(accept: AcceptElement[]): string[] {
   // `span` carries marks and is never the reason content is stripped; the rest of `STYLED_TAGS`

package/src/columns.ts

@@ -0,0 +1,117 @@
+import { PT_TYPES, type PortableText } from "./types";
+
+/**
+ * RT7: columns (`PortableTextColumns`, types.ts), the first block that holds Portable Text of its
+ * own: `{ gap, columns: [{ _key, content }] }`. A V2 column is an editable run of text, so a
+ * column holds text blocks only, and never another block (R5: depth 1). The column count is
+ * derived (`data-cols`), never stored.
+ *
+ * A stored `bcmsBlock` under `builtin:columns` (plain text per column, `gap: small|medium|large`)
+ * is read the same way, so it renders instead of the empty marker it used to; nothing writes it.
+ * A legacy block in any other shape stays a marker.
+ */
+export const PT_COLUMNS_LIMITS = { min: 2, max: 4 } as const;
+export const COLUMNS_GAPS = ["s", "m", "l"] as const;
+export type ColumnsGap = (typeof COLUMNS_GAPS)[number];
+export const BUILTIN_COLUMNS_KEY = "builtin:columns" as const;
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  !!v && typeof v === "object" && !Array.isArray(v);
+
+/** The inline layout both renderers write (a hosted page has no stylesheet for it): legacy columns' flex row. */
+export const COLUMNS_STYLES: Record<ColumnsGap, { row: string; col: string }> = {
+  s: { row: "display:flex;flex-wrap:wrap;gap:0.75rem", col: "flex:1 1 14rem;min-width:0" },
+  m: { row: "display:flex;flex-wrap:wrap;gap:1.25rem", col: "flex:1 1 14rem;min-width:0" },
+  l: { row: "display:flex;flex-wrap:wrap;gap:2rem", col: "flex:1 1 14rem;min-width:0" },
+};
+
+/** A legacy column's plain text as text blocks: a paragraph per blank-line-separated run. */
+const legacyContent = (text: string, key: string): PortableText =>
+  text
+    .split(/\n{2,}/)
+    .filter((p) => p.trim() !== "")
+    .map((p, i) => ({ _type: "block", _key: `${key}p${i}`, style: "normal", markDefs: [], children: [{ _type: "span", _key: `${key}s${i}`, text: p, marks: [] }] }) as never);
+
+/**
+ * What a reader sees of a columns block, ours or a legacy `builtin:columns`: its gap and each
+ * column's content. Null for anything else. Read defensively: a column without content renders empty.
+ */
+export function columnsView(node: unknown): { gap: ColumnsGap; columns: { key: string; content: PortableText }[] } | null {
+  if (!isRecord(node)) return null;
+  if (node._type === PT_TYPES.columns) {
+    const gap: ColumnsGap = node.gap === "s" || node.gap === "l" ? node.gap : "m";
+    const columns = (Array.isArray(node.columns) ? node.columns : []).map((c, i) => ({
+      key: isRecord(c) && typeof c._key === "string" && c._key ? c._key : `c${i}`,
+      content: (isRecord(c) && Array.isArray(c.content) ? c.content : []) as PortableText,
+    }));
+    return { gap, columns };
+  }
+  if (node._type === PT_TYPES.block && node.schemaKey === BUILTIN_COLUMNS_KEY) {
+    const f = isRecord(node.fields) ? node.fields : {};
+    // Only the shape the legacy renderer wrote (plain text per column) reads as columns; any other
+    // stays the marker, which keeps "something is here" visible rather than drawing it empty.
+    if (!Array.isArray(f.columns) || !f.columns.every((c) => typeof c === "string")) return null;
+    const gap: ColumnsGap = f.gap === "small" ? "s" : f.gap === "large" ? "l" : "m";
+    const columns = (Array.isArray(f.columns) ? f.columns : []).slice(0, PT_COLUMNS_LIMITS.max).map((c, i) => ({
+      key: `c${i}`,
+      content: legacyContent(typeof c === "string" ? c : "", `c${i}`),
+    }));
+    return { gap, columns };
+  }
+  return null;
+}
+
+/** One reason a stored columns block is refused, at its own path inside the block. */
+export type PortableTextColumnsProblem = { path: Array<string | number>; code: string; message: string };
+
+const KEYS = new Set(["_type", "_key", "gap", "columns"]);
+
+/**
+ * Every reason `node` cannot be stored: `columns_invalid` (a shape problem, a column holding
+ * anything but text blocks, which includes another columns block (R5) and a footnote) or
+ * `columns_limit_exceeded` (outside V2's 2 to 4 columns). A derived `cols` is refused by R8, by name.
+ */
+export function columnsProblems(node: unknown): PortableTextColumnsProblem[] {
+  const out: PortableTextColumnsProblem[] = [];
+  if (!isRecord(node) || node._type !== PT_TYPES.columns) return out;
+  const bad = (path: Array<string | number>, message: string, code = "columns_invalid") =>
+    out.push({ path, code, message: `${code}: ${message}` });
+  for (const k of Object.keys(node)) if (!KEYS.has(k) && k !== "cols") bad([k], `unknown key "${k}" (gap, columns)`);
+  if (!(COLUMNS_GAPS as readonly unknown[]).includes(node.gap)) bad(["gap"], 'gap must be "s", "m" or "l"');
+  if (!Array.isArray(node.columns)) {
+    bad(["columns"], "columns must be an array");
+    return out;
+  }
+  const n = node.columns.length;
+  if (n < PT_COLUMNS_LIMITS.min || n > PT_COLUMNS_LIMITS.max) {
+    bad(["columns"], `${n} columns; ${PT_COLUMNS_LIMITS.min} to ${PT_COLUMNS_LIMITS.max}`, "columns_limit_exceeded");
+  }
+  node.columns.forEach((col, i) => {
+    const at = ["columns", i];
+    if (!isRecord(col)) return bad(at, `columns[${i}] must be an object`);
+    if (typeof col._key !== "string" || !col._key) bad([...at, "_key"], `columns[${i}] needs a _key`);
+    for (const k of Object.keys(col)) if (k !== "_key" && k !== "content") bad([...at, k], `unknown key "${k}" (content)`);
+    if (!Array.isArray(col.content)) return bad([...at, "content"], "content must be an array of text blocks");
+    col.content.forEach((b, j) => {
+      const bp = [...at, "content", j];
+      if (!isRecord(b) || b._type !== "block") {
+        return bad(bp, `a column holds text blocks only, not ${isRecord(b) && typeof b._type === "string" ? `"${b._type}"` : "this"}`);
+      }
+      (Array.isArray(b.children) ? b.children : []).forEach((c, k) => {
+        if (isRecord(c) && c._type === PT_TYPES.footnote) bad([...bp, "children", k], "a footnote belongs in the body text, not a column");
+      });
+    });
+  });
+  return out;
+}
+
+/** `columnsProblems` for every columns block at the top level of a value, with its block key. */
+export function portableTextColumnsProblems(value: unknown): Array<PortableTextColumnsProblem & { block: string }> {
+  const out: Array<PortableTextColumnsProblem & { block: string }> = [];
+  for (const node of Array.isArray(value) ? value : []) {
+    if (!isRecord(node) || node._type !== PT_TYPES.columns) continue;
+    const block = typeof node._key === "string" ? node._key : "";
+    for (const p of columnsProblems(node)) out.push({ ...p, block });
+  }
+  return out;
+}

package/src/embed.ts

@@ -0,0 +1,242 @@
+/**
+ * RT3: the embed. Stored `{ url, title, aspect }`; everything else is DERIVED from the url at
+ * render: the provider, its shape and the frame src (never stored; R8 refuses them on write).
+ *
+ * The resolver is pure and the frame src comes only from code: each provider's player URL is
+ * BUILT from ids parsed out of the link, for a host on this file's allowlist, over https. A link
+ * no rule recognises is a link card, never an iframe of whatever it points at. The allowlist grows
+ * from evidence (an import's `embed.legacy_iframe:<host>` lines), one pure parser per provider.
+ *
+ * An X post is a card: its words come from an oEmbed fetch the server makes when it builds the
+ * html cache (never stored in the value). Without that data, it is a link card.
+ */
+import type { EmbedCard, RichTextEmbeds } from "@bettercms-ai/types";
+import { resolveVideoSource } from "./video";
+import { safeHref } from "./href";
+
+export type { EmbedCard, RichTextEmbeds };
+
+export const EMBED_ASPECTS = ["16:9", "4:3", "1:1", "9:16"] as const;
+export type EmbedAspect = (typeof EMBED_ASPECTS)[number];
+export const isEmbedAspect = (v: unknown): v is EmbedAspect => (EMBED_ASPECTS as readonly unknown[]).includes(v);
+/** V2's title cap: screen-reader only, never shown. */
+export const EMBED_TITLE_MAX = 120;
+
+export type EmbedProvider =
+  | "youtube" | "vimeo" | "x" | "codepen" | "figma" | "maps" | "spotify" | "podcast" | "audio"
+  | "calendly" | "typeform" | "loom" | "airtable" | "google"
+  | "link";
+
+/** V2's detectEmbed (kit rich-text article.ts), verbatim: which provider a link is, and its label. */
+export function detectEmbed(url: string): { provider: EmbedProvider; label: string; host: string } {
+  const u = url.trim();
+  let host = "";
+  try {
+    host = new URL(u).hostname.replace(/^www\./, "");
+  } catch {
+    host = "";
+  }
+  const is = (re: RegExp) => re.test(u);
+  if (is(/(?:youtube\.com\/(?:watch\?|embed\/|shorts\/|live\/)|youtu\.be\/)/i)) return { provider: "youtube", label: "YouTube", host };
+  if (is(/vimeo\.com\/(?:video\/)?\d+/i)) return { provider: "vimeo", label: "Vimeo", host };
+  if (is(/(?:twitter|x)\.com\/[^/]+\/status\/\d+/i)) return { provider: "x", label: "X post", host };
+  if (is(/codepen\.io\/[^/]+\/(?:pen|embed)\//i)) return { provider: "codepen", label: "CodePen", host };
+  if (is(/figma\.com\/(?:file|design|proto|board)\//i)) return { provider: "figma", label: "Figma", host };
+  if (is(/(?:google\.[a-z.]+\/maps|maps\.app\.goo\.gl|goo\.gl\/maps)/i)) return { provider: "maps", label: "Google Maps", host };
+  if (is(/open\.spotify\.com\/(?:episode|track|show|playlist|album)\//i)) return { provider: "spotify", label: "Spotify", host };
+  if (is(/podcasts\.apple\.com\//i)) return { provider: "podcast", label: "Apple Podcasts", host };
+  if (is(/\.(?:mp3|m4a|wav|ogg|aac)(?:\?|$)/i)) return { provider: "audio", label: "Audio", host };
+  return { provider: "link", label: host || "Link", host };
+}
+
+/**
+ * Past V2's list: the providers the import evidence asked for, and the PLAYER urls an imported
+ * `<iframe>` carries (a YouTube nocookie frame, a Spotify /embed/ path) that V2's page-url patterns miss.
+ */
+function detectMore(url: URL): { provider: EmbedProvider; label: string } | null {
+  const host = url.hostname.toLowerCase().replace(/^www\./, "");
+  const path = url.pathname;
+  if (host === "youtube-nocookie.com" && path.startsWith("/embed/")) return { provider: "youtube", label: "YouTube" };
+  if (host === "open.spotify.com" && /^\/embed\/(?:episode|track|show|playlist|album)\//.test(path)) return { provider: "spotify", label: "Spotify" };
+  if (host === "calendly.com") return { provider: "calendly", label: "Calendly" };
+  if (host.endsWith(".typeform.com") && /^\/to\//.test(path)) return { provider: "typeform", label: "Typeform" };
+  if (host === "loom.com" && /^\/(?:share|embed)\//.test(path)) return { provider: "loom", label: "Loom" };
+  if (host === "airtable.com") return { provider: "airtable", label: "Airtable" };
+  if (host === "docs.google.com") {
+    const kind = path.split("/")[1];
+    const label = { forms: "Google Forms", document: "Google Docs", spreadsheets: "Google Sheets", presentation: "Google Slides" }[kind ?? ""];
+    if (label) return { provider: "google", label };
+  }
+  return null;
+}
+
+/** How an embed renders, all of it derived from the stored url. */
+export type ResolvedEmbed =
+  | { kind: "frame"; provider: EmbedProvider; label: string; src: string; width: string; height: string }
+  | { kind: "audio"; provider: "audio"; label: string; src: string }
+  | { kind: "card"; provider: "x"; label: string; url: string }
+  | { kind: "link"; provider: EmbedProvider; label: string; url: string | null };
+
+/** A video frame's default box per aspect: the size it has with no stylesheet at all. */
+const FRAME_SIZE: Record<EmbedAspect, [string, string]> = {
+  "16:9": ["640", "360"],
+  "4:3": ["640", "480"],
+  "1:1": ["640", "640"],
+  "9:16": ["360", "640"],
+};
+
+const ID = /^[A-Za-z0-9_-]{1,64}$/;
+/** A form, a calendar, a table or a document fills the column and is as tall as it needs. */
+const FULL_WIDTH_HEIGHT: Partial<Record<EmbedProvider, string>> = { calendly: "700", typeform: "500", airtable: "533" };
+
+/** The provider's player url (and, for a full-width player, its height), or null when we cannot frame the link. */
+function frameOf(provider: EmbedProvider, url: URL): { src: string; height?: string } | null {
+  const parts = url.pathname.split("/").filter(Boolean);
+  switch (provider) {
+    case "youtube":
+    case "vimeo": {
+      // The video block's resolver: one place knows YouTube's and Vimeo's player urls.
+      const video = resolveVideoSource(url.href);
+      return video?.kind === "iframe" ? { src: video.src } : null;
+    }
+    case "codepen": {
+      const [user, mode, id] = parts;
+      return user && ID.test(user) && (mode === "pen" || mode === "embed") && id && ID.test(id)
+        ? { src: `https://codepen.io/${user}/embed/${id}?default-tab=result` }
+        : null;
+    }
+    case "figma": {
+      const [mode, key] = parts;
+      if (!mode || !["file", "design", "proto", "board"].includes(mode) || !key || !ID.test(key)) return null;
+      const frame = new URL(`https://embed.figma.com/${mode}/${key}`);
+      const node = url.searchParams.get("node-id");
+      if (node && /^[0-9A-Za-z:_-]{1,64}$/.test(node)) frame.searchParams.set("node-id", node);
+      frame.searchParams.set("embed-host", "bettercms");
+      return { src: frame.href };
+    }
+    case "maps": {
+      if (!/^(?:www\.)?google\.[a-z.]+$/i.test(url.hostname)) return null; // a short link needs a fetch to resolve
+      const pb = url.searchParams.get("pb");
+      if (parts[0] === "maps" && parts[1] === "embed" && pb && /^[!A-Za-z0-9._:%+-]{1,2000}$/.test(pb)) {
+        return { src: `https://www.google.com/maps/embed?pb=${encodeURIComponent(pb)}` };
+      }
+      const at = /@(-?\d{1,3}(?:\.\d+)?),(-?\d{1,3}(?:\.\d+)?)/.exec(url.pathname);
+      const place = parts[0] === "maps" && parts[1] === "place" && parts[2] ? decodeURIComponent(parts[2]).replace(/\+/g, " ") : null;
+      const q = at ? `${at[1]},${at[2]}` : (url.searchParams.get("q") ?? place);
+      if (!q || q.length > 200) return null;
+      return { src: `https://maps.google.com/maps?q=${encodeURIComponent(q)}&output=embed` };
+    }
+    case "spotify": {
+      const [type, id] = parts[0] === "embed" ? parts.slice(1) : parts;
+      if (!type || !["episode", "track", "show", "playlist", "album"].includes(type) || !id || !ID.test(id)) return null;
+      return { src: `https://open.spotify.com/embed/${type}/${id}`, height: type === "track" || type === "episode" ? "152" : "352" };
+    }
+    case "podcast":
+      return (url.hostname === "podcasts.apple.com" || url.hostname === "embed.podcasts.apple.com") && parts.length >= 2
+        ? { src: `https://embed.podcasts.apple.com${url.pathname}${url.search}`, height: url.searchParams.has("i") ? "175" : "450" }
+        : null;
+    case "calendly":
+      return parts.length >= 1 && parts.length <= 2 && parts.every((p) => ID.test(p))
+        ? { src: `https://calendly.com/${parts.join("/")}?embed_type=Inline&hide_gdpr_banner=1` }
+        : null;
+    case "typeform": {
+      const id = parts[0] === "to" ? parts[1] : undefined;
+      return id && /^[A-Za-z0-9]{4,32}$/.test(id) ? { src: `https://form.typeform.com/to/${id}` } : null;
+    }
+    case "loom": {
+      const id = parts[1];
+      return (parts[0] === "share" || parts[0] === "embed") && id && /^[0-9a-f]{32}$/.test(id) ? { src: `https://www.loom.com/embed/${id}` } : null;
+    }
+    case "airtable": {
+      const ids = parts[0] === "embed" ? parts.slice(1) : parts;
+      return ids.length >= 1 && ids.length <= 3 && ids.every((p) => /^(?:app|shr|tbl|viw)[A-Za-z0-9]{14}$/.test(p)) && ids.some((p) => p.startsWith("shr"))
+        ? { src: `https://airtable.com/embed/${ids.join("/")}` }
+        : null;
+    }
+    case "google": {
+      // /<kind>/d/e/<id>/… is a published file, /<kind>/d/<id>/… a shared one.
+      const [kind, d, maybeE, maybeId] = parts;
+      if (d !== "d") return null;
+      const published = maybeE === "e";
+      const id = published ? maybeId : maybeE;
+      if (!id || !/^[A-Za-z0-9_-]{10,128}$/.test(id)) return null;
+      const base = `https://docs.google.com/${kind}/d/${published ? `e/${id}` : id}`;
+      if (kind === "forms") return { src: `${base}/viewform?embedded=true`, height: "800" };
+      if (kind === "document") return { src: published ? `${base}/pub?embedded=true` : `${base}/preview`, height: "600" };
+      if (kind === "spreadsheets") return { src: published ? `${base}/pubhtml?widget=true&headers=false` : `${base}/preview`, height: "600" };
+      if (kind === "presentation") return { src: published ? `${base}/embed` : `${base}/preview` };
+      return null;
+    }
+    default:
+      return null;
+  }
+}
+
+/** The X post id and handle in a status link, any of its spellings. */
+const X_STATUS = /^\/([A-Za-z0-9_]{1,15})\/status\/(\d{1,25})(?:\/|$)/;
+const X_HOSTS = /^(?:www\.|mobile\.)?(?:twitter|x)\.com$/i;
+
+/**
+ * The url an embed's derived data is keyed by. An X post in any spelling (twitter.com or x.com,
+ * www. or mobile., a tracking query, a /photo/1 tail, any handle case) is one
+ * `https://x.com/<handle>/status/<id>`; any other link is itself, normalised and without its
+ * fragment. Null for a link no renderer would follow.
+ */
+export function canonicalEmbedUrl(raw: unknown): string | null {
+  const url = typeof raw === "string" ? raw.trim() : "";
+  const safe = url ? safeHref(url) : null;
+  if (!safe || !/^https?:\/\//i.test(safe)) return null;
+  let parsed: URL;
+  try {
+    parsed = new URL(safe);
+  } catch {
+    return null;
+  }
+  const status = X_HOSTS.test(parsed.hostname) ? X_STATUS.exec(parsed.pathname) : null;
+  if (status) return `https://x.com/${status[1].toLowerCase()}/status/${status[2]}`;
+  parsed.hash = "";
+  return parsed.href;
+}
+
+/**
+ * The embed's rendering, derived from its stored url and aspect. Pure. An unsafe url is a link
+ * card with no href; one no rule recognises (or a short link) is a link card to itself.
+ */
+export function resolveEmbed(rawUrl: unknown, aspect: unknown = "16:9"): ResolvedEmbed {
+  const url = typeof rawUrl === "string" ? rawUrl.trim() : "";
+  const v2 = detectEmbed(url);
+  const safe = url ? safeHref(url) : null;
+  let parsed: URL | null = null;
+  try {
+    parsed = safe && /^https?:\/\//i.test(safe) ? new URL(safe) : null;
+  } catch {
+    parsed = null;
+  }
+  const { provider, label } = v2.provider === "link" && parsed ? (detectMore(parsed) ?? v2) : v2;
+  const link: ResolvedEmbed = { kind: "link", provider, label, url: safe };
+  if (!parsed) return link;
+  if (provider === "x") return { kind: "card", provider: "x", label, url: canonicalEmbedUrl(parsed.href) ?? parsed.href };
+  if (provider === "audio") return parsed.protocol === "https:" ? { kind: "audio", provider: "audio", label, src: parsed.href } : link;
+  const frame = frameOf(provider, parsed);
+  if (!frame) return link;
+  const height = frame.height ?? FULL_WIDTH_HEIGHT[provider];
+  if (height) return { kind: "frame", provider, label, src: frame.src, width: "100%", height };
+  const [width, h] = FRAME_SIZE[isEmbedAspect(aspect) ? aspect : "16:9"];
+  return { kind: "frame", provider, label, src: frame.src, width, height: h };
+}
+
+/** What a render needs that the value does not hold: the cards fetched for it. */
+export type EmbedRender = Partial<RichTextEmbeds>;
+
+/** X's widget script, loaded once per page on a site that opted in (next `BcmsEmbedScripts`), never by a value's html. */
+export const X_WIDGET_SCRIPT = "https://platform.twitter.com/widgets.js";
+
+/** The aspect nearest an imported frame's width and height (16:9 when it gives none). */
+export function nearestEmbedAspect(width: unknown, height: unknown): EmbedAspect {
+  const w = Number(width);
+  const h = Number(height);
+  if (!(w > 0) || !(h > 0)) return "16:9";
+  const ratio = w / h;
+  const ratios: [EmbedAspect, number][] = [["16:9", 16 / 9], ["4:3", 4 / 3], ["1:1", 1], ["9:16", 9 / 16]];
+  return ratios.reduce((best, cur) => (Math.abs(cur[1] - ratio) < Math.abs(best[1] - ratio) ? cur : best))[0];
+}

package/src/features.ts

@@ -1,29 +1,12 @@
 // ─── Feature Catalog ───────────────────────────────────────────────────────────
+// The vocabulary lives in @bettercms-ai/types (RICHTEXT_FEATURES), the one list richtext, the kit
+// and the backend validation read. These are its Lexical-era groups, unchanged: the Lexical editor
+// still switches every heading level with `headings`, which the vocabulary keeps as an alias only.
+import { RICHTEXT_MARK_FEATURES, RICHTEXT_TOGGLE_FEATURES } from '@bettercms-ai/types'
 
-export const ALWAYS_ON_FEATURES = [
-  'bold',
-  'italic',
-  'underline',
-  'strikethrough',
-  'code',
-  'highlight',
-] as const
+export const ALWAYS_ON_FEATURES = RICHTEXT_MARK_FEATURES
 
-export const TOGGLEABLE_FEATURES = [
-  'headings',
-  'blockquote',
-  'horizontalRule',
-  'orderedList',
-  'unorderedList',
-  'checklist',
-  'link',
-  'internalLink',
-  'inlineImage',
-  'videoEmbed',
-  'codeBlock',
-  'table',
-  'columns',
-] as const
+export const TOGGLEABLE_FEATURES = ['headings', ...RICHTEXT_TOGGLE_FEATURES] as const
 
 export type ToggleableRichTextFeature = (typeof TOGGLEABLE_FEATURES)[number]
 

package/src/footnote.ts

@@ -0,0 +1,70 @@
+import { PT_TYPES } from "./types";
+import { isPortableTextTable } from "./table";
+
+/**
+ * RT6: the footnote (`PortableTextFootnote`, types.ts), an inline object in body text that stores
+ * only its `note` (plain text, as V2 keeps it on the marker). Everything else is derived on every
+ * render: its number (its place in text order across the value's top-level text blocks), the
+ * `fnref-N` / `fn-N` ids, the end list and its back links.
+ *
+ * Not the table's footnote (`PortableTextTableFootnote`), which belongs to a table and stays apart.
+ */
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  !!v && typeof v === "object" && !Array.isArray(v);
+
+/**
+ * Each footnote in the value's top-level text blocks, numbered in text order (V2
+ * `renumberFootnotes`), and the notes in that order. `nodes` maps each marker to its number, which
+ * is how a renderer finds the number of the marker it is drawing.
+ */
+export function footnoteOrder(value: unknown): { notes: string[]; nodes: WeakMap<object, number> } {
+  const notes: string[] = [];
+  const nodes = new WeakMap<object, number>();
+  for (const node of Array.isArray(value) ? value : []) {
+    if (!isRecord(node) || node._type !== "block" || !Array.isArray(node.children)) continue;
+    for (const child of node.children) {
+      if (!isRecord(child) || child._type !== PT_TYPES.footnote) continue;
+      nodes.set(child, notes.push(typeof child.note === "string" ? child.note : ""));
+    }
+  }
+  return { notes, nodes };
+}
+
+/** One reason a stored footnote is refused, with the block it sits in. */
+export type PortableTextFootnoteProblem = { block: string; path: Array<string | number>; code: string; message: string };
+
+const KEYS = new Set(["_type", "_key", "note"]);
+
+/**
+ * Every reason a value's footnotes cannot be stored, by block and path: `footnote_invalid` for a
+ * shape problem, and for a footnote in a table cell (V2 refuses one inside a block: a cell has no
+ * place in the body's numbering). A derived `number` is refused by the R8 check, by name.
+ */
+export function portableTextFootnoteProblems(value: unknown): PortableTextFootnoteProblem[] {
+  const out: PortableTextFootnoteProblem[] = [];
+  const bad = (block: string, path: Array<string | number>, message: string) =>
+    out.push({ block, path, code: "footnote_invalid", message: `footnote_invalid: ${message}` });
+  const blockKey = (n: Record<string, unknown>) => (typeof n._key === "string" ? n._key : "");
+  const each = (blocks: unknown, inCell: string | null) => {
+    for (const node of Array.isArray(blocks) ? blocks : []) {
+      if (isPortableTextTable(node)) {
+        for (const row of node.rows as unknown[]) {
+          if (!isRecord(row) || !Array.isArray(row.cells)) continue;
+          for (const cell of row.cells) if (isRecord(cell)) each(cell.content, blockKey(node as Record<string, unknown>));
+        }
+        continue;
+      }
+      if (!isRecord(node) || node._type !== "block" || !Array.isArray(node.children)) continue;
+      node.children.forEach((child, i) => {
+        if (!isRecord(child) || child._type !== PT_TYPES.footnote) return;
+        const block = inCell ?? blockKey(node);
+        const path = inCell === null ? ["children", i] : [blockKey(node), "children", i];
+        if (inCell !== null) bad(block, path, "a footnote belongs in the body text, not a table cell");
+        for (const k of Object.keys(child)) if (!KEYS.has(k) && k !== "number") bad(block, [...path, k], `unknown key "${k}" (note)`);
+        if (typeof child.note !== "string") bad(block, [...path, "note"], "note must be a string");
+      });
+    }
+  };
+  each(value, null);
+  return out;
+}