@bettercms-ai/richtext 0.14.0 → 0.17.0

package/src/ingest.ts

@@ -14,13 +14,15 @@ import {
   type PortableTextTableRow,
 } from "./types";
 import { randomKey, isValidKey, type KeyGenerator } from "./key";
-import { safeHref } from "./href";
+import { readLinkRel, safeHref } from "./href";
 import { BARE_IS_DESIGN, isStyledTag, styledAttrsOf, type StyledMarkDef } from "./styled";
 import { EMBED_TITLE_MAX, isEmbedAspect, nearestEmbedAspect, resolveEmbed } from "./embed";
 import { cellTypeOf, columnOf, designOf, isColumnType, isValueType, jsonLdOf, PT_TABLE_LIMITS, typedCellText } from "./table";
 import { PT_KEY_TAKEAWAYS_LIMITS } from "./key-takeaways";
 import { PT_GALLERY_LIMITS } from "./gallery";
-import { PT_TOC_LIMITS } from "./toc";
+import { PT_TOC_LIMITS, isHeadingAnchor, outlineOf } from "./toc";
+import { PT_RELATED_LIMITS } from "./references";
+import { readImageFrame } from "./image-layout";
 import type { PtSchema } from "./schema";
 
 /**
@@ -63,6 +65,14 @@ export interface IngestOptions {
    * the allowlist grows from.
    */
   onReceipt?: (line: string) => void;
