@bettercms-ai/richtext 0.14.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/richtext",
-  "version": "0.14.0",
+  "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,7 +26,8 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@bettercms-ai/types": "^1.55.0",
+    "@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"

package/src/accept.ts

@@ -30,9 +30,9 @@ export const CORE_ELEMENTS = RICHTEXT_CORE_ELEMENTS
 export const ADVANCED_ELEMENTS = RICHTEXT_ADVANCED_ELEMENTS
 
 /**
- * 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.
+ * 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
 
@@ -61,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.
 ]
@@ -88,7 +90,7 @@ 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
+  // 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.
@@ -97,7 +99,11 @@ const ELEMENT_TAGS: Record<AcceptElement, string[]> = {
   gallery: ['figure', 'ul', 'li', 'img', 'figcaption'],
   // RT5: the contents' nav, its title and its (nested) list of links.
   tableOfContents: ['nav', 'p', 'ol', 'li', 'a'],
-  relatedPosts: [], authorBio: [], footnotes: [],
+  // 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'],
 }
@@ -116,7 +122,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', ...BLOCK_ELEMENTS])
+const NEW_AUTHORING_EXCLUSIONS = new Set<AcceptElement>(['internalLink', 'rtl'])
 
 /** New defaults contain every capability whose complete consumer pipeline is currently live. */
 export const DEFAULT_ACCEPT: AcceptElement[] = ALL_ELEMENTS.filter(

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/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;
+}

package/src/gallery.ts

@@ -1,6 +1,7 @@
 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
@@ -27,7 +28,8 @@ export type PortableTextGalleryProblem = { path: Array<string | number>; code: s
 
 const KEYS = new Set(["_type", "_key", "layout", "images"]);
 const ITEM_KEYS = new Set(["_key", "image", "caption"]);
-const IMAGE_KEYS = new Set(["src", "alt", "mediaId"]);
+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
@@ -63,6 +65,18 @@ export function galleryProblems(node: unknown): PortableTextGalleryProblem[] {
     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");
@@ -128,17 +142,23 @@ export const GALLERY_STYLES: Record<GalleryLayout, { ul: string; li: string; fig
  * `renderArticle("gallery")` leaves it out. Read defensively: a value that never passed the write
  * check renders what it can.
  */
-export function galleryView(value: unknown): { layout: GalleryLayout; images: { key: string; src: string; alt: string; caption: string }[] } {
+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: { key: string; src: string; alt: string; caption: string }[] = [];
+  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,
+      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() : "",
     });

package/src/html.ts

@@ -14,10 +14,14 @@ 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";
 
 /**
@@ -282,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)}"` : ""
@@ -434,7 +442,9 @@ 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}" loading="lazy" src="${esc(x.src)}">${
+    .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("");
@@ -448,6 +458,75 @@ function galleryHtml(value: unknown): string {
  * 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) =>
@@ -511,9 +590,15 @@ export interface RenderOptions {
   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.
+   * 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.
    *
@@ -588,6 +673,7 @@ const buildComponents = (
   binding?: { base: string; keys: ReadonlySet<unknown> },
   renderBlock?: RenderOptions["renderBlock"],
   embeds: EmbedRender = {},
+  resolved?: RichTextResolved,
 ): Partial<PortableTextHtmlComponents> => ({
   block: { ...tagOverrides(classes, STYLE_TAGS), h2: headingWithId("h2", classes), h3: headingWithId("h3", classes) },
   list: {
@@ -624,6 +710,9 @@ const buildComponents = (
     [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
@@ -640,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.
@@ -659,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>`;
@@ -734,24 +826,25 @@ export function portableTextToHtml(
 ): string {
   if (!Array.isArray(value) || value.length === 0) return "";
   if (opts.inline) return render(value, opts);
-  const outer = outline;
+  const outer = { outline, footnotes };
   outline = outlineOf(value);
+  footnotes = footnoteOrder(value);
   try {
-    return render(value, opts);
+    return render(value, opts) + footnoteListHtml(footnotes.notes);
   } finally {
-    outline = outer;
+    ({ outline, footnotes } = outer);
   }
 }
 
 function render(value: PortableText, opts: RenderOptions): string {
   const components =
-    opts.classes || opts.renderBlock || opts.embeds
-      ? buildComponents(opts.classes, undefined, opts.renderBlock, opts.embeds)
+    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, opts.embeds);
+    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

@@ -8,6 +8,9 @@ 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";