@bettercms-ai/richtext 0.12.1 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/richtext",
-  "version": "0.12.1",
+  "version": "0.13.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,13 @@
     "test:watch": "vitest"
   },
   "dependencies": {
+    "@bettercms-ai/types": "^1.54.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. Each is reachable from its feature through `acceptFor`, but none is in
+ * the panel, the defaults or the sanitiser until its RT step ships the renderer and the ingest:
+ * a toggle with nothing behind it is the fake button the owner rule forbids.
+ */
+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',
 }
 
 /**
@@ -76,6 +88,14 @@ 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'],
+  // None until its RT step teaches the ingest the block's markup: 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'],
+  gallery: [], tableOfContents: [], relatedPosts: [], authorBio: [], footnotes: [],
+  // RT2: a button is an `<a data-button>`; the ingest reads it back (buttonLinkRule).
+  button: ['a'],
 }
 
 /**
@@ -92,7 +112,7 @@ export const HTML_BACKED_UNAVAILABLE_ACCEPT_REASONS: Partial<Record<AcceptElemen
   columns: 'Embedded blocks are available in entry rich text; component rich text stores HTML.',
 }
 
-const NEW_AUTHORING_EXCLUSIONS = new Set<AcceptElement>(['internalLink', 'rtl'])
+const NEW_AUTHORING_EXCLUSIONS = new Set<AcceptElement>(['internalLink', 'rtl', ...BLOCK_ELEMENTS])
 
 /** New defaults contain every capability whose complete consumer pipeline is currently live. */
 export const DEFAULT_ACCEPT: AcceptElement[] = ALL_ELEMENTS.filter(
@@ -122,6 +142,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/embed.ts

@@ -0,0 +1,160 @@
+/**
+ * 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.
+ *
+ * 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 { resolveVideoSource } from "./video";
+import { safeHref } from "./href";
+
+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" | "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 };
+}
+
+/** 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}$/;
+
+/** The provider's player url, built from the parsed link, or null when the link is not one we can frame. */
+function frameSrc(provider: EmbedProvider, url: URL): 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" ? video.src : null;
+    }
+    case "codepen": {
+      const [user, mode, id] = parts;
+      return user && ID.test(user) && (mode === "pen" || mode === "embed") && id && ID.test(id)
+        ? `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 frame.href;
+    }
+    case "maps": {
+      if (!/^(?:www\.)?google\.[a-z.]+$/i.test(url.hostname)) return null; // a short link needs a fetch to resolve
+      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 `https://maps.google.com/maps?q=${encodeURIComponent(q)}&output=embed`;
+    }
+    case "spotify": {
+      const [type, id] = parts;
+      return type && ["episode", "track", "show", "playlist", "album"].includes(type) && id && ID.test(id)
+        ? `https://open.spotify.com/embed/${type}/${id}`
+        : null;
+    }
+    case "podcast":
+      return url.hostname === "podcasts.apple.com" && parts.length >= 2 ? `https://embed.podcasts.apple.com${url.pathname}${url.search}` : null;
+    default:
+      return null;
+  }
+}
+
+/** The audio-shaped players' height: one row for an item, a list for a show or a playlist. */
+const audioHeight = (provider: EmbedProvider, url: URL): string => {
+  if (provider === "spotify") return /\/(?:track|episode)\//.test(url.pathname) ? "152" : "352";
+  return url.searchParams.has("i") ? "175" : "450";
+};
+
+/**
+ * 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 { provider, label } = 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 link: ResolvedEmbed = { kind: "link", provider, label, url: safe };
+  if (!parsed) return link;
+  if (provider === "x") return { kind: "card", provider: "x", label, url: parsed.href };
+  if (provider === "audio") return parsed.protocol === "https:" ? { kind: "audio", provider: "audio", label, src: parsed.href } : link;
+  const src = frameSrc(provider, parsed);
+  if (!src) return link;
+  if (provider === "spotify" || provider === "podcast") return { kind: "frame", provider, label, src, width: "100%", height: audioHeight(provider, parsed) };
+  const [width, height] = FRAME_SIZE[isEmbedAspect(aspect) ? aspect : "16:9"];
+  return { kind: "frame", provider, label, src, width, height };
+}
+
+/**
+ * An X post's card data, fetched by the server (oEmbed) when it builds the html cache: plain
+ * strings, escaped on the way out, never third-party markup. `text` is the post's words.
+ */
+export interface EmbedCard {
+  text: string;
+  authorName: string;
+  authorUrl?: string;
+  /** As X shows it ("Oct 24, 2026"). */
+  date?: string;
+}
+
+/** What a render needs that the value does not hold: the cards fetched for it, and the site's X choice. */
+export interface EmbedRender {
+  /** Card data by the embed's stored url. */
+  cards?: Readonly<Record<string, EmbedCard>>;
+  /** The site's opt-in to X's own script, which turns the card into X's live widget. Default off. */
+  xScript?: boolean;
+}
+
+/** X's widget script, loaded only on a site that opted in. */
+export const X_WIDGET_SCRIPT = "https://platform.twitter.com/widgets.js";

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/html.ts