+  /**
+   * RT9: keep a top-level h2/h3's own `id` as the block's `anchor` (only when it differs from the
+   * id its words make). OFF by default, because a value stored before anchors existed was read
+   * without them: a comparison of such a value with its page must read the page the same way, or
+   * an unedited page reads as changed (R15). An import turns it on; a comparison turns it on only
+   * when the stored value has an anchor (`hasHeadingAnchors`).
+   */
+  headingAnchors?: boolean;
 }
 
 /**
@@ -608,6 +618,58 @@ function checklistItemRule(schema: PtSchema | undefined): DeserializerRule {
   };
 }
 
+/**
+ * RT8: `<aside data-rt="related">` → `relatedPosts` and `<aside data-rt="author">` → `authorBio`, the
+ * inverses of their renderers and of V2's markup. Only what is stored is read: the title (≤ 40),
+ * the mode (V2's "auto" is "topic"; else "newest" or "manual"), the count (V2 clamps it to 1–6,
+ * default 3) and the picks (`data-posts`); the author's id (`data-author`). The listed posts and
+ * the author's name, avatar and bio are resolved at render and ignored.
+ */
+function referenceRule(key: KeyGenerator, schema: PtSchema | undefined): DeserializerRule {
+  const related = allowsBlockObject(schema, PT_TYPES.relatedPosts);
+  const author = allowsBlockObject(schema, PT_TYPES.authorBio);
+  return {
+    deserialize(el: Node, _next, createBlock) {
+      if (!isElement(el) || el.nodeName.toLowerCase() !== "aside") return undefined;
+      const rt = el.getAttribute("data-rt");
+      if (rt === "related" && related) {
+        // Our placeholder (no `resolved`) carries the title as an attribute; a filled aside, and V2's, as `[data-title]`.
+        const title = (el.getAttribute("data-title") ?? el.querySelector("[data-title]")?.textContent ?? "").replace(/\s+/g, " ").trim().slice(0, PT_RELATED_LIMITS.titleChars);
+        const m = el.getAttribute("data-mode");
+        const mode = m === "manual" || m === "newest" ? m : "topic";
+        const count = Math.min(PT_RELATED_LIMITS.maxCount, Math.max(PT_RELATED_LIMITS.minCount, Math.trunc(Number(el.getAttribute("data-count"))) || 3));
+        const posts = (el.getAttribute("data-posts") ?? "").split(",").map((id) => id.trim()).filter(Boolean).map((_ref) => ({ _key: key(), _ref }));
+        return createBlock({ _type: PT_TYPES.relatedPosts, _key: key(), ...(title ? { title } : {}), mode, count, posts });
+      }
+      if (rt === "author" && author) {
+        const id = (el.getAttribute("data-author") ?? "").trim();
+        return createBlock({ _type: PT_TYPES.authorBio, _key: key(), ...(id ? { author: { _ref: id } } : {}) });
+      }
+      return undefined;
+    },
+  };
+}
+
+/**
+ * RT7: `<div data-rt="columns" data-gap>` → the `columns` block, the inverse of `columnsHtml` and
+ * of V2's own markup: one column per `[data-col]` child, its html read with the same options as
+ * the body (the field's schema too), and the gap (s, m, l; else m). The count is derived. Nothing
+ * is dropped here: a column holding more than text, or a count outside 2 to 4, is the write check's
+ * to refuse by name.
+ */
+function columnsRule(key: KeyGenerator, inner: (html: string) => PortableText): DeserializerRule {
+  return {
+    deserialize(el: Node, _next, createBlock) {
+      if (!isElement(el) || el.nodeName.toLowerCase() !== "div" || el.getAttribute("data-rt") !== "columns") return undefined;
+      const g = el.getAttribute("data-gap");
+      const columns = Array.from(el.children)
+        .filter((c) => c.hasAttribute("data-col"))
+        .map((c) => ({ _key: key(), content: inner(c.innerHTML) }));
+      return createBlock({ _type: PT_TYPES.columns, _key: key(), gap: g === "s" || g === "l" ? g : "m", columns });
+    },
+  };
+}
+
 /**
  * RT5: `<nav data-rt="toc" data-depth>` → the `tableOfContents` block, the inverse of `tocHtml`
  * and of V2's own markup. Only what is stored is read: the title (`[data-title]`, ≤ 40, none when
@@ -637,9 +699,17 @@ function galleryFigureRule(key: KeyGenerator): DeserializerRule {
       const images = Array.from(el.querySelectorAll("li")).map((li) => {
         const img = li.querySelector("img");
         const caption = (li.querySelector("figcaption")?.textContent ?? "").trim().slice(0, PT_GALLERY_LIMITS.captionChars);
+        const frame = img ? readImageFrame(img) : null;
         return {
           _key: key(),
-          image: img ? { src: (img.getAttribute("src") ?? "").trim(), alt: img.getAttribute("alt") ?? "" } : null,
+          image: img
+            ? {
+                src: frame?.src ?? (img.getAttribute("src") ?? "").trim(),
+                alt: img.getAttribute("alt") ?? "",
+                ...(frame?.crop ? { crop: frame.crop } : {}),
+                ...(frame?.focal ? { focal: frame.focal } : {}),
+              }
+            : null,
           ...(caption ? { caption } : {}),
         };
       });
@@ -685,45 +755,39 @@ function buttonLinkRule(key: KeyGenerator, schema: PtSchema | undefined): Deseri
       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 } : {}),
-      };
+      const markDef = { _type: PT_TYPES.link, _key: key(), href, button: true, ...linkExtras(el) };
       return { _type: "__annotation", markDef, children: next(el.childNodes) } as never;
     },
   };
 }
 
 /**
- * `<a class>` → a `link` annotation that keeps the site's class as `className`.
+ * What an `<a>` stores beyond its href: the site's class, a new tab (only `_blank`) and its
+ * `rel` (author tokens; the noopener/noreferrer a new tab adds on render are not kept).
+ */
+function linkExtras(el: Element): { className?: string; target?: "_blank"; rel?: string } {
+  const className = el.getAttribute("class")?.trim();
+  const blank = el.getAttribute("target")?.trim().toLowerCase() === "_blank";
+  const rel = readLinkRel(el.getAttribute("rel"), blank);
+  return { ...(className ? { className } : {}), ...(blank ? { target: "_blank" } : {}), ...(rel ? { rel } : {}) };
+}
+
+/**
+ * `<a class>`, `<a target="_blank">`, `<a rel>` → a `link` annotation that keeps them.
  *
  * The built-in link rule records `href` and nothing else, so a styled link (`<a class="underline
- * text-brand">`) came back bare and the design died on ingest. Only a link WITH a class takes
- * this rule; a plain link still goes to the built-in one. `href` is checked by `normalise`.
+ * text-brand">`) came back bare and the design died on ingest, and a link's new tab and its
+ * `nofollow` (V2's link form writes both) were lost the same way. Only a link carrying one of
+ * them takes this rule; a bare link still goes to the built-in one. `href` is checked by `normalise`.
  */
