@bettercms-ai/richtext 0.12.1 → 0.16.0

package/src/gallery.ts

@@ -0,0 +1,167 @@
+import { PT_TYPES } from "./types";
+import { isPortableTextTable } from "./table";
+import { safeHref } from "./href";
+import { richTextImageFrame } from "./image-layout";
+
+/**
+ * RT4: the gallery (`PortableTextGallery`, types.ts): the limits, the write check, and the read
+ * both renderers share.
+ *
+ * The limits are the V2 kit's (`ARTICLE_SCHEMAS.gallery` in `controls/rich-text/article.ts`): 2 to
+ * 24 images, a caption of at most 160 characters. As with key takeaways, V2's `min: 2` and its
+ * required image are the editor's, not the write's: an author adds images one at a time, and
+ * refusing the autosave in between would refuse the gallery they are building. So a gallery of
+ * one, or an image not yet chosen, stores; the view leaves an unchosen image out, as V2 does.
+ *
+ * The image is the rich-text image's own `{ src, alt }` (+ an optional media id), so whatever
+ * reads a rich-text image's src and alt reads a gallery image's the same way.
+ */
+export const PT_GALLERY_LIMITS = { minImages: 2, images: 24, captionChars: 160 } as const;
+export const GALLERY_LAYOUTS = ["grid", "carousel"] as const;
+export type GalleryLayout = (typeof GALLERY_LAYOUTS)[number];
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  !!v && typeof v === "object" && !Array.isArray(v);
+
+/** One reason a stored gallery is refused, at its own path inside the block. */
+export type PortableTextGalleryProblem = { path: Array<string | number>; code: string; message: string };
+
+const KEYS = new Set(["_type", "_key", "layout", "images"]);
+const ITEM_KEYS = new Set(["_key", "image", "caption"]);
+const IMAGE_KEYS = new Set(["src", "alt", "mediaId", "crop", "focal"]);
+const fraction = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= 1;
+
+/**
+ * Every reason `node` cannot be stored, each named with a code: `gallery_invalid` (a shape
+ * problem) or `gallery_limit_exceeded` (a V2 limit). Only a `gallery` block is judged; the type is
+ * new, so there is nothing stored before it to grandfather.
+ */
+export function galleryProblems(node: unknown): PortableTextGalleryProblem[] {
+  const out: PortableTextGalleryProblem[] = [];
+  if (!isRecord(node) || node._type !== PT_TYPES.gallery) return out;
+  const bad = (path: Array<string | number>, message: string, code = "gallery_invalid") =>
+    out.push({ path, code, message: `${code}: ${message}` });
+  for (const k of Object.keys(node)) if (!KEYS.has(k)) bad([k], `unknown key "${k}" (layout, images)`);
+  if (!(GALLERY_LAYOUTS as readonly unknown[]).includes(node.layout)) bad(["layout"], 'layout must be "grid" or "carousel"');
+  if (!Array.isArray(node.images)) {
+    bad(["images"], "images must be an array");
+    return out;
+  }
+  node.images.forEach((item, i) => {
+    const at = ["images", i];
+    if (!isRecord(item)) return bad(at, `images[${i}] must be an object`);
+    for (const k of Object.keys(item)) if (!ITEM_KEYS.has(k)) bad([...at, k], `unknown key "${k}" (image, caption)`);
+    if (typeof item._key !== "string" || !item._key) bad([...at, "_key"], `images[${i}] needs a _key`);
+    if (item.caption !== undefined) {
+      if (typeof item.caption !== "string") bad([...at, "caption"], "caption must be a string");
+      else if (item.caption.length > PT_GALLERY_LIMITS.captionChars) {
+        bad([...at, "caption"], `caption is ${item.caption.length} characters; at most ${PT_GALLERY_LIMITS.captionChars}`, "gallery_limit_exceeded");
+      }
+    }
+    const image = item.image;
+    if (image === undefined || image === null) return;
+    if (!isRecord(image)) return bad([...at, "image"], "image must be { src, alt }");
+    for (const k of Object.keys(image)) if (!IMAGE_KEYS.has(k)) bad([...at, "image", k], `unknown key "${k}" (src, alt, mediaId)`);
+    if (typeof image.src !== "string") bad([...at, "image", "src"], "src must be a string");
+    if (typeof image.alt !== "string") bad([...at, "image", "alt"], "alt must be a string");
+    if (image.mediaId !== undefined && typeof image.mediaId !== "string") bad([...at, "image", "mediaId"], "mediaId must be a string");
+    // RT9: the rich-text image's framing, image-url's shape: edges cut as 0–1 fractions, a 0–1 point.
+    const crop = image.crop;
+    if (crop !== undefined && crop !== null) {
+      const c = isRecord(crop) ? crop : {};
+      if (![c.top, c.right, c.bottom, c.left].every(fraction) || (c.top as number) + (c.bottom as number) >= 1 || (c.left as number) + (c.right as number) >= 1) {
+        bad([...at, "image", "crop"], "crop must be { top, right, bottom, left }, 0–1 fractions that leave some picture");
+      }
+    }
+    const focal = image.focal;
+    if (focal !== undefined && focal !== null && !(isRecord(focal) && fraction(focal.x) && fraction(focal.y))) {
+      bad([...at, "image", "focal"], "focal must be { x, y }, 0–1 fractions");
+    }
+  });
+  if (node.images.length > PT_GALLERY_LIMITS.images) {
+    bad(["images"], `${node.images.length} images; at most ${PT_GALLERY_LIMITS.images}`, "gallery_limit_exceeded");
+  }
+  return out;
+}
+
+/**
+ * `galleryProblems` for every gallery in a rich-text value (top level, and inside table cells),
+ * with the block's `_key` so a refusal names the block an author has to find.
+ */
+export function portableTextGalleryProblems(value: unknown): Array<PortableTextGalleryProblem & { block: string }> {
+  const out: Array<PortableTextGalleryProblem & { block: string }> = [];
+  const walk = (blocks: unknown) => {
+    if (!Array.isArray(blocks)) return;
+    for (const node of 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)) walk(cell.content);
+        }
+        continue;
+      }
+      if (!isRecord(node) || node._type !== PT_TYPES.gallery) continue;
+      const block = typeof node._key === "string" ? node._key : "";
+      for (const p of galleryProblems(node)) out.push({ ...p, block });
+    }
+  };
+  walk(value);
+  return out;
+}
+
+/**
+ * The same widened check the rich-text image's `<img>` gets (html.ts `mediaSrc`): http(s), or a
+ * site-relative path with no scheme, whitespace or protocol-relative `//`.
+ */
+export const galleryMediaSrc = (raw: string): string | null =>
+  safeHref(raw) ?? (raw !== "" && !raw.startsWith("//") && !/[:\s]/.test(raw) ? raw : null);
+
+/**
+ * The layout, as inline CSS both renderers write (ui turns each into a React style object). A grid
+ * of equal cells; a carousel is one image per view in a scroll-snap row, its no-JS fallback being
+ * itself.
+ */
+export const GALLERY_STYLES: Record<GalleryLayout, { ul: string; li: string; figure: string; img: string }> = {
+  grid: {
+    ul: "display:grid;grid-template-columns:repeat(auto-fill,minmax(12rem,1fr));gap:1rem;list-style:none;margin:0;padding:0",
+    li: "margin:0",
+    figure: "margin:0",
+    img: "display:block;width:100%;height:auto",
+  },
+  carousel: {
+    ul: "display:flex;gap:1rem;overflow-x:auto;scroll-snap-type:x mandatory;list-style:none;margin:0;padding:0",
+    li: "flex:0 0 100%;scroll-snap-align:start;margin:0",
+    figure: "margin:0",
+    img: "display:block;width:100%;height:auto",
+  },
+};
+
+/**
+ * What a reader sees of a gallery: its layout (grid unless it says carousel) and each image that
+ * has a safe src, with its alt and trimmed caption. An unchosen image is left out, as V2's
+ * `renderArticle("gallery")` leaves it out. Read defensively: a value that never passed the write
+ * check renders what it can.
+ */
+export type GalleryViewImage = { key: string; src: string; alt: string; caption: string; position: string | null; data: [string, string][] };
+
+export function galleryView(value: unknown): { layout: GalleryLayout; images: GalleryViewImage[] } {
+  const v = isRecord(value) ? value : {};
+  const layout: GalleryLayout = v.layout === "carousel" ? "carousel" : "grid";
+  const images: GalleryViewImage[] = [];
+  (Array.isArray(v.images) ? v.images : []).forEach((item, i) => {
+    if (!isRecord(item) || !isRecord(item.image)) return;
+    const src = galleryMediaSrc(typeof item.image.src === "string" ? item.image.src.trim() : "");
+    if (!src) return;
+    // RT9: the crop and focal point, as a rich-text image draws them (image-layout.ts).
+    const frame = richTextImageFrame(src, item.image.crop, item.image.focal);
+    images.push({
+      key: typeof item._key === "string" && item._key ? item._key : `i${i}`,
+      src: frame.src,
+      position: frame.position,
+      data: frame.data,
+      alt: typeof item.image.alt === "string" ? item.image.alt : "",
+      caption: typeof item.caption === "string" ? item.caption.trim() : "",
+    });
+  });
+  return { layout, images };
+}