@@ -16,6 +16,7 @@ import { safeHref } from "./href";
 import { isStyledTag, styledAttrEntries } from "./styled";
 import { richTextImageLayout } from "./image-layout";
 import { keyTakeawaysView } from "./key-takeaways";
+import { X_WIDGET_SCRIPT, isEmbedAspect, resolveEmbed, type EmbedCard, type EmbedRender } from "./embed";
 
 /**
  * Portable Text → HTML.
@@ -420,12 +421,58 @@ function keyTakeawaysHtml(value: unknown, classes: HtmlClasses): string {
   return `<aside data-rt="takeaways">${title ? `<p data-title>${esc(title)}</p>` : ""}<ul${cls(classes, "ul")}>${items}</ul></aside>`;
 }
 
+/**
+ * An X post's card, from the oEmbed data the server fetched (plain strings, escaped here; never
+ * X's markup). Static by default; with the site's `xScript` it is X's own blockquote and widget
+ * script, which turn it into the live post. The `<p>` and the link keep the post readable either way.
+ */
+function xCardHtml(url: string, card: EmbedCard, xScript: boolean, once: { script: boolean }): string {
+  const name = esc(card.authorName);
+  const date = esc(card.date || "View on X");
+  if (xScript) {
+    // The script once per render, however many posts: it upgrades every blockquote it finds (React dedupes it too).
+    const script = once.script ? "" : `<script async src="${X_WIDGET_SCRIPT}" charset="utf-8"></script>`;
+    once.script = true;
+    return `<blockquote class="twitter-tweet"><p>${esc(card.text)}</p>&mdash; ${name} <a href="${esc(url)}">${date}</a></blockquote>${script}`;
+  }
+  const authorHref = card.authorUrl ? safeHref(card.authorUrl) : null;
+  const author = authorHref ? `<a href="${esc(authorHref)}">${name}</a>` : name;
+  return `<blockquote class="bcms-embed-card" cite="${esc(url)}"><p>${esc(card.text)}</p><footer>&mdash; ${author} <a href="${esc(url)}">${date}</a></footer></blockquote>`;
+}
+
+/**
+ * RT3: an embed, V2's `<figure data-rt="embed" data-url data-provider data-aspect>` around what
+ * its url resolves to (`resolveEmbed`): the provider's frame, an audio player, an X card, or a
+ * link card. `aria-label` carries the stored title, present even when empty, so the ingest reads
+ * back exactly what was stored (V2's own markup has the title in the link instead).
+ */
+function embedFigureHtml(value: unknown, embeds: EmbedRender, once: { script: boolean }): string {
+  const v = (value ?? {}) as { url?: unknown; title?: unknown; aspect?: unknown };
+  const url = typeof v.url === "string" ? v.url.trim() : "";
+  const aspect = isEmbedAspect(v.aspect) ? v.aspect : "16:9";
+  const title = typeof v.title === "string" ? v.title.trim() : "";
+  const r = resolveEmbed(url, aspect);
+  const label = title || r.label;
+  let body: string;
+  if (r.kind === "frame") body = `<iframe src="${esc(r.src)}" title="${esc(label)}" width="${r.width}" height="${r.height}"${IFRAME_ATTRS}></iframe>`;
+  else if (r.kind === "audio") body = `<audio controls preload="none" src="${esc(r.src)}" title="${esc(label)}"></audio>`;
+  else if (r.kind === "card" && embeds.cards?.[url]) body = xCardHtml(r.url, embeds.cards[url], embeds.xScript === true, once);
+  // A link card: no rule frames this url, or it is an X post with no card data for this render.
+  else body = r.url ? `<a href="${esc(r.url)}">${esc(label)}</a>` : "";
+  return `<figure data-rt="embed" data-url="${esc(url)}" data-provider="${r.provider}" data-aspect="${aspect}" aria-label="${esc(title)}">${body}</figure>`;
+}
+
 export interface RenderOptions {
   /**
    * Render a single value with no wrapping `<p>`, for a field whose consumer supplies its own
    * heading or button. Mirrors `allowMultipleParagraphs: false` and the old `toInlineHtml`.
    */
   inline?: boolean;
+  /**
+   * RT3: what an embed needs that the value does not hold: the X cards the server fetched for this
+   * render (by url), and the site's opt-in to X's script. Absent: every X post is a link card.
+   */
+  embeds?: EmbedRender;
   /**
    * The site's own class per tag, for a value derived FROM that site.
    *
@@ -480,6 +527,17 @@ const bindingAttrs = (base: string, key: unknown): string =>
     ? ` data-bcms-field="${esc(base)}#${esc(key)}" data-bcms-kind="richtext"`
     : "";
 
+/**
+ * A checklist item, as V2 stores it (`<li data-checked="true|false">`), with a disabled checkbox in
+ * front of the words so a page without the V2 stylesheet still shows the box and its state, and a
+ * screen reader announces it. The ingest reads `data-checked` back and skips the box.
+ */
+const checkItemHtml = (classes: HtmlClasses, value: { checked?: unknown }, children: string | undefined, address: string): string => {
+  const checked = value.checked === true;
+  // `disabled` before `type`: the order React writes an input's attributes in, so the two renderers match (R6).
+  return `<li${cls(classes, "li")}${address} data-checked="${checked}"><input disabled type="checkbox"${checked ? " checked" : ""}>${children ?? ""}</li>`;
+};
+
 /**
  * `keys` is the set of `_key`s the value actually carries: to-html invents one (`li-0-1`) for an
  * item that has none, and an invented key is an address that resolves to nothing.
@@ -488,14 +546,28 @@ const buildComponents = (
   classes: HtmlClasses = {},
   binding?: { base: string; keys: ReadonlySet<unknown> },
   renderBlock?: RenderOptions["renderBlock"],
+  embeds: EmbedRender = {},
+  // Fresh per build, and a render builds its components once: what "once per render" counts against.
+  once: { script: boolean } = { script: false },
 ): Partial<PortableTextHtmlComponents> => ({
   block: tagOverrides(classes, STYLE_TAGS),
-  list: tagOverrides(classes, { bullet: "ul", number: "ol", check: "ul" }),
+  list: {
+    ...tagOverrides(classes, { bullet: "ul", number: "ol" }),
+    // A checklist is V2's `<ul data-task="true">`, dressed or not: it is not a bullet list.
+    check: ({ children }: { children?: string }) => `<ul data-task="true"${cls(classes, "ul")}>${children ?? ""}</ul>`,
+  },
   // With a base, every item carries its own address ON the `<li>` — see `bindingBase`.
   listItem: binding
-    ? ({ value, children }: { value: { _key?: unknown }; children?: string }) =>
-        `<li${cls(classes, "li")}${binding.keys.has(value._key) ? bindingAttrs(binding.base, value._key) : ""}>${children ?? ""}</li>`
-    : tagOverrides(classes, { bullet: "li", number: "li", check: "li" }),
+    ? ({ value, children }: { value: { _key?: unknown; listItem?: unknown; checked?: unknown }; children?: string }) => {
+        const address = binding.keys.has(value._key) ? bindingAttrs(binding.base, value._key) : "";
+        return value.listItem === "check"
+          ? checkItemHtml(classes, value, children, address)
+          : `<li${cls(classes, "li")}${address}>${children ?? ""}</li>`;
+      }
+    : {
+        ...tagOverrides(classes, { bullet: "li", number: "li" }),
+        check: ({ value, children }) => checkItemHtml(classes, value as { checked?: unknown }, children, ""),
+      },
   types: {
     [PT_TYPES.divider]: () => "<hr>",
     [PT_TYPES.table]: ({ value }) => tableHtml(value as PortableTextTable),
@@ -510,6 +582,7 @@ const buildComponents = (
     [PT_TYPES.file]: ({ value }) => fileHtml(value, classes),
     [PT_TYPES.pullQuote]: ({ value }) => pullQuoteHtml(value, classes),
     [PT_TYPES.keyTakeaways]: ({ value }) => keyTakeawaysHtml(value, classes),
+    [PT_TYPES.embed]: ({ value }) => embedFigureHtml(value, embeds, once),
     /**
      * A generic embedded block. A block whose payload this serialiser can READ renders as
      * content; one carrying a reference it would have to resolve against a project renders as a
@@ -557,9 +630,11 @@ const buildComponents = (
      * renders the LABEL rather than deleting it — a blocked link must not lose the words.
      */
     [PT_TYPES.link]: ({ value, children }) => {
-      const v = (value ?? {}) as { href?: unknown; target?: unknown; rel?: unknown; className?: unknown };
+      const v = (value ?? {}) as { href?: unknown; target?: unknown; rel?: unknown; className?: unknown; button?: unknown };
       const href = typeof v.href === "string" ? safeHref(v.href) : null;
       if (!href) return children;
+      // RT2: a button is a link the author marked as one; V2's `data-button` is the site's style hook.
+      const button = v.button === true ? ' data-button="true"' : "";
       // `rel` is author data too (the importer keeps `prev`/`next` on pagination links), so only
       // plain link-type tokens pass; a new tab always adds noopener + noreferrer.
       const rel = new Set(
@@ -573,7 +648,7 @@ const buildComponents = (
       const relAttr = rel.size ? ` rel="${esc([...rel].join(" "))}"` : "";
       // The link's own class (kept on ingest) wins over the caller's default: it IS the site.
       const own = typeof v.className === "string" && v.className ? ` class="${esc(v.className)}"` : "";
-      return `<a${own || cls(classes, "a")} href="${esc(href)}"${target}${relAttr}>${children}</a>`;
+      return `<a${own || cls(classes, "a")}${button} href="${esc(href)}"${target}${relAttr}>${children}</a>`;
     },
     /**
      * The site's own inline markup, written back out as itself.
@@ -618,11 +693,13 @@ export function portableTextToHtml(
 ): string {
   if (!Array.isArray(value) || value.length === 0) return "";
   const components =
-    opts.classes || opts.renderBlock ? buildComponents(opts.classes, undefined, opts.renderBlock) : defaultComponents;
+    opts.classes || opts.renderBlock || opts.embeds
+      ? buildComponents(opts.classes, undefined, opts.renderBlock, opts.embeds)
+      : defaultComponents;
 
   if (opts.bindingBase) {
     const base = opts.bindingBase;
-    const bound = buildComponents(opts.classes, { base, keys: new Set(value.map((n) => n._key)) }, opts.renderBlock);
+    const bound = buildComponents(opts.classes, { base, keys: new Set(value.map((n) => n._key)) }, opts.renderBlock, opts.embeds);
     const out: string[] = [];
     for (let i = 0; i < value.length; ) {
       const node = value[i];

package/src/index.ts

@@ -11,5 +11,7 @@ export * from "./read";
 export * from "./component-copy";
 export * from "./accept";
 export * from "./features";
+export * from "./write-refusals";
 export * from "./video";
+export * from "./embed";
 export * from "./image-layout";

package/src/ingest.ts

@@ -15,6 +15,7 @@ import {
 import { randomKey, isValidKey, type KeyGenerator } from "./key";
 import { safeHref } from "./href";
 import { BARE_IS_DESIGN, isStyledTag, styledAttrsOf, type StyledMarkDef } from "./styled";
+import { EMBED_TITLE_MAX, isEmbedAspect } from "./embed";
 import { cellTypeOf, columnOf, designOf, isColumnType, isValueType, jsonLdOf, PT_TABLE_LIMITS, typedCellText } from "./table";
 import { PT_KEY_TAKEAWAYS_LIMITS } from "./key-takeaways";
 import type { PtSchema } from "./schema";
@@ -513,6 +514,115 @@ function styledRule(key: KeyGenerator): DeserializerRule {
   };
 }
 
+/**
+ * The two decorators the renderer writes in markup the standard rules do not read back (R1):
+ * - `<mark>`: the deserialiser names it `mark`, the schema calls it `highlight`, so it was
+ *   dropped on every round trip;
+ * - `<span style="text-decoration:underline">`: what `portableTextToHtml` emits for `underline`,
+ *   which the styled rule then recorded as the site's own design instead of the decorator.
+ * Bare only: a classed `<mark>` or a span with anything else on it is still the styled rule's.
+ * Gated on the schema, because a custom rule's output is never filtered by it.
+ */
+function ownDecoratorRule(schema: PtSchema | undefined): DeserializerRule {
+  const allows = (name: string) => !schema || schema.decorators.some((d) => d.name === name);
+  return {
+    deserialize(el: Node, next) {
+      if (!isElement(el)) return undefined;
+      const tag = el.nodeName.toLowerCase();
+      const attrs = el.getAttributeNames();
+      if (tag === "mark" && attrs.length === 0 && allows("highlight")) {
+        return { _type: "__decorator", name: "highlight", children: next(el.childNodes) } as never;
+      }
+      const style = el.getAttribute("style")?.replace(/\s+/g, "").replace(/;$/, "").toLowerCase();
+      if (tag === "span" && attrs.length === 1 && style === "text-decoration:underline" && allows("underline")) {
+        return { _type: "__decorator", name: "underline", children: next(el.childNodes) } as never;
+      }
+      return undefined;
+    },
+  };
+}
+
+/**
+ * A V2 checklist item, `<ul data-task="true"><li data-checked="true|false">`, read as
+ * `listItem: "check"` + `checked`; a nested list's depth is added when it is flattened. The box in front of the words (the
+ * renderer's disabled checkbox) is skipped: the state is `data-checked`, never the input. Gated on
+ * the schema, because a custom rule's output is never filtered by it: a field without the
+ * checklist falls through to the standard rule and reads the items as bullets.
+ */
+function checklistItemRule(schema: PtSchema | undefined): DeserializerRule {
+  const allowed = !schema || schema.lists.some((l) => l.name === "check");
+  return {
+    deserialize(el: Node, next) {
+      if (!allowed || !isElement(el) || el.nodeName.toLowerCase() !== "li") return undefined;
+      const list = el.parentNode;
+      if (!list || !isElement(list) || list.nodeName.toLowerCase() !== "ul" || !list.hasAttribute("data-task")) return undefined;
+      const words = Array.from(el.childNodes).filter((n) => !(isElement(n) && n.nodeName.toLowerCase() === "input"));
+      return {
+        _type: "block",
+        style: "normal",
+        markDefs: [],
+        listItem: "check",
+        // 1, as the standard list rule writes it: flattening a nested list adds the depth.
+        level: 1,
+        checked: el.getAttribute("data-checked") === "true",
+        children: next(words as never),
+      } as never;
+    },
+  };
+}
+
+/**
+ * RT3: `<figure data-rt="embed">` → the `embed` block, the inverse of `embedFigureHtml` and of V2's
+ * own `<figure data-rt="embed" data-url data-aspect><a href>title</a></figure>`. Only what is
+ * stored is read: the url (`data-url`, else the link's href), the title (`aria-label` when the
+ * figure has one, which ours always does, else the link's words, as V2 reads it) and the aspect
+ * (V2's four, else 16:9). The frame, the card and `data-provider` are derived and ignored.
+ */
+function embedFigureRule(key: KeyGenerator, schema: PtSchema | undefined): DeserializerRule {
+  const allowed = allowsBlockObject(schema, PT_TYPES.embed);
+  return {
+    deserialize(el: Node, _next, createBlock) {
+      if (!allowed || !isElement(el) || el.nodeName.toLowerCase() !== "figure" || el.getAttribute("data-rt") !== "embed") return undefined;
+      const link = el.querySelector("a[href]");
+      const url = (el.getAttribute("data-url") ?? link?.getAttribute("href") ?? "").trim();
+      const title = (el.hasAttribute("aria-label") ? el.getAttribute("aria-label") ?? "" : (link?.textContent ?? "")).trim().slice(0, EMBED_TITLE_MAX);
+      const aspect = el.getAttribute("data-aspect");
+      return createBlock({ _type: PT_TYPES.embed, _key: key(), url, title, aspect: isEmbedAspect(aspect) ? aspect : "16:9" });
+    },
+  };
+}
+
+/**
+ * RT2: V2's button, `<a data-button="true" href>`, → a `link` annotation with `button: true` (and
+ * the site's class, a new tab and `rel`, as the classed link keeps them). Gated on the schema's
+ * link annotation having the `button` field: a field without the button feature reads it as the
+ * plain link it also is.
+ */
+function buttonLinkRule(key: KeyGenerator, schema: PtSchema | undefined): DeserializerRule {
+  const allowed =
+    !schema || schema.annotations.some((a) => a.name === PT_TYPES.link && (a.fields ?? []).some((f) => f.name === "button"));
+  return {
+    deserialize(el: Node, next) {
+      if (!allowed || !isElement(el) || el.nodeName.toLowerCase() !== "a") return undefined;
+      const flag = el.getAttribute("data-button");
+      const href = el.getAttribute("href")?.trim();
+      if (flag === null || flag === "false" || !href) return undefined;
+      const className = el.getAttribute("class")?.trim();
+      const rel = el.getAttribute("rel")?.trim();
+      const markDef = {
+        _type: PT_TYPES.link,
+        _key: key(),
+        href,
+        button: true,
+        ...(className ? { className } : {}),
+        ...(el.getAttribute("target") === "_blank" ? { target: "_blank" } : {}),
+        ...(rel ? { rel } : {}),
+      };
+      return { _type: "__annotation", markDef, children: next(el.childNodes) } as never;
+    },
+  };
+}
+
 /**
  * `<a class>` → a `link` annotation that keeps the site's class as `className`.
  *
@@ -851,8 +961,13 @@ export function htmlToPortableText(html: string, opts: IngestOptions = {}): Port
       ...(allowsBlockObject(opts.schema, PT_TYPES.code) ? [codeRule(key)] : []),
       ...(allowsBlockObject(opts.schema, PT_TYPES.pullQuote) ? [pullQuoteRule(key)] : []),
       ...(allowsBlockObject(opts.schema, PT_TYPES.keyTakeaways) ? [keyTakeawaysRule(key)] : []),
+      // Before the media rule, which would take the iframe out of our own embed figure.
+      embedFigureRule(key, opts.schema),
       mediaRule(key, opts.schema),
+      checklistItemRule(opts.schema),
+      ownDecoratorRule(opts.schema),
       ...(allowsStyled(opts.schema) ? [styledRule(key)] : []),
+      buttonLinkRule(key, opts.schema),
       ...(allowsLinks(opts.schema) ? [classedLinkRule(key)] : []),
     ],
     keyGenerator: key,

package/src/schema.ts

@@ -102,7 +102,7 @@ export function ptSchemaFor(accept: readonly AcceptElement[]): PtSchema {
       ],
     },
   ];
-  if (has("link") || has("internalLink")) {
+  if (has("link") || has("internalLink") || has("button")) {
     annotations.push({
       name: PT_TYPES.link,
       title: "Link",
@@ -113,6 +113,9 @@ export function ptSchemaFor(accept: readonly AcceptElement[]): PtSchema {
         { name: "target", type: "string" },
         // The site's own class on the `<a>`, kept so a styled link round-trips.
         { name: "className", type: "string" },
+        // RT2: V2's button is a link the author marked as one (`<a data-button="true">`), edited as
+        // text in the flow. Only a field with the button feature has the field to set.
+        ...(has("button") ? [{ name: "button", type: "boolean" as const }] : []),
       ],
     });
   }
@@ -222,6 +225,18 @@ export function ptSchemaFor(accept: readonly AcceptElement[]): PtSchema {
    * hold and move it; it does not validate the payload, so a deeper declaration would buy
    * nothing and drift from the types that do.
    */
+  // RT3: the third-party embed; its provider and frame are derived from `url` (embed.ts).
+  if (has("providerEmbed")) {
+    blockObjects.push({
+      name: PT_TYPES.embed,
+      title: "Embed",
+      fields: [
+        { name: "url", type: "string" },
+        { name: "title", type: "string" },
+        { name: "aspect", type: "string" },
+      ],
+    });
+  }
   if (has("table")) {
     blockObjects.push({
       name: PT_TYPES.table,

package/src/types.ts

@@ -338,6 +338,18 @@ export interface PortableTextKeyTakeaways extends PortableTextObject {
   points: string[];
 }
 
+/**
+ * RT3: an embed, as V2's EmbedModel. Only what the author sets is stored: the link, the
+ * screen-reader title (≤ EMBED_TITLE_MAX) and the shape. The provider, its kind and the frame src
+ * are derived from `url` at render (`resolveEmbed`), never stored.
+ */
+export interface PortableTextEmbed extends PortableTextObject {
+  _type: "embed";
+  url: string;
+  title: string;
+  aspect: "16:9" | "4:3" | "1:1" | "9:16";
+}
+
 export const isPortableTextBlock = (n: unknown): n is PortableTextBlock =>
   !!n && typeof n === "object" && (n as PortableTextNode)._type === "block";
 
@@ -389,6 +401,12 @@ export const PT_TYPES = {
   pullQuote: "pullQuote",
   /** Key takeaways — see `PortableTextKeyTakeaways`. The V2 kit's `<aside data-rt="takeaways">`. */
   keyTakeaways: "keyTakeaways",
+  /**
+   * A third-party embed (X, CodePen, Figma, Maps, Spotify, Podcasts, audio, a link card) — see
+   * `PortableTextEmbed` and `embed.ts`. The V2 kit's `<figure data-rt="embed">`. Gated by the
+   * `embed` feature; YouTube and Vimeo links still resolve here too, through the video resolver.
+   */
+  embed: "embed",
   /**
    * A table. Spelled `table`, unprefixed, because that is what every other Portable Text
    * producer calls one — the Sanity-shaped `{_type:"table", rows}` this platform used to refuse
@@ -446,6 +464,7 @@ export const STORABLE_BLOCK_TYPES: ReadonlySet<string> = new Set<string>([
   PT_TYPES.file,
   PT_TYPES.pullQuote,
   PT_TYPES.keyTakeaways,
+  PT_TYPES.embed,
 ]);
 
 /**
@@ -575,6 +594,14 @@ export function isStorableKeyTakeaways(node: unknown): boolean {
   return Array.isArray((node as { points?: unknown }).points);
 }
 
+/** An embed holds a link, a title of at most 120 characters, and one of V2's four shapes. */
+export function isStorableEmbed(node: unknown): boolean {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return false;
+  const n = node as { url?: unknown; title?: unknown; aspect?: unknown };
+  return typeof n.url === "string" && typeof n.title === "string" && n.title.length <= 120
+    && (n.aspect === "16:9" || n.aspect === "4:3" || n.aspect === "1:1" || n.aspect === "9:16");
+}
+
 /**
  * @deprecated The marker a table-accepting field used to carry INSTEAD of a table.
  *

package/src/write-refusals.ts

@@ -0,0 +1,106 @@
+/**
+ * What a rich-text WRITE may not hold, refused by name and never removed (RT0, properties R4, R8).
+ *
+ * Both read the value and answer a list. Neither changes it, so a caller that writes after an
+ * empty answer writes exactly what it was given: there is no strip step for content to vanish in.
+ * Callers that judge a stored value should judge only what the write introduces, as the field-key
+ * rules do: values written before a rule existed must keep saving.
+ */
+import { richTextRefusal, type UiRefusal } from "@bettercms-ai/types";
+import { acceptFor } from "./accept";
+import { ptSchemaFor } from "./schema";
+import { isPortableTextBlock, type PortableText, type PortableTextNode } from "./types";
+
+/**
+ * R4: every node, style, list, mark or annotation a field's features do not accept, judged against
+ * `ptSchemaFor(acceptFor(features))`, the same schema the editor offers. One refusal per name:
+ * `richtext.block_not_accepted:<name>`, where name is a block object's or inline object's `_type`,
+ * a style (`h2`), a list (`check`), a decorator (`strong`) or an annotation's `_type` (`link`).
+ */
+export function notAcceptedProblems(value: PortableText, features: readonly string[]): UiRefusal[] {
+  const accepted = acceptFor(features);
+  const schema = ptSchemaFor(accepted);
+  // One `link` annotation carries both: a plain link needs a link element, a button the button one.
+  const linkOk = accepted.includes("link") || accepted.includes("internalLink");
+  const buttonOk = accepted.includes("button");
+  const names = (list: { name: string }[]) => new Set(list.map((x) => x.name));
+  const styles = names(schema.styles);
+  const lists = names(schema.lists);
+  const decorators = names(schema.decorators);
+  const annotations = names(schema.annotations);
+  const blockObjects = names(schema.blockObjects);
+  const inlineObjects = names(schema.inlineObjects);
+
+  const out: UiRefusal[] = [];
+  const refused = new Set<string>();
+  const refuse = (name: string) => {
+    if (refused.has(name)) return;
+    refused.add(name);
+    out.push(richTextRefusal("block_not_accepted", name));
+  };
+
+  for (const node of value) {
+    if (!isPortableTextBlock(node)) {
+      if (!blockObjects.has(node._type)) refuse(node._type);
+      continue;
+    }
+    if (!styles.has(node.style ?? "normal")) refuse(node.style);
+    if (node.listItem !== undefined && !lists.has(node.listItem)) refuse(node.listItem);
+    const defs = new Set<string>();
+    for (const def of node.markDefs ?? []) {
+      defs.add(def._key);
+      if (def._type === "link") {
+        if (def.button === true ? !buttonOk : !linkOk) refuse(def.button === true ? "button" : "link");
+      } else if (!annotations.has(def._type)) refuse(def._type);
+    }
+    for (const child of node.children ?? []) {
+      if (child._type !== "span") {
+        if (!inlineObjects.has(child._type)) refuse(child._type);
+        continue;
+      }
+      // A mark is a markDef key (its annotation was judged above) or a decorator name.
+      for (const mark of (child as { marks?: string[] }).marks ?? []) if (!defs.has(mark) && !decorators.has(mark)) refuse(mark);
+    }
+  }
+  return out;
+}
+
+/**
+ * What each V2 block computes at render time and never stores (kit-richtext-blocks-gap.md, the
+ * "Derived" line of each block). `posts[].title` means that key on every entry of `posts`. Each RT
+ * step confirms its row when it builds the type; a key outside its row is not judged here.
+ */
+export const DERIVED_FIELDS: Readonly<Record<string, readonly string[]>> = {
+  footnote: ["number"],
+  embed: ["provider", "shape", "src"],
+  columns: ["cols"],
+  tableOfContents: ["outline"],
+  authorBio: ["name", "avatar", "bio"],
+  relatedPosts: ["posts[].title", "posts[].slug", "posts[].url", "posts[].cover", "posts[].category"],
+};
+
+/** Whether a node holds a derived path: `key`, or `list[].key` on any entry of the list. */
+const holds = (node: Record<string, unknown>, path: string): boolean => {
+  const [list, key] = path.split("[].");
+  if (key === undefined) return Object.hasOwn(node, path);
+  const items = node[list];
+  return Array.isArray(items) && items.some((item) => item !== null && typeof item === "object" && Object.hasOwn(item, key));
+};
+
+/**
+ * R8: every derived key a write carries, top-level nodes and inline children alike, refused as
+ * `richtext.derived_field:<_type>.<path>` (`embed.provider`, `relatedPosts.posts[].title`).
+ */
+export function derivedFieldProblems(value: PortableText): UiRefusal[] {
+  const out: UiRefusal[] = [];
+  const judge = (node: PortableTextNode) => {
+    for (const path of DERIVED_FIELDS[node._type] ?? []) {
+      if (holds(node as unknown as Record<string, unknown>, path)) out.push(richTextRefusal("derived_field", `${node._type}.${path}`));
+    }
+  };
+  for (const node of value) {
+    judge(node);
+    if (isPortableTextBlock(node)) for (const child of node.children ?? []) judge(child);
+  }
+  return out;
+}