@bettercms-ai/richtext 0.12.1 → 0.16.0

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

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

@@ -0,0 +1,146 @@
+import { slugify } from "@bettercms-ai/types";
+import { PT_TYPES } from "./types";
+import { isPortableTextTable } from "./table";
+
+/**
+ * RT5: the table of contents (`PortableTextTableOfContents`, types.ts): the one `slugify`, the
+ * outline a value's headings make, the write check, and the tree both renderers draw.
+ *
+ * Stored is what the author sets, `{ title?, depth }`; the outline is derived from the value's
+ * headings on every render and never stored (R8 refuses `outline`). Every top-level h2 and h3 is
+ * given its outline id on every render, with or without a table of contents, so a link to a
+ * heading keeps working when one is added or removed.
+ */
+export const PT_TOC_LIMITS = { titleChars: 40 } as const;
+export const TOC_DEPTHS = ["2", "3"] as const;
+export type TocDepth = (typeof TOC_DEPTHS)[number];
+
+/** The id a heading's words make: V2's `slugify`, whose one spelling lives in @bettercms-ai/types. */
+export { slugify };
+
+export interface OutlineItem {
+  id: string;
+  text: string;
+  depth: 2 | 3;
+}
+
+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 : ""))
+    .join("")
+    .replace(/​/g, "")
+    .trim();
+
+/**
+ * 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. 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 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 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 });
+  }
+  return { items, nodes };
+}
+
+export type TocEntry = OutlineItem & { children: OutlineItem[] };
+
+/**
+ * The list a table of contents draws (V2 `renderArticle("toc")`): only h2 at depth "2"; an h3
+ * nests under the entry before it, and opens the list only when nothing comes before it.
+ */
+export function tocTree(items: readonly OutlineItem[], depth: TocDepth): TocEntry[] {
+  const out: TocEntry[] = [];
+  for (const it of items) {
+    if (it.depth === 3 && depth === "2") continue;
+    const last = out[out.length - 1];
+    if (it.depth === 3 && last) last.children.push(it);
+    else out.push({ ...it, children: [] });
+  }
+  return out;
+}
+
+/** What a reader sees of the block itself: its title (trimmed), the label its nav carries, and its depth. */
+export function tocView(value: unknown): { title: string; label: string; depth: TocDepth } {
+  const v = isRecord(value) ? value : {};
+  const title = typeof v.title === "string" ? v.title.trim() : "";
+  return { title, label: title || "Table of contents", depth: v.depth === "2" ? "2" : "3" };
+}
+
+/** One reason a stored table of contents is refused, at its own path inside the block. */
+export type PortableTextTocProblem = { path: Array<string | number>; code: string; message: string };
+
+const KEYS = new Set(["_type", "_key", "title", "depth"]);
+
+/**
+ * Every reason `node` cannot be stored: `toc_invalid` (a shape problem) or `toc_limit_exceeded`
+ * (V2's 40-character title). A derived `outline` is refused by the R8 check, by name.
+ */
+export function tableOfContentsProblems(node: unknown): PortableTextTocProblem[] {
+  const out: PortableTextTocProblem[] = [];
+  if (!isRecord(node) || node._type !== PT_TYPES.tableOfContents) return out;
+  const bad = (path: Array<string | number>, message: string, code = "toc_invalid") =>
+    out.push({ path, code, message: `${code}: ${message}` });
+  for (const k of Object.keys(node)) if (!KEYS.has(k) && k !== "outline") bad([k], `unknown key "${k}" (title, depth)`);
+  if (!(TOC_DEPTHS as readonly unknown[]).includes(node.depth)) bad(["depth"], 'depth must be "2" or "3"');
+  if (node.title !== undefined) {
+    if (typeof node.title !== "string") bad(["title"], "title must be a string");
+    else if (node.title.length > PT_TOC_LIMITS.titleChars) {
+      bad(["title"], `title is ${node.title.length} characters; at most ${PT_TOC_LIMITS.titleChars}`, "toc_limit_exceeded");
+    }
+  }
+  return out;
+}
+
+/** `tableOfContentsProblems` for every table of contents in a value (top level, and in table cells), with its block key. */
+export function portableTextTableOfContentsProblems(value: unknown): Array<PortableTextTocProblem & { block: string }> {
+  const out: Array<PortableTextTocProblem & { block: string }> = [];
+  const walk = (blocks: unknown) => {
+    if (!Array.isArray(blocks)) return;
+    for (const node of blocks) {
+      if (isPortableTextTable(node)) {
+        for (const row of node.rows as unknown[]) {
+          if (!isRecord(row) || !Array.isArray(row.cells)) continue;
+          for (const cell of row.cells) if (isRecord(cell)) walk(cell.content);
+        }
+        continue;
+      }
+      if (!isRecord(node) || node._type !== PT_TYPES.tableOfContents) continue;
+      const block = typeof node._key === "string" ? node._key : "";
+      for (const p of tableOfContentsProblems(node)) out.push({ ...p, block });
+    }
+  };
+  walk(value);
+  return out;
+}

