@bettercms-ai/richtext 0.14.0 → 0.16.0

package/src/ingest.ts

@@ -20,7 +20,9 @@ import { EMBED_TITLE_MAX, isEmbedAspect, nearestEmbedAspect, resolveEmbed } from
 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 } : {}),
         };
       });
@@ -852,14 +922,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 +1075,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 +1204,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,12 +1238,15 @@ 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),
@@ -1075,7 +1257,8 @@ export function htmlToPortableText(html: string, opts: IngestOptions = {}): Port
     ],
     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,7 @@ 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";
 
 /**
  * THE reader. One function, every stored shape, and it never throws.
@@ -298,3 +298,40 @@ 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 };
+}

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

@@ -248,6 +248,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 +311,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 }] }] : []),
     ],
   };
 }

package/src/toc.ts

@@ -27,6 +27,13 @@ export interface OutlineItem {
 const isRecord = (v: unknown): v is Record<string, unknown> =>
   !!v && typeof v === "object" && !Array.isArray(v);
 
+/** A heading id kept from an imported page: a plain HTML id a link can name (`#…`) without escaping. */
+export const isHeadingAnchor = (v: unknown): v is string => typeof v === "string" && /^[A-Za-z0-9][A-Za-z0-9_:.-]{0,127}$/.test(v);
+
+/** Does this value hold a heading anchor? A comparison reads the page with anchors only when it does (ingest `headingAnchors`). */
+export const hasHeadingAnchors = (value: unknown): boolean =>
+  Array.isArray(value) && value.some((n) => isRecord(n) && n._type === "block" && isHeadingAnchor(n.anchor));
+
 const headingText = (node: Record<string, unknown>): string =>
   (Array.isArray(node.children) ? node.children : [])
     .map((c) => (isRecord(c) && typeof c.text === "string" ? c.text : ""))
@@ -36,21 +43,31 @@ const headingText = (node: Record<string, unknown>): string =>
 
 /**
  * The value's top-level h2 and h3, in order, each with a de-duplicated id (V2 `outlineOf`): a
- * heading with no words is left out. `nodes` maps each heading node to its id, which is how a
- * renderer finds the id of the heading it is drawing.
+ * heading with no words is left out. A heading's own `anchor` (an imported page's id, RT9) is its
+ * id, the first time it appears; every other heading's slug steps around the anchors. `nodes` maps
+ * each heading node to its id, which is how a renderer finds the id of the heading it is drawing.
  */
 export function outlineOf(value: unknown): { items: OutlineItem[]; nodes: WeakMap<object, string> } {
-  const items: OutlineItem[] = [];
-  const nodes = new WeakMap<object, string>();
+  const heads: { node: Record<string, unknown>; text: string; anchor: string | null }[] = [];
   const used = new Set<string>();
   for (const node of Array.isArray(value) ? value : []) {
     if (!isRecord(node) || node._type !== "block" || node.listItem || (node.style !== "h2" && node.style !== "h3")) continue;
     const text = headingText(node);
     if (!text) continue;
-    const base = slugify(text);
-    let id = base;
-    for (let n = 2; used.has(id); n++) id = `${base}-${n}`;
-    used.add(id);
+    const anchor = isHeadingAnchor(node.anchor) && !used.has(node.anchor) ? node.anchor : null;
+    if (anchor) used.add(anchor);
+    heads.push({ node, text, anchor });
+  }
+  const items: OutlineItem[] = [];
+  const nodes = new WeakMap<object, string>();
+  for (const { node, text, anchor } of heads) {
+    let id = anchor;
+    if (!id) {
+      const base = slugify(text);
+      id = base;
+      for (let n = 2; used.has(id); n++) id = `${base}-${n}`;
+      used.add(id);
+    }
     nodes.set(node, id);
     items.push({ id, text, depth: node.style === "h2" ? 2 : 3 });
   }