package/src/html.ts

@@ -14,8 +14,15 @@ import { builtInTableToTable, designOf, footnoteNumbers, footnotesOf, highlighte
 import { portableTextToPlainText } from "./plain";
 import { safeHref } from "./href";
 import { isStyledTag, styledAttrEntries } from "./styled";
-import { richTextImageLayout } from "./image-layout";
+import { richTextImageFrame, richTextImageLayout } from "./image-layout";
 import { keyTakeawaysView } from "./key-takeaways";
+import { GALLERY_STYLES, galleryView } from "./gallery";
+import { outlineOf, tocTree, tocView, type OutlineItem } from "./toc";
+import { footnoteOrder } from "./footnote";
+import { BUILTIN_COLUMNS_KEY, COLUMNS_STYLES, columnsView } from "./columns";
+import { authorBioView, relatedPostsView } from "./references";
+import type { RichTextResolved } from "@bettercms-ai/types";
+import { isEmbedAspect, resolveEmbed, type EmbedCard, type EmbedRender } from "./embed";
 
 /**
  * Portable Text → HTML.
@@ -279,9 +286,13 @@ function imageHtml(value: unknown, classes: HtmlClasses): string {
   if (!src) return "";
   const caption = str(f.caption);
   const layout = richTextImageLayout(f);
+  // RT9: the crop rides the url, the focal point is object-position; what is stored rides data-*.
+  const frame = richTextImageFrame(src, f.crop, f.focal);
   // A placed image fills its figure; the figure carries the width and position (image-layout.ts).
-  const imgStyle = layout ? ' style="display:block;width:100%;height:auto"' : "";
-  const img = `<img${cls(classes, "img")} src="${esc(src)}" alt="${esc(str(f.alt))}"${imgStyle}>`;
+  const styles = [layout ? "display:block;width:100%;height:auto" : "", frame.position ? `object-position:${frame.position}` : ""].filter(Boolean);
+  const imgStyle = styles.length ? ` style="${styles.join(";")}"` : "";
+  const data = frame.data.map(([k, v]) => ` ${k}="${esc(v)}"`).join("");
+  const img = `<img${cls(classes, "img")} src="${esc(frame.src)}" alt="${esc(str(f.alt))}"${imgStyle}${data}>`;
   const figureClass = [classes.figure, layout?.className].filter(Boolean).join(" ");
   const figureAttrs = `${figureClass ? ` class="${esc(figureClass)}"` : ""}${
     layout ? ` style="${esc(layout.figureStyle)}"` : ""
@@ -420,12 +431,174 @@ 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>`;
 }
 
+/**
+ * RT4: a gallery, V2's `<figure data-rt="gallery" data-layout><ul><li><figure><img><figcaption>`.
+ * The layout needs no script: a grid, or a carousel that is a scroll-snap row (swipe, scroll, or
+ * the keyboard once the row has focus). The styles are inline because a hosted page has no
+ * stylesheet for them; the ingest reads only the markup back. `src` comes last on the `<img>`, as
+ * React writes a lazy image's, so both renderers give the same bytes (R6).
+ */
+function galleryHtml(value: unknown): string {
+  const { layout, images } = galleryView(value);
+  const s = GALLERY_STYLES[layout];
+  const items = images
+    .map((x) => `<li style="${s.li}"><figure style="${s.figure}"><img alt="${esc(x.alt)}" style="${s.img}${x.position ? `;object-position:${x.position}` : ""}" loading="lazy"${x.data
+      .map(([k, v]) => ` ${k}="${esc(v)}"`)
+      .join("")} src="${esc(x.src)}">${
+      x.caption ? `<figcaption>${esc(x.caption)}</figcaption>` : ""
+    }</figure></li>`)
+    .join("");
+  const focus = layout === "carousel" ? ' tabindex="0"' : "";
+  return `<figure data-rt="gallery" data-layout="${layout}"><ul style="${s.ul}"${focus}>${items}</ul></figure>`;
+}
+
+/**
+ * RT5: the outline of the value being rendered. Set by `portableTextToHtml` for a whole-value
+ * render and restored after it (a render is synchronous, and a table cell renders inside another
+ * one); an inline render (a cell, a heading field) keeps the value's outline it sits in.
+ */
+let outline: { items: OutlineItem[]; nodes: WeakMap<object, string> } = { items: [], nodes: new WeakMap() };
+/** RT6: the footnotes of the value being rendered, numbered in text order; set and restored with `outline`. */
+let footnotes: { notes: string[]; nodes: WeakMap<object, number> } = { notes: [], nodes: new WeakMap() };
+
+/**
+ * RT6: a footnote's marker, V2's `<sup data-rt="fn" id="fnref-N" data-note><a href="#fn-N">N</a></sup>`.
+ * `data-note` carries the stored note, so the ingest reads it back; the number is its place in the
+ * value. A marker outside the value's body text (a table cell, which the write refuses) has none.
+ */
+function footnoteMarkHtml(value: object): string {
+  const note = esc(typeof (value as { note?: unknown }).note === "string" ? (value as { note: string }).note : "");
+  const n = footnotes.nodes.get(value);
+  return n
+    ? `<sup data-rt="fn" id="fnref-${n}" data-note="${note}"><a href="#fn-${n}" aria-label="Footnote ${n}">${n}</a></sup>`
+    : `<sup data-rt="fn" data-note="${note}"></sup>`;
+}
+
+/**
+ * RT7: columns, V2's `<div data-rt="columns" data-gap data-cols><div data-col="true">…</div></div>`,
+ * each column's text rendered by the same components as the body. The flex row is inline (no
+ * stylesheet on a hosted page): side by side, wrapping one under another on a narrow screen. A
+ * legacy `builtin:columns` renders the same way.
+ */
+function columnsHtml(value: unknown, components: () => Partial<PortableTextHtmlComponents>): string {
+  const view = columnsView(value);
+  if (!view) return "";
+  const s = COLUMNS_STYLES[view.gap];
+  const cols = view.columns
+    .map((c) => `<div data-col="true" style="${s.col}">${c.content.length ? toHTML(c.content as never, { components: components() }) : ""}</div>`)
+    .join("");
+  return `<div data-rt="columns" data-gap="${view.gap}" data-cols="${view.columns.length}" style="${s.row}">${cols}</div>`;
+}
+
+/**
+ * RT8: related posts, V2's `<aside data-rt="related" data-mode data-count data-posts><p data-title>…</p>
+ * <ul><li><a href>…</a></li></ul></aside>`, listing what the server resolved (relatedPostsView).
+ */
+function relatedPostsHtml(value: unknown, resolved: RichTextResolved | undefined): string {
+  const { key, title, mode, count, picked, items } = relatedPostsView(value, resolved);
+  if (!resolved) {
+    return `<aside data-rt="related" data-key="${esc(key)}" data-mode="${mode}" data-count="${count}" data-posts="${esc(picked.join(","))}"${
+      title ? ` data-title="${esc(title)}"` : ""
+    }></aside>`;
+  }
+  if (!items.length) return "";
+  const list = items.map((p) => `<li><a href="${esc(p.url)}">${esc(p.title)}</a></li>`).join("");
+  return `<aside data-rt="related" data-mode="${mode}" data-count="${count}" data-posts="${esc(picked.join(","))}">${
+    title ? `<p data-title>${esc(title)}</p>` : ""
+  }${list ? `<ul>${list}</ul>` : ""}</aside>`;
+}
+
+/**
+ * RT8: an author bio, V2's `<aside data-rt="author" data-author><img><p data-name>…</p><p data-bio>…</p></aside>`.
+ * The `<img>` writes `src` last, as React does, so both renderers give the same bytes (R6).
+ */
+function authorBioHtml(value: unknown, resolved: RichTextResolved | undefined): string {
+  const { key, id, author } = authorBioView(value, resolved);
+  if (!resolved) return `<aside data-rt="author" data-key="${esc(key)}" data-author="${esc(id)}"></aside>`;
+  if (!author) return "";
+  return `<aside data-rt="author" data-author="${esc(id)}">${author?.avatar ? `<img alt="" src="${esc(author.avatar)}">` : ""}${
+    author ? `<p data-name>${esc(author.name)}</p>` : ""
+  }${author?.bio ? `<p data-bio>${esc(author.bio)}</p>` : ""}</aside>`;
+}
+
+/** RT6: the end list, V2 `renderFootnotes` byte for byte: each note, then a link back to its marker. */
+function footnoteListHtml(notes: readonly string[]): string {
+  if (!notes.length) return "";
+  const items = notes.map((n, i) => `<li id="fn-${i + 1}">${esc(n)} <a href="#fnref-${i + 1}" aria-label="Back to reference ${i + 1}">↩</a></li>`).join("");
+  return `<ol class="cs-footnotes" data-rt="footnotes" aria-label="Footnotes">${items}</ol>`;
+}
+
+/** An h2 or h3 with its outline id, so a table of contents (or any link) can point at it. */
+const headingWithId = (tag: "h2" | "h3", classes: HtmlClasses) =>
+  ({ value, children }: { value: object; children?: string }) => {
+    const id = outline.nodes.get(value);
+    return `<${tag}${id ? ` id="${esc(id)}"` : ""}${cls(classes, tag)}>${children ?? ""}</${tag}>`;
+  };
+
+/**
+ * RT5: a table of contents, V2's `<nav data-rt="toc" data-depth aria-label><p data-title>…</p>
+ * <ol><li><a href="#id">…</a><ol>…</ol></li></ol></nav>`, listing the outline of the value it is in.
+ */
+function tocHtml(value: unknown): string {
+  const { title, label, depth } = tocView(value);
+  const link = (o: OutlineItem) => `<a href="#${esc(o.id)}">${esc(o.text)}</a>`;
+  const items = tocTree(outline.items, depth)
+    .map((e) => `<li>${link(e)}${e.children.length ? `<ol>${e.children.map((c) => `<li>${link(c)}</li>`).join("")}</ol>` : ""}</li>`)
+    .join("");
+  return `<nav data-rt="toc" data-depth="${depth}" aria-label="${esc(label)}">${title ? `<p data-title>${esc(title)}</p>` : ""}<ol>${items}</ol></nav>`;
+}
+
+/**
+ * An X post's card, from the oEmbed data the server fetched (plain strings, escaped here; never
+ * X's markup). Always the blockquote X's widget recognises: it reads as a quote without
+ * JavaScript, and on a site that opted in, the page's one widgets.js (next `BcmsEmbedScripts`)
+ * upgrades it in place. No script here: the html is a function of the value and its cards only,
+ * so turning the opt-in on or off re-bakes no html cache.
+ */
+function xCardHtml(url: string, card: EmbedCard): string {
+  return `<blockquote class="twitter-tweet bcms-embed-card" cite="${esc(url)}"><p>${esc(card.text)}</p>&mdash; ${esc(card.authorName)} <a href="${esc(url)}">${esc(card.date || "View on X")}</a></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): 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>`;
+  // Cards are keyed by the canonical url (`r.url`), so a post pasted two ways finds its card.
+  else if (r.kind === "card" && embeds.cards?.[r.url]) body = xCardHtml(r.url, embeds.cards[r.url]);
+  // 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 canonical url). Absent: every X post is a link card.
+   */
+  embeds?: EmbedRender;
+  /**
+   * RT8: the entries this value's author bios and related posts point at, resolved by the caller
+   * whenever a page is produced; never stored. Absent: each block is a placeholder aside carrying
+   * only what is stored (the stored html cache). Present: a block with nothing to show draws nothing.
+   */
+  resolved?: RichTextResolved;
   /**
    * The site's own class per tag, for a value derived FROM that site.
    *
@@ -480,6 +653,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 +672,27 @@ const buildComponents = (
   classes: HtmlClasses = {},
   binding?: { base: string; keys: ReadonlySet<unknown> },
   renderBlock?: RenderOptions["renderBlock"],
+  embeds: EmbedRender = {},
+  resolved?: RichTextResolved,
 ): Partial<PortableTextHtmlComponents> => ({
-  block: tagOverrides(classes, STYLE_TAGS),
-  list: tagOverrides(classes, { bullet: "ul", number: "ol", check: "ul" }),
+  block: { ...tagOverrides(classes, STYLE_TAGS), h2: headingWithId("h2", classes), h3: headingWithId("h3", classes) },
+  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 +707,12 @@ 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),
+    [PT_TYPES.gallery]: ({ value }) => galleryHtml(value),
+    [PT_TYPES.tableOfContents]: ({ value }) => tocHtml(value),
+    [PT_TYPES.relatedPosts]: ({ value }) => relatedPostsHtml(value, resolved),
+    [PT_TYPES.authorBio]: ({ value }) => authorBioHtml(value, resolved),
+    [PT_TYPES.columns]: ({ value }) => columnsHtml(value, () => buildComponents(classes, undefined, renderBlock, embeds, resolved)),
     /**
      * 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
@@ -526,6 +729,8 @@ const buildComponents = (
       if (v.schemaKey === BUILTIN_EMBED_KEY) return embedHtml(value, classes);
       if (v.schemaKey === BUILTIN_CALLOUT_KEY) return calloutHtml(value);
       if (v.schemaKey === BUILTIN_TOGGLE_KEY) return toggleHtml(value);
+      // A legacy columns block in the shape it was written in reads as columns; any other stays a marker.
+      if (v.schemaKey === BUILTIN_COLUMNS_KEY && columnsView(value)) return columnsHtml(value, () => buildComponents(classes, undefined, renderBlock, embeds, resolved));
       /**
        * A pre-P1c TABLE is the exception to the marker, and it has to be: it resolves against
        * nothing. Its rows are text, held right here, so a marker would DELETE visible content.
@@ -545,6 +750,7 @@ const buildComponents = (
         : "block";
       return `<div class="bcms-block" data-bcms-schema-key="${esc(key)}"></div>`;
     },
+    [PT_TYPES.footnote]: ({ value }) => footnoteMarkHtml(value),
     [PT_TYPES.mention]: ({ value }) => {
       const v = value as { label?: unknown };
       return `<span class="bcms-mention">${esc(typeof v.label === "string" ? v.label : "")}</span>`;
@@ -557,9 +763,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 +781,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.
@@ -617,12 +825,26 @@ export function portableTextToHtml(
   opts: RenderOptions = {},
 ): string {
   if (!Array.isArray(value) || value.length === 0) return "";
+  if (opts.inline) return render(value, opts);
+  const outer = { outline, footnotes };
+  outline = outlineOf(value);
+  footnotes = footnoteOrder(value);
+  try {
+    return render(value, opts) + footnoteListHtml(footnotes.notes);
+  } finally {
+    ({ outline, footnotes } = outer);
+  }
+}
+
+function render(value: PortableText, opts: RenderOptions): string {
   const components =
-    opts.classes || opts.renderBlock ? buildComponents(opts.classes, undefined, opts.renderBlock) : defaultComponents;
+    opts.classes || opts.renderBlock || opts.embeds || opts.resolved
+      ? buildComponents(opts.classes, undefined, opts.renderBlock, opts.embeds, opts.resolved)
+      : 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, opts.resolved);
     const out: string[] = [];
     for (let i = 0; i < value.length; ) {
       const node = value[i];

package/src/image-layout.ts

@@ -1,3 +1,14 @@
+import {
+  focalInCrop,
+  formatImageRect,
+  imageValueUrl,
+  normalizeImageCrop,
+  normalizeImageFocal,
+  objectPosition,
+  parseImageRect,
+  type ImageCrop,
+  type ImageFocal,
+} from "@bettercms-ai/image-url";
 /**
  * Where a rich-text image sits and how wide it is — `align` and `size` on a `builtin:image`
  * block's fields.
@@ -67,3 +78,46 @@ export function richTextImageLayout(fields: Record<string, unknown>): RichTextIm
     figureStyle: `max-width:${maxWidth};margin-left:${ml};margin-right:${mr}`,
   };
 }
+
+/**
+ * RT9: a rich-text image's framing, the platform's own image vocabulary (`@bettercms-ai/image-url`):
+ * `crop`, how much to cut from each edge as 0–1 fractions of the source, and `focal`, a 0–1 point
+ * of the source. Both optional on a `builtin:image`'s fields and on a gallery image.
+ *
+ * The crop is applied the way every lane applies it, through `imageValueUrl` (`?rect=` on a
+ * BetterCMS media url; any other url is drawn uncropped); the focal point is `object-position`
+ * inside that crop. What is stored rides the `<img>` as `data-src` / `data-crop` / `data-focal`
+ * whenever there is a frame, so the ingest reads back exactly what was stored.
+ */
+export interface RichTextImageFrame {
+  /** The url to draw: the stored one, with the crop applied when it can be. */
+  src: string;
+  crop: ImageCrop | null;
+  focal: ImageFocal | null;
+  /** `object-position` for the focal point, or null when there is none. */
+  position: string | null;
+  /** The `data-*` attributes carrying what is stored, in render order; empty when there is no frame. */
+  data: [string, string][];
+}
+
+export function richTextImageFrame(src: string, crop: unknown, focal: unknown): RichTextImageFrame {
+  const c = normalizeImageCrop(crop);
+  const f = normalizeImageFocal(focal);
+  if (!c && !f) return { src, crop: null, focal: null, position: null, data: [] };
+  const drawn = imageValueUrl({ url: src, crop: c, focal: f }) ?? src;
+  const data: [string, string][] = [];
+  if (drawn !== src) data.push(["data-src", src]);
+  if (c) data.push(["data-crop", formatImageRect(c)]);
+  if (f) data.push(["data-focal", `${f.x},${f.y}`]);
+  return { src: drawn, crop: c, focal: f, position: f ? objectPosition(focalInCrop(f, c)) : null, data };
+}
+
+/** The stored framing an `<img>` carries back (`richTextImageFrame`'s `data`), for the ingest. */
+export function readImageFrame(img: { getAttribute(name: string): string | null }): { src: string | null; crop: ImageCrop | null; focal: ImageFocal | null } {
+  const xy = (img.getAttribute("data-focal") ?? "").split(",").map(Number);
+  return {
+    src: img.getAttribute("data-src"),
+    crop: parseImageRect(img.getAttribute("data-crop")),
+    focal: xy.length === 2 ? normalizeImageFocal({ x: xy[0], y: xy[1] }) : null,
+  };
+}

package/src/index.ts

@@ -6,10 +6,17 @@ export * from "./from-lexical";
 export * from "./plain";
 export * from "./table";
 export * from "./key-takeaways";
+export * from "./gallery";
+export * from "./toc";
+export * from "./footnote";
+export * from "./columns";
+export * from "./references";
 export * from "./styled";
 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";