package/src/types.ts

@@ -57,6 +57,11 @@ export interface PortableTextBlock extends PortableTextNode {
   level?: number;
   /** Only meaningful when `listItem` is "check". A checklist item's state is content, not style. */
   checked?: boolean;
+  /**
+   * RT9: a top-level h2/h3's own id from the page it was imported from, kept so the site's links
+   * to it keep working. Only when it differs from the id its words would make (toc.ts `outlineOf`).
+   */
+  anchor?: string;
 }
 
 /** Anything that is not text — an image, an embed, a table, a placed component. */
@@ -338,6 +343,83 @@ export interface PortableTextKeyTakeaways extends PortableTextObject {
   points: string[];
 }
 
+/**
+ * RT3: an embed, as V2's EmbedModel. Only what the author sets is stored: the link, the
+ * screen-reader title (≤ EMBED_TITLE_MAX) and the shape. The provider, its kind and the frame src
+ * are derived from `url` at render (`resolveEmbed`), never stored.
+ */
+export interface PortableTextEmbed extends PortableTextObject {
+  _type: "embed";
+  url: string;
+  title: string;
+  aspect: "16:9" | "4:3" | "1:1" | "9:16";
+}
+
+/**
+ * RT4: a gallery, as V2's GalleryModel. Each image is the rich-text image's own `{ src, alt }`
+ * (+ an optional media id), so media rewrites, alt audits and CDN transforms read it the same way.
+ * Limits and the write check: gallery.ts.
+ */
+export interface PortableTextGallery extends PortableTextObject {
+  _type: "gallery";
+  layout: "grid" | "carousel";
+  images: {
+    _key: string;
+    /** The rich-text image's own shape, its RT9 framing (`crop`, `focal`; @bettercms-ai/image-url) included. */
+    image: { src: string; alt: string; mediaId?: string; crop?: { top: number; right: number; bottom: number; left: number }; focal?: { x: number; y: number } } | null;
+    caption?: string;
+  }[];
+}
+
+/**
+ * RT5: a table of contents, as V2's TocModel: a title (≤ 40) and which headings it lists. The
+ * outline is derived from the value's headings at render (toc.ts) and never stored.
+ */
+export interface PortableTextTableOfContents extends PortableTextObject {
+  _type: "tableOfContents";
+  title?: string;
+  depth: "2" | "3";
+}
+
+/**
+ * RT6: a footnote, an inline object in body text (V2's `<sup data-rt="fn" data-note>`). Only the
+ * note is stored; its number, ids, the end list and the back links are derived (footnote.ts).
+ */
+export interface PortableTextFootnote {
+  _type: "footnote";
+  _key: string;
+  note: string;
+}
+
+/**
+ * RT7: columns, as V2's ColumnsModel: a gap and 2 to 4 columns, each a run of text blocks of its
+ * own (depth 1). The column count is derived. Limits and the write check: columns.ts.
+ */
+export interface PortableTextColumns extends PortableTextObject {
+  _type: "columns";
+  gap: "s" | "m" | "l";
+  columns: { _key: string; content: PortableTextBlock[] }[];
+}
+
+/** RT8: an author bio, a reference to the author's entry; name, avatar and bio are resolved at render (references.ts). */
+export interface PortableTextAuthorBio extends PortableTextObject {
+  _type: "authorBio";
+  author?: { _ref: string };
+}
+
+/**
+ * RT8: related posts: a title, how they are chosen (`topic`: shared topics; `newest`: the
+ * collection's newest; `manual`: the hand-picked `posts`), and how many. Each post is resolved at render.
+ */
+export interface PortableTextRelatedPosts extends PortableTextObject {
+  _type: "relatedPosts";
+  title?: string;
+  mode: "topic" | "newest" | "manual";
+  count: number;
+  /** The hand-picked posts. Absent is none, which is what an automatic (topic, newest) block holds. */
+  posts?: { _key: string; _ref: string }[];
+}
+
 export const isPortableTextBlock = (n: unknown): n is PortableTextBlock =>
   !!n && typeof n === "object" && (n as PortableTextNode)._type === "block";
 