-function classedLinkRule(key: KeyGenerator): DeserializerRule {
+function linkRule(key: KeyGenerator): DeserializerRule {
   return {
     deserialize(el: Node, next) {
       if (!isElement(el) || el.nodeName.toLowerCase() !== "a") return undefined;
-      const className = el.getAttribute("class")?.trim();
       const href = el.getAttribute("href")?.trim();
-      if (!className || !href) return undefined;
-      const rel = el.getAttribute("rel")?.trim();
-      const markDef = {
-        _type: PT_TYPES.link,
-        _key: key(),
-        href,
-        className,
-        ...(el.getAttribute("target") === "_blank" ? { target: "_blank" } : {}),
-        ...(rel ? { rel } : {}),
-      };
+      const extras = linkExtras(el);
+      if (!href || !Object.keys(extras).length) return undefined;
+      const markDef = { _type: PT_TYPES.link, _key: key(), href, ...extras };
       return { _type: "__annotation", markDef, children: next(el.childNodes) } as never;
     },
   };
@@ -852,14 +916,18 @@ function mediaRule(key: KeyGenerator, schema: PtSchema | undefined, onReceipt?:
           fields: { url: src, ...(title ? { title } : {}) },
         });
       }
+      // RT9: an image we drew with a crop or focal point carries what was stored back.
+      const frame = readImageFrame(el);
       return createBlock({
         _type: PT_TYPES.block,
         _key: key(),
         schemaKey: BUILTIN_IMAGE_KEY,
         fields: {
-          src,
+          src: frame.src ?? src,
           alt: (el.getAttribute("alt") ?? "").trim(),
           ...(caption ? { caption } : {}),
+          ...(frame.crop ? { crop: frame.crop } : {}),
+          ...(frame.focal ? { focal: frame.focal } : {}),
         },
       });
     },
@@ -1001,6 +1069,104 @@ const allowsStyled = (schema: PtSchema | undefined): boolean =>
 const allowsBlockObject = (schema: PtSchema | undefined, name: string): boolean =>
   !schema || schema.blockObjects.some((o) => o.name === name);
 
+const words = (s: string): string => s.replace(/\u200b/g, "").replace(/\s+/g, " ").trim();
+
+/**
+ * RT9: each top-level h2/h3 of the page being read, in order, with its own `id` ("" when none or
+ * not a plain id). The words exclude a footnote marker, as the stored heading's do.
+ */
+const withHeadingIds =
+  (parse: (html: string) => Document, into: { text: string; id: string }[]) =>
+  (html: string): Document => {
+    const doc = parse(html);
+    for (const h of Array.from(doc.body.querySelectorAll(":scope > h2, :scope > h3"))) {
+      const copy = h.cloneNode(true) as Element;
+      copy.querySelectorAll("sup").forEach((s) => s.remove());
+      const id = h.getAttribute("id") ?? "";
+      into.push({ text: words(copy.textContent ?? ""), id: isHeadingAnchor(id) ? id : "" });
+    }
+    return doc;
+  };
+
+/**
+ * RT9: an imported heading keeps its page's id as `anchor`, so the site's own links to it keep
+ * working, but only when it differs from the id its words make: our own markup reads back with
+ * no anchor at all, and a heading's id follows its words unless the page said otherwise.
+ */
+function keepHeadingIds(value: PortableText, ids: { text: string; id: string }[]): PortableText {
+  if (!ids.some((h) => h.id)) return value;
+  const heads = value.filter(
+    (n): n is PortableTextBlock => n._type === "block" && !(n as PortableTextBlock).listItem && ((n as PortableTextBlock).style === "h2" || (n as PortableTextBlock).style === "h3"),
+  );
+  let at = 0;
+  const marked: PortableTextBlock[] = [];
+  for (const head of heads) {
+    const text = words(head.children.map((c) => (typeof (c as { text?: unknown }).text === "string" ? (c as { text: string }).text : "")).join(""));
+    while (at < ids.length && ids[at].text !== text) at++;
+    if (at >= ids.length) break;
+    if (ids[at].id) {
+      head.anchor = ids[at].id;
+      marked.push(head);
+    }
+    at++;
+  }
+  // The ids the words alone would make: an anchor equal to its heading's is not kept.
+  const set = new Set<unknown>(marked);
+  const plain = value.map((n) => (set.has(n) ? { ...n, anchor: undefined } : n));
+  const auto = outlineOf(plain).nodes;
+  value.forEach((n, i) => {
+    if (set.has(n) && auto.get(plain[i]) === (n as PortableTextBlock).anchor) delete (n as PortableTextBlock).anchor;
+  });
+  return value;
+}
+
+const allowsInlineObject = (schema: PtSchema | undefined, name: string): boolean =>
+  !schema || schema.inlineObjects.some((o) => o.name === name);
+
+/**
+ * RT6: V2's end list (`<ol data-rt="footnotes">`, or a legacy `ol.cs-footnotes`) is derived, so it
+ * is dropped before the deserialiser sees it (V2 `hydrate`). A legacy marker that kept its note only
+ * in the list (`<sup id="fnref-N">`, no `data-note`) is lent that note first.
+ */
+const withFootnoteNotes =
+  (parse: (html: string) => Document) =>
+  (html: string): Document => {
+    const doc = parse(html);
+    const lists = Array.from(doc.body.querySelectorAll(":scope > ol[data-rt=footnotes], :scope > ol.cs-footnotes"));
+    if (lists.length === 0) return doc;
+    const legacy: Record<number, string> = {};
+    for (const ol of lists) {
+      for (const li of Array.from(ol.querySelectorAll(":scope > li[id^='fn-']"))) {
+        const n = Number(li.id.slice(3));
+        const copy = li.cloneNode(true) as Element;
+        copy.querySelectorAll("a[href^='#fnref-']").forEach((a) => a.remove());
+        if (n) legacy[n] = (copy.textContent ?? "").replace(/\u200b/g, "").trim();
+      }
+      ol.remove();
+    }
+    for (const sup of Array.from(doc.body.querySelectorAll("sup[data-rt=fn], sup[id^='fnref-']"))) {
+      if (sup.hasAttribute("data-note")) continue;
+      const n = Number(sup.id.replace("fnref-", "")) || Number(sup.textContent) || 0;
+      sup.setAttribute("data-note", legacy[n] ?? "");
+    }
+    return doc;
+  };
+
+/**
+ * RT6: a footnote marker, ours or V2's `<sup data-rt="fn" data-note>` (or a legacy `<sup
+ * id="fnref-N">`) → the `footnote` inline object. Only the note is read: the number, the ids and
+ * the link inside are derived.
+ */
+function footnoteRule(key: KeyGenerator): DeserializerRule {
+  return {
+    deserialize(el: Node) {
+      if (!isElement(el) || el.nodeName.toLowerCase() !== "sup") return undefined;
+      if (el.getAttribute("data-rt") !== "fn" && !(el.getAttribute("id") ?? "").startsWith("fnref-")) return undefined;
+      return { _type: PT_TYPES.footnote, _key: key(), note: el.getAttribute("data-note") ?? "" } as never;
+    },
+  };
+}
+
 const isElement = (n: unknown): n is Element =>
   !!n && typeof n === "object" && (n as Node).nodeType === 1;
 