@@ -359,6 +441,8 @@ export interface RichTextEnvelope {
   format: typeof PORTABLE_TEXT_FORMAT;
   value: PortableText;
   html: string;
+  /** RT3: what its embeds need beside `html` (the X cards), written at html-cache build. */
+  embeds?: import("@bettercms-ai/types").RichTextEmbeds;
 }
 
 /**
@@ -389,6 +473,24 @@ export const PT_TYPES = {
   pullQuote: "pullQuote",
   /** Key takeaways — see `PortableTextKeyTakeaways`. The V2 kit's `<aside data-rt="takeaways">`. */
   keyTakeaways: "keyTakeaways",
+  /**
+   * A third-party embed (X, CodePen, Figma, Maps, Spotify, Podcasts, audio, a link card) — see
+   * `PortableTextEmbed` and `embed.ts`. The V2 kit's `<figure data-rt="embed">`. Gated by the
+   * `embed` feature; YouTube and Vimeo links still resolve here too, through the video resolver.
+   */
+  embed: "embed",
+  /** A gallery of images, a grid or a carousel — see `PortableTextGallery`. The V2 kit's `<figure data-rt="gallery">`. */
+  gallery: "gallery",
+  /** A table of contents built from the headings — see `PortableTextTableOfContents`. The V2 kit's `<nav data-rt="toc">`. */
+  tableOfContents: "tableOfContents",
+  /** A footnote, an INLINE object in body text — see `PortableTextFootnote`. The V2 kit's `<sup data-rt="fn">`. */
+  footnote: "footnote",
+  /** Columns of text — see `PortableTextColumns`. The V2 kit's `<div data-rt="columns">`; the legacy `builtin:columns` reads the same way. */
+  columns: "columns",
+  /** An author bio — see `PortableTextAuthorBio`. The V2 kit's `<aside data-rt="author">`. */
+  authorBio: "authorBio",
+  /** Related posts — see `PortableTextRelatedPosts`. The V2 kit's `<aside data-rt="related">`. */
+  relatedPosts: "relatedPosts",
   /**
    * A table. Spelled `table`, unprefixed, because that is what every other Portable Text
    * producer calls one — the Sanity-shaped `{_type:"table", rows}` this platform used to refuse
@@ -446,6 +548,12 @@ export const STORABLE_BLOCK_TYPES: ReadonlySet<string> = new Set<string>([
   PT_TYPES.file,
   PT_TYPES.pullQuote,
   PT_TYPES.keyTakeaways,
+  PT_TYPES.embed,
+  PT_TYPES.gallery,
+  PT_TYPES.tableOfContents,
+  PT_TYPES.columns,
+  PT_TYPES.authorBio,
+  PT_TYPES.relatedPosts,
 ]);
 
 /**
@@ -465,6 +573,13 @@ export const BUILTIN_EMBED_KEY = "builtin:video" as const;
 /** A callout (`{ tone: info|tip|warning, title, message }`) and a toggle (`{ title, body }`): plain text, read straight. */
 export const BUILTIN_CALLOUT_KEY = "builtin:callout" as const;
 export const BUILTIN_TOGGLE_KEY = "builtin:toggle" as const;
+/**
+ * A part of a body the SITE's own code renders: an MDX component (`<Figure>…</Figure>`, a chart, a
+ * tabs widget) or an `{expression}`. Not content an author edits here: the page shows what the
+ * build drew, publish never writes over it, and the editor shows it as a locked card. `fields.source`
+ * keeps what the repo wrote, for the card; the delivered html carries only the empty marker.
+ */
+export const BUILTIN_SITE_KEY = "builtin:site" as const;
 
 /**
  * The `schemaKey` of a component embedded in rich text. A wire value shared with the dashboard
@@ -493,7 +608,7 @@ export function foreignBlocks(value: unknown): { _type: string; _key: string }[]
     if (!node || typeof node !== "object" || Array.isArray(node)) continue;
     const type = (node as PortableTextNode)._type;
     if (typeof type !== "string") continue;
-    // A table, a pull quote and key takeaways are admitted by SHAPE, never by `_type` alone —
+    // A table, a pull quote, key takeaways, a gallery and a table of contents are admitted by SHAPE, never by `_type` alone —
     // see `isStorableTable`.
     const storable = type === PT_TYPES.table
       ? isStorableTable(node)
@@ -501,7 +616,16 @@ export function foreignBlocks(value: unknown): { _type: string; _key: string }[]
         ? isStorablePullQuote(node)
         : type === PT_TYPES.keyTakeaways
           ? isStorableKeyTakeaways(node)
-          : STORABLE_BLOCK_TYPES.has(type);
+          : type === PT_TYPES.gallery
+            ? isStorableGallery(node)
+            : type === PT_TYPES.tableOfContents
+              ? isStorableTableOfContents(node)
+              : type === PT_TYPES.columns
+                ? isStorableColumns(node)
+                : type === PT_TYPES.relatedPosts
+                  ? // No `posts` is no picks: an automatic block (topic, newest) needs none.
+                    (node as { posts?: unknown }).posts === undefined || Array.isArray((node as { posts?: unknown }).posts)
+                  : STORABLE_BLOCK_TYPES.has(type);
     if (storable) continue;
     const key = (node as PortableTextNode)._key;
     out.push({ _type: type, _key: typeof key === "string" ? key : "" });
@@ -575,6 +699,37 @@ export function isStorableKeyTakeaways(node: unknown): boolean {
   return Array.isArray((node as { points?: unknown }).points);
 }
 
+/** An embed holds a link, a title of at most 120 characters, and one of V2's four shapes. */
+export function isStorableEmbed(node: unknown): boolean {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return false;
+  const n = node as { url?: unknown; title?: unknown; aspect?: unknown };
+  return typeof n.url === "string" && typeof n.title === "string" && n.title.length <= 120
+    && (n.aspect === "16:9" || n.aspect === "4:3" || n.aspect === "1:1" || n.aspect === "9:16");
+}
+
+/**
+ * Is this `_type:"gallery"` one we can render? An `images` array; what is in it and the limits
+ * are judged by `galleryProblems` (gallery.ts), which names each problem with a code.
+ */
+export function isStorableGallery(node: unknown): boolean {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return false;
+  return Array.isArray((node as { images?: unknown }).images);
+}
+
+/** Is this `_type:"columns"` one we can render? A `columns` array whose entries hold a `content` array; the rest is `columnsProblems`'. */
+export function isStorableColumns(node: unknown): boolean {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return false;
+  const columns = (node as { columns?: unknown }).columns;
+  return Array.isArray(columns) && columns.every((c) => !!c && typeof c === "object" && Array.isArray((c as { content?: unknown }).content));
+}
+
+/** Is this `_type:"tableOfContents"` one we can render? One of V2's two depths; the title is judged by `tableOfContentsProblems`. */
+export function isStorableTableOfContents(node: unknown): boolean {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return false;
+  const depth = (node as { depth?: unknown }).depth;
+  return depth === "2" || depth === "3";
+}
+
 /**
  * @deprecated The marker a table-accepting field used to carry INSTEAD of a table.
  *