@@ -1032,11 +1198,18 @@ const withoutBlockWhitespace =
 export function htmlToPortableText(html: string, opts: IngestOptions = {}): PortableText {
   if (typeof html !== "string" || html.trim() === "") return [];
   const key = opts.keyGenerator ?? randomKey;
+  const headingIds: { text: string; id: string }[] = [];
   const parse =
     opts.parseHtml ?? (typeof DOMParser !== "undefined" ? (markup: string) => new DOMParser().parseFromString(markup, "text/html") : undefined);
   const converted = ptHtmlToPortableText(html, {
     // The browser's own parser when none is passed (Node must pass one), so both drop the same whitespace.
-    ...(parse ? { parseHtml: withoutBlockWhitespace(parse) } : {}),
+    ...(parse
+      ? {
+          parseHtml: ((p) => (opts.headingAnchors ? withHeadingIds(p, headingIds) : p))(
+            allowsInlineObject(opts.schema, PT_TYPES.footnote) ? withFootnoteNotes(withoutBlockWhitespace(parse)) : withoutBlockWhitespace(parse),
+          ),
+        }
+      : {}),
     // `ptSchemaFor` returns a schema DEFINITION — the same object `EditorProvider` takes, so
     // the editor and this filter are literally configured from one value. The deserialiser
     // wants the COMPILED form, so the compile happens here rather than at every call site.
@@ -1059,23 +1232,27 @@ export function htmlToPortableText(html: string, opts: IngestOptions = {}): Port
       ...(allowsBlockObject(opts.schema, PT_TYPES.table)
         ? [tableFigureRule(key, (cell) => htmlToPortableText(cell, opts)), tableRule(key, (cell) => htmlToPortableText(cell, opts))]
         : []),
+      ...(allowsInlineObject(opts.schema, PT_TYPES.footnote) ? [footnoteRule(key)] : []),
       ...(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 (and an image out of a gallery).
       ...(allowsBlockObject(opts.schema, PT_TYPES.gallery) ? [galleryFigureRule(key)] : []),
       ...(allowsBlockObject(opts.schema, PT_TYPES.tableOfContents) ? [tocRule(key)] : []),
+      referenceRule(key, opts.schema),
+      ...(allowsBlockObject(opts.schema, PT_TYPES.columns) ? [columnsRule(key, (inner) => htmlToPortableText(inner, opts))] : []),
       embedFigureRule(key, opts.schema),
       mediaRule(key, opts.schema, opts.onReceipt),
       checklistItemRule(opts.schema),
       ownDecoratorRule(opts.schema),
       ...(allowsStyled(opts.schema) ? [styledRule(key)] : []),
       buttonLinkRule(key, opts.schema),
-      ...(allowsLinks(opts.schema) ? [classedLinkRule(key)] : []),
+      ...(allowsLinks(opts.schema) ? [linkRule(key)] : []),
     ],
     keyGenerator: key,
   });
-  return normalise(converted, key);
+  const value = normalise(converted, key);
+  return opts.headingAnchors ? keepHeadingIds(value, headingIds) : value;
 }
 
 /**

package/src/plain.ts

@@ -2,6 +2,7 @@ import { isPortableTextBlock, isPortableTextSpan, PT_TYPES, type PortableText, t
 import { migrateTable, tableGroupLayout } from "./table";
 import { keyTakeawaysView } from "./key-takeaways";
 import { galleryView } from "./gallery";
+import { columnsView } from "./columns";
 import { componentCopyLines, detachedComponentCopy } from "./component-copy";
 
 /**
@@ -55,6 +56,15 @@ export function portableTextToPlainText(value: PortableText | null | undefined):
       lines.push(...galleryView(node).images.map((x) => x.caption).filter(Boolean));
       continue;
     }
+    /** A column's text is words a reader sees, in column order (a legacy `builtin:columns` too). */
+    const cols = columnsView(node);
+    if (cols) {
+      for (const c of cols.columns) {
+        const text = portableTextToPlainText(c.content);
+        if (text) lines.push(text);
+      }
+      continue;
+    }
     const table = migrateTable(node);
     if (table) {
       lines.push(...tableLines(table));

package/src/read.ts

@@ -3,7 +3,8 @@ import { lexicalToPortableText } from "./from-lexical";
 import { migrateTable } from "./table";
 import { detachedComponentCopy, type DetachedComponentCopy } from "./component-copy";
 import { randomKey, type KeyGenerator } from "./key";
-import type { EmbedCard, RichTextEmbeds } from "@bettercms-ai/types";
+import type { EmbedCard, ResolvedAuthor, ResolvedPost, RichTextEmbeds, RichTextResolved } from "@bettercms-ai/types";
+import type { ClassTag, HtmlClasses } from "./html";
 
 /**
  * THE reader. One function, every stored shape, and it never throws.
@@ -298,3 +299,60 @@ export function embeddedComponentRender(
   const copy = detachedComponentCopy(value);
   return copy ? { kind: "copy", copy } : null;
 }
+
+const strings = <K extends string>(o: Record<string, unknown>, keys: readonly K[]): Partial<Record<K, string>> =>
+  Object.fromEntries(keys.filter((k) => typeof o[k] === "string").map((k) => [k, o[k]])) as Partial<Record<K, string>>;
+
+/**
+ * RT8 (G-RT8): the entries a DELIVERED value's author bios and related posts point at, which the
+ * delivery puts beside the value (`value.resolved`); undefined when there are none. Never read from
+ * a stored envelope: nothing stores it. Checked, not trusted: a post keeps only its string fields
+ * and needs a title and url, an author a name, and `related` only lists of ids.
+ */
+export function readStructuredResolved(props: unknown): RichTextResolved | undefined {
+  if (!isRecord(props)) return undefined;
+  const candidate = props.content ?? props.value;
+  const raw = isRecord(candidate) ? candidate.resolved : undefined;
+  if (!isRecord(raw)) return undefined;
+  const posts: Record<string, ResolvedPost> = {};
+  if (isRecord(raw.posts)) {
+    for (const [id, p] of Object.entries(raw.posts)) {
+      if (isRecord(p) && typeof p.title === "string" && typeof p.url === "string") {
+        posts[id] = { title: p.title, url: p.url, ...strings(p, ["cover", "category"] as const) };
+      }
+    }
+  }
+  const authors: Record<string, ResolvedAuthor> = {};
+  if (isRecord(raw.authors)) {
+    for (const [id, a] of Object.entries(raw.authors)) {
+      if (isRecord(a) && typeof a.name === "string") authors[id] = { name: a.name, ...strings(a, ["avatar", "bio", "url"] as const) };
+    }
+  }
+  const related: Record<string, string[]> = {};
+  if (isRecord(raw.related)) {
+    for (const [key, ids] of Object.entries(raw.related)) {
+      if (Array.isArray(ids)) related[key] = ids.filter((id): id is string => typeof id === "string");
+    }
+  }
+  return { posts, authors, related };
+}
+
+/** Every tag a caller may class (html.ts `ClassTag`); a Record so a tag added there must be added here. */
+const CLASS_TAGS = Object.keys({
+  p: 1, h1: 1, h2: 1, h3: 1, h4: 1, h5: 1, h6: 1, ul: 1, ol: 1, li: 1, a: 1, img: 1, figure: 1, blockquote: 1,
+} satisfies Record<ClassTag, 1>) as ClassTag[];
+
+/**
+ * The site's own class per tag for a DELIVERED value (`value.classes`, the field's
+ * `config.htmlClasses`, which the delivery puts beside the value); undefined when there are none.
+ * Checked, not trusted: only the tags a renderer dresses, with non-empty string classes.
+ */
+export function readStructuredClasses(props: unknown): HtmlClasses | undefined {
+  if (!isRecord(props)) return undefined;
+  const candidate = props.content ?? props.value;
+  const raw = isRecord(candidate) ? candidate.classes : undefined;
+  if (!isRecord(raw)) return undefined;
+  const out: HtmlClasses = {};
+  for (const tag of CLASS_TAGS) if (typeof raw[tag] === "string" && raw[tag]) out[tag] = raw[tag] as string;
+  return Object.keys(out).length ? out : undefined;
+}

package/src/references.ts

@@ -0,0 +1,147 @@
+import type { ResolvedAuthor, ResolvedPost, RichTextResolved } from "@bettercms-ai/types";
+import { PT_TYPES } from "./types";
+import { safeHref } from "./href";
+
+/**
+ * RT8: the two blocks that point at entries. An author bio stores its author as a reference;
+ * related posts store a title, a mode, a count and (hand-picked) references. What a reader sees
+ * of the entries (names, titles, urls, covers, bios) is derived, and NEVER stored (G-RT8): the
+ * caller resolves it whenever a page is produced (delivery, the hosted apply, a draft preview) and
+ * passes `RichTextResolved` in. The renderers never fetch. Three branches, the same on both:
+ *   - no `resolved` at all: a placeholder aside carrying only what is stored, so a stored html
+ *     cache stays a pure function of the value and reads back exactly;
+ *   - resolved, nothing to show (no post resolves, the author is missing): nothing;
+ *   - resolved: V2's aside, filled.
+ */
+export const PT_RELATED_LIMITS = { titleChars: 40, minCount: 1, maxCount: 6, posts: 6 } as const;
+export const RELATED_MODES = ["topic", "newest", "manual"] as const;
+export type RelatedMode = (typeof RELATED_MODES)[number];
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  !!v && typeof v === "object" && !Array.isArray(v);
+const refOf = (v: unknown): string => (isRecord(v) && typeof v._ref === "string" ? v._ref : "");
+
+/** The same widened check a rich-text image gets: http(s), or a site-relative path. */
+const imageSrc = (raw: string): string | null =>
+  safeHref(raw) ?? (raw !== "" && !raw.startsWith("//") && !/[:\s]/.test(raw) ? raw : null);
+
+/**
+ * What a reader sees of a related-posts block: its title, mode and count, the hand-picked ids
+ * (V2's `data-posts`), and the posts to list, in order: the block's own `posts` when manual,
+ * else the ids the server chose (`resolved.related[_key]`), at most `count`. An id the server
+ * could not resolve (deleted, unpublished) is skipped, and so is a post whose url is refused.
+ */
+export function relatedPostsView(value: unknown, resolved: RichTextResolved = {}) {
+  const v = isRecord(value) ? value : {};
+  const title = typeof v.title === "string" ? v.title.trim() : "";
+  const mode: RelatedMode = v.mode === "manual" || v.mode === "newest" ? v.mode : "topic";
+  const n = typeof v.count === "number" && Number.isInteger(v.count) ? v.count : 3;
+  const count = Math.min(PT_RELATED_LIMITS.maxCount, Math.max(PT_RELATED_LIMITS.minCount, n));
+  const picked = (Array.isArray(v.posts) ? v.posts : []).map(refOf).filter(Boolean);
+  const key = typeof v._key === "string" ? v._key : "";
+  const ids = mode === "manual" ? picked : (resolved.related?.[key] ?? []).slice(0, count);
+  const items: (ResolvedPost & { id: string })[] = [];
+  for (const id of ids) {
+    const post = resolved.posts?.[id];
+    const url = post && typeof post.url === "string" ? safeHref(post.url) : null;
+    if (post && typeof post.title === "string" && url) items.push({ ...post, id, url });
+  }
+  return { key, title, mode, count, picked, items };
+}
+
+/** What a reader sees of an author bio: the referenced id, and the author when the server resolved one. */
+export function authorBioView(value: unknown, resolved: RichTextResolved = {}): { key: string; id: string; author: (ResolvedAuthor & { avatar?: string }) | null } {
+  const key = isRecord(value) && typeof value._key === "string" ? value._key : "";
+  const id = refOf(isRecord(value) ? value.author : undefined);
+  const a = id ? resolved.authors?.[id] : undefined;
+  if (!a || typeof a.name !== "string") return { key, id, author: null };
+  const avatar = typeof a.avatar === "string" ? imageSrc(a.avatar.trim()) : null;
+  return {
+    key,
+    id,
+    author: {
+      name: a.name,
+      ...(avatar ? { avatar } : {}),
+      ...(typeof a.bio === "string" && a.bio.trim() ? { bio: a.bio.trim() } : {}),
+    },
+  };
+}
+
+/** One reason a stored author bio or related-posts block is refused, with its block key. */
+export type PortableTextReferenceProblem = { block: string; path: Array<string | number>; code: string; message: string };
+
+/**
+ * Every reason a value's author bios and related posts cannot be stored, by block and path:
+ * `author_bio_invalid`, `related_posts_invalid` (a shape problem, a duplicated pick) or
+ * `related_posts_limit_exceeded` (V2's 40-character title, 1 to 6, at most 6 picks). As with key
+ * takeaways, V2's required author and its "at least one pick" are the editor's, not the write's:
+ * an author still choosing must be able to autosave. Derived keys are refused by R8, by name.
+ */
+export function portableTextReferenceProblems(value: unknown): PortableTextReferenceProblem[] {
+  const out: PortableTextReferenceProblem[] = [];
+  for (const node of Array.isArray(value) ? value : []) {
+    if (!isRecord(node)) continue;
+    const block = typeof node._key === "string" ? node._key : "";
+    const bad = (path: Array<string | number>, code: string, message: string) => out.push({ block, path, code, message: `${code}: ${message}` });
+    if (node._type === PT_TYPES.authorBio) {
+      // name, avatar and bio are derived: R8 refuses them by name.
+      for (const k of Object.keys(node)) if (!["_type", "_key", "author", "name", "avatar", "bio", "resolved"].includes(k)) bad([k], "author_bio_invalid", `unknown key "${k}" (author)`);
+      if (node.author !== undefined && (!isRecord(node.author) || typeof node.author._ref !== "string" || !node.author._ref)) {
+        bad(["author"], "author_bio_invalid", "author must be a reference { _ref }");
+      }
+    }
+    if (node._type === PT_TYPES.relatedPosts) {
+      const keys = ["_type", "_key", "title", "mode", "count", "posts", "resolved"];
+      for (const k of Object.keys(node)) if (!keys.includes(k)) bad([k], "related_posts_invalid", `unknown key "${k}" (title, mode, count, posts)`);
+      if (node.title !== undefined) {
+        if (typeof node.title !== "string") bad(["title"], "related_posts_invalid", "title must be a string");
+        else if (node.title.length > PT_RELATED_LIMITS.titleChars) {
+          bad(["title"], "related_posts_limit_exceeded", `title is ${node.title.length} characters; at most ${PT_RELATED_LIMITS.titleChars}`);
+        }
+      }
+      if (!(RELATED_MODES as readonly unknown[]).includes(node.mode)) bad(["mode"], "related_posts_invalid", 'mode must be "topic", "newest" or "manual"');
+      if (typeof node.count !== "number" || !Number.isInteger(node.count) || node.count < PT_RELATED_LIMITS.minCount || node.count > PT_RELATED_LIMITS.maxCount) {
+        bad(["count"], "related_posts_limit_exceeded", `count must be a whole number from ${PT_RELATED_LIMITS.minCount} to ${PT_RELATED_LIMITS.maxCount}`);
+      }
+      // Absent is no picks (an automatic block needs none).
+      if (node.posts === undefined) continue;
+      if (!Array.isArray(node.posts)) {
+        bad(["posts"], "related_posts_invalid", "posts must be an array of references");
+        continue;
+      }
+      const seen = new Set<string>();
+      node.posts.forEach((p, i) => {
+        const ref = refOf(p);
+        if (!ref || !isRecord(p) || typeof p._key !== "string") return bad(["posts", i], "related_posts_invalid", "a post is { _key, _ref }");
+        // A post's title, slug, url, cover and category are derived: R8 refuses them by name.
+        for (const k of Object.keys(p)) if (!["_key", "_ref", "title", "slug", "url", "cover", "category"].includes(k)) bad(["posts", i, k], "related_posts_invalid", `unknown key "${k}" (_ref)`);
+        if (seen.has(ref)) bad(["posts", i], "related_posts_invalid", `"${ref}" is picked twice`);
+        seen.add(ref);
+      });
+      if (node.posts.length > PT_RELATED_LIMITS.posts) {
+        bad(["posts"], "related_posts_limit_exceeded", `${node.posts.length} posts; at most ${PT_RELATED_LIMITS.posts}`);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * `relatedPosts.no_topic_field`: a `topic` block in a collection with no topic field has nothing to
+ * rank by, so it is refused by name rather than quietly listing nothing. The caller knows the
+ * collection's config and says whether it has one.
+ */
+export function relatedPostsTopicProblems(value: unknown, opts: { topicField: boolean }): PortableTextReferenceProblem[] {
+  if (opts.topicField) return [];
+  const out: PortableTextReferenceProblem[] = [];
+  for (const node of Array.isArray(value) ? value : []) {
+    if (!isRecord(node) || node._type !== PT_TYPES.relatedPosts || node.mode !== "topic") continue;
+    out.push({
+      block: typeof node._key === "string" ? node._key : "",
+      path: ["mode"],
+      code: "relatedPosts.no_topic_field",
+      message: "relatedPosts.no_topic_field: the collection has no topic field to rank related posts by; choose newest or hand-picked",
+    });
+  }
+  return out;
+}

package/src/schema.ts

@@ -111,6 +111,9 @@ export function ptSchemaFor(accept: readonly AcceptElement[]): PtSchema {
       fields: [
         { name: "href", type: "string" },
         { name: "target", type: "string" },
+        // The author's link-type tokens (V2's link form: nofollow, sponsored, ugc); a new tab's
+        // noopener/noreferrer are the renderer's and are not stored (href.ts `readLinkRel`).
+        { name: "rel", 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
@@ -248,6 +251,33 @@ export function ptSchemaFor(accept: readonly AcceptElement[]): PtSchema {
       ],
     });
   }
+  // RT7: columns of text; the generic block above still carries a legacy `builtin:columns`.
+  if (has("columns")) {
+    blockObjects.push({
+      name: PT_TYPES.columns,
+      title: "Columns",
+      fields: [
+        { name: "gap", type: "string" },
+        { name: "columns", type: "object" },
+      ],
+    });
+  }
+  // RT8: the two reference blocks; what they point at is resolved at render (references.ts).
+  if (has("authorBio")) {
+    blockObjects.push({ name: PT_TYPES.authorBio, title: "Author bio", fields: [{ name: "author", type: "object" }] });
+  }
+  if (has("relatedPosts")) {
+    blockObjects.push({
+      name: PT_TYPES.relatedPosts,
+      title: "Related posts",
+      fields: [
+        { name: "title", type: "string" },
+        { name: "mode", type: "string" },
+        { name: "count", type: "number" },
+        { name: "posts", type: "object" },
+      ],
+    });
+  }
   // RT5: the table of contents; its outline is derived from the headings (toc.ts).
   if (has("tableOfContents")) {
     blockObjects.push({
@@ -284,6 +314,8 @@ export function ptSchemaFor(accept: readonly AcceptElement[]): PtSchema {
     // content element, and a stored mention must survive in a field that never offered one.
     inlineObjects: [
       { name: PT_TYPES.mention, title: "Mention", fields: [{ name: "label", type: "string" }] },
+      // RT6: a footnote stores only its note; its number and the end list are derived (footnote.ts).
+      ...(has("footnotes") ? [{ name: PT_TYPES.footnote, title: "Footnote", fields: [{ name: "note", type: "string" as const }] }] : []),
     ],
   };
 }