@bettercms-ai/richtext 0.8.3 → 0.10.0

package/src/ingest.ts

@@ -6,10 +6,15 @@ import {
   PT_TYPES,
   type PortableText,
   type PortableTextBlock,
+  type PortableTextTable,
+  type PortableTextTableGroup,
+  type PortableTextTableRow,
 } from "./types";
 import { randomKey, isValidKey, type KeyGenerator } from "./key";
 import { safeHref } from "./href";
 import { BARE_IS_DESIGN, isStyledTag, styledAttrsOf, type StyledMarkDef } from "./styled";
+import { designOf, jsonLdOf, PT_TABLE_LIMITS } from "./table";
+import { PT_KEY_TAKEAWAYS_LIMITS } from "./key-takeaways";
 import type { PtSchema } from "./schema";
 
 /**
@@ -145,44 +150,220 @@ const cellsOf = (row: Element): Element[] =>
   [...row.querySelectorAll("th,td")].filter((c) => c.closest("tr") === row);
 
 /** A span attribute, recorded and not honoured — see `PortableTextTableCell`. */
-const spanOf = (cell: Element, name: "colspan" | "rowspan"): number | undefined => {
+const spanOf = (cell: Element, name: "colspan" | "rowspan" | "span"): number | undefined => {
   const n = Number(cell.getAttribute(name));
   return Number.isInteger(n) && n > 1 ? n : undefined;
 };
 
+/** An element's words, whitespace collapsed. */
+const wordsOf = (el: Element | null | undefined): string => (el?.textContent ?? "").replace(/\s+/g, " ").trim();
+
+const scopeOf = (cell: Element): string => (cell.getAttribute("scope") ?? "").toLowerCase();
+const isTag = (el: Element | null | undefined, tag: string): boolean => (el?.nodeName ?? "").toLowerCase() === tag;
+
+/**
+ * The V2 table's column-group row: in `<thead>`, at least one `<th scope="colgroup">`, and every
+ * other cell an EMPTY `<td>` (the corner over ungrouped columns). Anything looser stays a row, so
+ * a site's own two-row header keeps round-tripping exactly as it always has.
+ */
+const isColumnGroupRow = (row: Element): boolean => {
+  const cells = cellsOf(row);
+  return isTag(row.parentElement, "thead")
+    && cells.some((c) => isTag(c, "th") && scopeOf(c) === "colgroup")
+    && cells.every((c) => (isTag(c, "th") && scopeOf(c) === "colgroup") || (isTag(c, "td") && wordsOf(c) === ""));
+};
+
+/**
+ * The V2 table's row-group label row: one `<th scope="rowgroup">` and nothing else, OPENING its
+ * own `<tbody>` with at least one body row after it — the shape V2 and `portableTextToHtml` write.
+ * A site's own `scope="rowgroup"` header anywhere else (a lone last row, inside `<thead>`, a
+ * second label in the same `<tbody>`) stays an ordinary row, so that markup round-trips as before.
+ */
+const isRowGroupRow = (row: Element): boolean => {
+  const cells = cellsOf(row);
+  if (cells.length !== 1 || !isTag(cells[0], "th") || scopeOf(cells[0]!) !== "rowgroup") return false;
+  const body = row.parentElement;
+  if (!body || !isTag(body, "tbody")) return false;
+  const bodyRows = [...body.children].filter((r) => isTag(r, "tr"));
+  return bodyRows[0] === row && bodyRows.length > 1;
+};
+
+/** Ingested text clipped to its stored limit, so a long caption or note never fails the whole write. */
+const clip = (text: string, max: number): string => (text.length > max ? text.slice(0, max).trimEnd() : text);
+
+/** A group `_key` the markup carries (`data-group`, a `<tbody data-key>`), or a minted one. */
+const groupKey = (value: string | null | undefined, key: KeyGenerator, taken: Set<string>): string => {
+  const own = (value ?? "").trim();
+  const k = own && own.length <= 64 && !taken.has(own) ? own : key();
+  taken.add(k);
+  return k;
+};
+
+/**
+ * A `<table>` element → the table, or `undefined` when it holds no row with a cell.
+ *
+ * Caption and groups are read only where the markup says them in the V2 table's own terms
+ * (`<caption>`, `th[scope=colgroup]`, `th[scope=rowgroup]`), so a table without them reads exactly
+ * as it did before they existed.
+ */
+function readTableElement(el: Element, key: KeyGenerator, ingestCell: (html: string) => PortableText): PortableTextTable | undefined {
+  const all = rowsOf(el);
+  // The columns a `<col data-sortable="true">` marks: a `<colgroup>` without `<col>`s spans its `span` columns.
+  const sortableCols = new Set<number>();
+  let colAt = 0;
+  for (const group of [...el.children].filter((c) => isTag(c, "colgroup"))) {
+    const cols = [...group.children].filter((c) => isTag(c, "col"));
+    if (!cols.length) colAt += spanOf(group, "span") ?? 1;
+    for (const col of cols) {
+      const width = spanOf(col, "span") ?? 1;
+      if (col.getAttribute("data-sortable") === "true") for (let i = 0; i < width; i += 1) sortableCols.add(colAt + i);
+      colAt += width;
+    }
+  }
+  const groupRow = all.find(isColumnGroupRow);
+  const taken = new Set<string>();
+
+  // Column groups: the column range each `scope="colgroup"` header spans.
+  const columnGroups: PortableTextTableGroup[] = [];
+  const ranges: { from: number; to: number; key: string }[] = [];
+  if (groupRow) {
+    let at = 0;
+    for (const cell of cellsOf(groupRow)) {
+      const width = spanOf(cell, "colspan") ?? 1;
+      if (isTag(cell, "th")) {
+        const own = cell.getAttribute("data-group");
+        // The same group split by an ungrouped column comes back as one group, not two.
+        const k = columnGroups.find((g) => own && g._key === own)?._key ?? groupKey(own, key, taken);
+        if (!columnGroups.some((g) => g._key === k)) columnGroups.push({ _key: k, label: clip(wordsOf(cell), PT_TABLE_LIMITS.labelChars) });
+        ranges.push({ from: at, to: at + width, key: k });
+      }
+      at += width;
+    }
+  }
+
+  const rowGroups: PortableTextTableGroup[] = [];
+  let current: { key: string; body: Element | null } | undefined;
+  const rows: PortableTextTableRow[] = [];
+  for (const row of all) {
+    if (row === groupRow) continue;
+    if (isRowGroupRow(row)) {
+      const own = row.parentElement?.getAttribute("data-key");
+      // The same group split by an ungrouped run comes back as one group, not two.
+      const k = rowGroups.find((g) => own && g._key === own)?._key ?? groupKey(own, key, taken);
+      if (!rowGroups.some((g) => g._key === k)) rowGroups.push({ _key: k, label: clip(wordsOf(cellsOf(row)[0]), PT_TABLE_LIMITS.labelChars) });
+      current = { key: k, body: row.parentElement };
+      continue;
+    }
+    if (current && current.body !== row.parentElement) current = undefined;
+    const first = rows.length === 0;
+    // Minted BEFORE the cells, as it always was: a deterministic key sequence is a contract.
+    const rowKey = key();
+    let at = 0;
+    const cells = cellsOf(row).map((cell) => {
+      const start = at;
+      at += spanOf(cell, "colspan") ?? 1;
+      const group = first ? ranges.find((r) => start >= r.from && start < r.to)?.key : undefined;
+      return {
+        _key: key(),
+        content: ingestCell(cell.innerHTML),
+        // A header is what the markup SAYS it is, cell by cell. Deriving it from position
+        // would promote the first data row of a headerless table, and would lose the row
+        // headers that live in a table's first COLUMN.
+        ...(isTag(cell, "th") ? { header: true } : {}),
+        ...(spanOf(cell, "colspan") === undefined ? {} : { span: spanOf(cell, "colspan") }),
+        ...(spanOf(cell, "rowspan") === undefined ? {} : { rowSpan: spanOf(cell, "rowspan") }),
+        ...(group === undefined ? {} : { group }),
+        // "Highlight this column" is named on the column's first-row cell, as `group` is.
+        ...(first && cell.getAttribute("data-highlight") === "true" ? { highlight: true } : {}),
+        // "Visitors can sort columns": the column's `<col data-sortable="true">` (V2 renderTableHtml)
+        ...(first && sortableCols.has(start) ? { sortable: true } : {}),
+      };
+    });
+    if (cells.length === 0) continue;
+    const head = isTag(row.parentElement, "thead");
+    // `<tfoot>` is the V2 table's "Totals row", `data-highlight` its "Highlight this row".
+    const footer = !head && isTag(row.parentElement, "tfoot");
+    const highlight = row.getAttribute("data-highlight") === "true";
+    rows.push({
+      _key: rowKey,
+      cells,
+      // `<thead>` is recorded rather than inferred: a browser inserts `<tbody>` on its own
+      // and never a `<thead>`, so inventing one at render time would make every bare
+      // `<tr><th>` table diverge from its own stored markup.
+      ...(head ? { head: true } : {}),
+      ...(current && !head && !footer ? { group: current.key } : {}),
+      ...(footer ? { footer: true } : {}),
+      ...(highlight ? { highlight: true } : {}),
+    });
+  }
+  if (rows.length === 0) return undefined;
+  const caption = clip(wordsOf([...el.children].find((c) => isTag(c, "caption"))), PT_TABLE_LIMITS.captionChars);
+  // `class="bcms-table"` and nothing else: that class only ever appears in markup the
+  // pre-P1c renderer produced, so recognising it is what lets such markup round-trip
+  // instead of coming back a class short. Any other class is not representable and the
+  // audit reports it, which is the honest answer.
+  const legacy = el.getAttribute("class") === "bcms-table";
+  return {
+    _type: PT_TYPES.table,
+    _key: key(),
+    rows,
+    ...(legacy ? { legacy } : {}),
+    ...(caption ? { caption } : {}),
+    ...(rowGroups.length ? { rowGroups } : {}),
+    ...(columnGroups.length ? { columnGroups } : {}),
+  };
+}
+
 function tableRule(key: KeyGenerator, ingestCell: (html: string) => PortableText): DeserializerRule {
   return {
     deserialize(el: Node, _next, createBlock) {
       if (!isElement(el) || el.nodeName.toLowerCase() !== "table") return undefined;
-      const rows = rowsOf(el)
-        .map((row) => ({
-          _key: key(),
-          cells: cellsOf(row).map((cell) => ({
-            _key: key(),
-            content: ingestCell(cell.innerHTML),
-            // A header is what the markup SAYS it is, cell by cell. Deriving it from position
-            // would promote the first data row of a headerless table, and would lose the row
-            // headers that live in a table's first COLUMN.
-            ...(cell.nodeName.toLowerCase() === "th" ? { header: true } : {}),
-            ...(spanOf(cell, "colspan") === undefined ? {} : { span: spanOf(cell, "colspan") }),
-            ...(spanOf(cell, "rowspan") === undefined ? {} : { rowSpan: spanOf(cell, "rowspan") }),
-          })),
-          // `<thead>` is recorded rather than inferred: a browser inserts `<tbody>` on its own
-          // and never a `<thead>`, so inventing one at render time would make every bare
-          // `<tr><th>` table diverge from its own stored markup.
-          ...(row.parentElement?.nodeName.toLowerCase() === "thead" ? { head: true } : {}),
-        }))
-        .filter((r) => r.cells.length > 0);
-      if (rows.length === 0) return undefined;
+      const table = readTableElement(el, key, ingestCell);
       // `createBlock` is what marks this BLOCK-level. Returning the object bare makes the
       // deserialiser treat it as inline and wrap it in a paragraph — the table survives, nested
       // one level down where no renderer looks for it.
-      // `class="bcms-table"` and nothing else: that class only ever appears in markup the
-      // pre-P1c renderer produced, so recognising it is what lets such markup round-trip
-      // instead of coming back a class short. Any other class is not representable and the
-      // audit reports it, which is the honest answer.
-      const legacy = el.getAttribute("class") === "bcms-table";
-      return createBlock({ _type: PT_TYPES.table, _key: key(), rows, ...(legacy ? { legacy } : {}) });
+      return table ? createBlock(table) : undefined;
+    },
+  };
+}
+
+/** The figure's `data-jsonld` (+ axis, price row) as the table's `jsonLd`, or nothing. */
+function jsonLdIn(el: Element, rowKeys: string[]): { jsonLd?: PortableTextTable["jsonLd"] } {
+  const price = el.getAttribute("data-jsonld-price");
+  const j = jsonLdOf({ type: el.getAttribute("data-jsonld"), axis: el.getAttribute("data-jsonld-axis") ?? undefined, ...(price && rowKeys.includes(price) ? { priceRow: price } : {}) });
+  return j ? { jsonLd: j } : {};
+}
+
+/**
+ * `<figure data-rt="table">` → the table, with the note under it: the V2 kit's table island
+ * (src/schema/table.ts renderTableHtml) and what `portableTextToHtml` writes for a table with
+ * `notes`. The note is `[data-notes]`; the kit's footnotes have no place of their own here, so
+ * they FOLD INTO the note, numbered as the kit numbers them (`[1] …`), rather than vanish. The
+ * table's `_key` comes back from the figure's `data-id` or the note's `id` (`<key>-notes`).
+ */
+function tableFigureRule(key: KeyGenerator, ingestCell: (html: string) => PortableText): DeserializerRule {
+  return {
+    deserialize(el: Node, _next, createBlock) {
+      if (!isElement(el) || el.nodeName.toLowerCase() !== "figure" || el.getAttribute("data-rt") !== "table") return undefined;
+      const inner = el.querySelector("table");
+      const table = inner ? readTableElement(inner, key, ingestCell) : undefined;
+      if (!table) return undefined;
+      const noteEl = el.querySelector("[data-notes]");
+      const footnotes = [...el.querySelectorAll("[data-footnotes] li")].map((li, i) => `[${i + 1}] ${wordsOf(li)}`);
+      // Joined with a space, not a line break: the note renders as one `<p>`, so a break would
+      // read back as a space and the value would not survive its own round trip.
+      const notes = clip([wordsOf(noteEl), ...footnotes].filter(Boolean).join(" "), PT_TABLE_LIMITS.notesChars);
+      const own = [el.getAttribute("data-id"), noteEl?.getAttribute("id")?.replace(/-notes$/, "")].find((k) => isValidKey(k));
+      return createBlock({ ...table, ...(own ? { _key: own } : {}), ...(notes ? { notes } : {}), ...(el.getAttribute("data-filter") === "true" ? { filterable: true } : {}),
+        // "Help search engines read this as" (V2 parseTableElement: dataset.jsonld, jsonldAxis, jsonldPrice). The price row
+        // is kept only when it names a row read here: this renderer writes no row keys, so a round trip falls back to
+        // V2's own default (the first row of prices), never to a key that names nothing.
+        ...jsonLdIn(el, table.rows.map((r) => r._key)),
+        // "On phones" / "Keep column names in view" (V2 parseTableElement: dataset.responsive stack|cards, dataset.sticky)
+        ...(designOf({ responsive: el.getAttribute("data-responsive"), sticky: el.getAttribute("data-sticky") === "true" })
+          ? { design: designOf({ responsive: el.getAttribute("data-responsive"), sticky: el.getAttribute("data-sticky") === "true" }) }
+          : {}),
+      });
     },
   };
 }
@@ -409,6 +590,126 @@ function mediaRule(key: KeyGenerator, schema: PtSchema | undefined): Deserialize
   };
 }
 
+/**
+ * `<figure data-rt="pullquote">` → the `pullQuote` block, the inverse of `pullQuoteHtml`.
+ *
+ * Read as the V2 kit reads it (`parseArticle("pullquote")`, article.ts): the quote is the
+ * blockquote's text (any `<cite>` removed), the name is the caption's `[data-name]` or else the
+ * `<cite>`, the role is the caption's `[data-role]`, and the link is the blockquote's `cite` or
+ * the name's `href`. With no figcaption at all, a `<cite>Name, role</cite>` splits on the first
+ * comma (the kit's legacy rule). One step past the kit, so nothing is dropped silently: a
+ * figcaption with neither hook nor `<cite>` keeps its whole text as the name (the kit reads
+ * `""` there). Only the marked figure takes this rule — a bare `<blockquote>` stays the
+ * blockquote STYLE it has always been.
+ */
+function pullQuoteRule(key: KeyGenerator): DeserializerRule {
+  const text = (el: Element | null | undefined): string => (el?.textContent ?? "").replace(/\s+/g, " ").trim();
+  return {
+    deserialize(el: Node, _next, createBlock) {
+      if (!isElement(el) || el.nodeName.toLowerCase() !== "figure" || el.getAttribute("data-rt") !== "pullquote") {
+        return undefined;
+      }
+      const bq = el.querySelector("blockquote");
+      const quoteEl = bq?.cloneNode(true) as Element | undefined;
+      quoteEl?.querySelectorAll("cite").forEach((c) => c.remove());
+      const cap = el.querySelector("figcaption");
+      const nameEl = cap?.querySelector("[data-name]") ?? el.querySelector("blockquote > cite, cite");
+      const roleEl = cap?.querySelector("[data-role]") ?? null;
+      let name = text(nameEl);
+      let role = text(roleEl);
+      if (!cap && name.includes(",")) {
+        const comma = name.indexOf(",");
+        [name, role] = [name.slice(0, comma).trim(), name.slice(comma + 1).trim()];
+      }
+      if (cap && !nameEl && !roleEl) name = text(cap);
+      const rawLink = (bq?.getAttribute("cite") ?? nameEl?.getAttribute("href") ?? "").trim();
+      const link = rawLink ? safeHref(rawLink) : null;
+      return createBlock({
+        _type: PT_TYPES.pullQuote,
+        _key: key(),
+        quote: text(quoteEl),
+        name,
+        ...(role ? { role } : {}),
+        ...(link ? { link } : {}),
+      });
+    },
+  };
+}
+
+/**
+ * Key takeaways → the `keyTakeaways` block, the inverse of `keyTakeawaysHtml`. Two sources:
+ *
+ *   · V2's own markup, `<aside data-rt="takeaways">`, read as V2 reads it (`parseArticle
+ *     ("takeaways")`, article.ts): the title is `[data-title]`'s text, each point an `<li>`'s.
+ *   · A site's own: an `<aside>`, `<div>` or `<section>` that SAYS it holds takeaways — a class
+ *     or id ENDING in "takeaways" (`takeaways`, `key-takeaways`, `keyTakeaways`,
+ *     `article__takeaways`; never a `takeaway-menu`), or an `aria-label` of "Takeaways" or "Key
+ *     takeaways" — holding an optional title (a heading, `<p>`, `<strong>` or `<b>`) and then ONE
+ *     bulleted list, and nothing else.
+ *
+ * 🔴 NO FALSE POSITIVES, AND NOTHING LOST. An ordinary list is never takeaways: only a marked
+ * container is read, and a `<ul>` alone is a list as it always was. And the block is taken only
+ * when it holds the whole container: a site's point that carries a link, an image, a nested list
+ * bold, italic or classed words, or other markup the block's plain strings cannot keep, a numbered list, text loose beside the
+ * list, more than V2's 8 points or a title over 40 characters — each leaves the container to the
+ * deserialiser, which reads it as the title paragraph and the list it was, word for word.
+ */
+const TAKEAWAYS_NAME = /^(?:[a-z0-9]+(?:-|_|__))*(?:key[-_]?)?takeaways$/i;
+const TAKEAWAYS_LABEL = /^(?:key )?takeaways$/i;
+const TITLE_TAGS = new Set(["h1", "h2", "h3", "h4", "h5", "h6", "p", "strong", "b"]);
+/**
+ * Bare inline wrappers a title may sit in (the title renders as its own label, so its weight is the block's). A point
+ * is a plain string and keeps no formatting, so a point may sit only in a bare `<span>`: a bold or italic word, or any
+ * wrapper with a class or attribute, is design the list item keeps and the block would lose.
+ */
+const TITLE_INLINE = new Set(["span", "strong", "b", "em", "i"]);
+const POINT_INLINE = new Set(["span"]);
+
+function keyTakeawaysRule(key: KeyGenerator): DeserializerRule {
+  const words = (el: Element | null | undefined): string => (el?.textContent ?? "").replace(/\s+/g, " ").trim();
+  const tag = (el: Element): string => el.nodeName.toLowerCase();
+  /** Only text and bare wrappers from `allowed`, at any depth. */
+  const plain = (el: Element, allowed: ReadonlySet<string>): boolean =>
+    [...el.children].every((c) => allowed.has(tag(c)) && c.attributes.length === 0 && plain(c, allowed));
+  const fits = (title: string, points: string[]): boolean =>
+    title.length <= PT_KEY_TAKEAWAYS_LIMITS.titleChars && points.length <= PT_KEY_TAKEAWAYS_LIMITS.points;
+  const block = (title: string, points: string[]) => ({
+    _type: PT_TYPES.keyTakeaways,
+    _key: key(),
+    ...(title ? { title } : {}),
+    points,
+  });
+  /** A site's container → its title and points, or null when it is anything but those. */
+  const siteTakeaways = (el: Element): { title: string; points: string[] } | null => {
+    const names = [...(el.getAttribute("class") ?? "").split(/\s+/), el.getAttribute("id") ?? ""];
+    const marked = names.some((n) => TAKEAWAYS_NAME.test(n)) || TAKEAWAYS_LABEL.test((el.getAttribute("aria-label") ?? "").trim());
+    if (!marked) return null;
+    if ([...el.childNodes].some((n) => n.nodeType === 3 && (n.textContent ?? "").trim() !== "")) return null;
+    const kids = [...el.children];
+    const list = kids[kids.length - 1];
+    if (!list || tag(list) !== "ul" || kids.length > 2) return null;
+    const head = kids.length === 2 ? kids[0]! : null;
+    if (head && (!TITLE_TAGS.has(tag(head)) || !plain(head, TITLE_INLINE))) return null;
+    const items = [...list.children];
+    if (items.length === 0 || items.some((li) => tag(li) !== "li" || !plain(li, POINT_INLINE))) return null;
+    return { title: words(head), points: items.map((li) => words(li)).filter(Boolean) };
+  };
+  return {
+    deserialize(el: Node, _next, createBlock) {
+      if (!isElement(el)) return undefined;
+      const t = tag(el);
+      if (t !== "aside" && t !== "div" && t !== "section") return undefined;
+      if (t === "aside" && el.getAttribute("data-rt") === "takeaways") {
+        const title = words(el.querySelector("[data-title]"));
+        const points = [...el.querySelectorAll("li")].map((li) => words(li)).filter(Boolean);
+        return fits(title, points) ? createBlock(block(title, points)) : undefined;
+      }
+      const site = siteTakeaways(el);
+      return site && fits(site.title, site.points) ? createBlock(block(site.title, site.points)) : undefined;
+    },
+  };
+}
+
 /**
  * Does this field's schema carry the `styled` annotation?
  *
@@ -449,8 +750,12 @@ export function htmlToPortableText(html: string, opts: IngestOptions = {}): Port
      * accepts only images.
      */
     rules: [
-      ...(allowsBlockObject(opts.schema, PT_TYPES.table) ? [tableRule(key, (cell) => htmlToPortableText(cell, opts))] : []),
+      ...(allowsBlockObject(opts.schema, PT_TYPES.table)
+        ? [tableFigureRule(key, (cell) => htmlToPortableText(cell, opts)), tableRule(key, (cell) => htmlToPortableText(cell, opts))]
+        : []),
       ...(allowsBlockObject(opts.schema, PT_TYPES.code) ? [codeRule(key)] : []),
+      ...(allowsBlockObject(opts.schema, PT_TYPES.pullQuote) ? [pullQuoteRule(key)] : []),
+      ...(allowsBlockObject(opts.schema, PT_TYPES.keyTakeaways) ? [keyTakeawaysRule(key)] : []),
       mediaRule(key, opts.schema),
       ...(allowsStyled(opts.schema) ? [styledRule(key)] : []),
       ...(allowsLinks(opts.schema) ? [classedLinkRule(key)] : []),

package/src/key-takeaways.ts

@@ -0,0 +1,93 @@
+import { PT_TYPES } from "./types";
+import { isPortableTextTable } from "./table";
+
+/**
+ * Key takeaways (`PortableTextKeyTakeaways`, types.ts): the limits, the write check, and the
+ * read every renderer shares.
+ *
+ * The limits are the V2 kit's (`ARTICLE_SCHEMAS.takeaways` in `controls/rich-text/article.ts`):
+ * a title of at most 40 characters and at most 8 points. V2's `min: 1` on points is the
+ * editor's, not the write's: its editor always holds a line to type in, and the value it renders
+ * while that line is still empty has no point in it. Refusing that would refuse an autosave
+ * mid-typing, so an empty list stores, and renders as V2 renders it.
+ */
+export const PT_KEY_TAKEAWAYS_LIMITS = { titleChars: 40, points: 8 } as const;
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  !!v && typeof v === "object" && !Array.isArray(v);
+
+/** One reason a stored key-takeaways block is refused, at its own path inside the block. */
+export type PortableTextKeyTakeawaysProblem = { path: Array<string | number>; code: string; message: string };
+
+const KEYS = new Set(["_type", "_key", "title", "points"]);
+
+/**
+ * Every reason `node` cannot be stored, each named with a code: `key_takeaways_invalid` (a
+ * shape problem) or `key_takeaways_limit_exceeded` (a V2 limit).
+ *
+ * Only a `keyTakeaways` block is judged. The type is new, so no value stored before it existed
+ * can hold one: there is nothing to grandfather.
+ */
+export function keyTakeawaysProblems(node: unknown): PortableTextKeyTakeawaysProblem[] {
+  const out: PortableTextKeyTakeawaysProblem[] = [];
+  if (!isRecord(node) || node._type !== PT_TYPES.keyTakeaways) return out;
+  const bad = (path: Array<string | number>, message: string, code = "key_takeaways_invalid") =>
+    out.push({ path, code, message: `${code}: ${message}` });
+  for (const k of Object.keys(node)) if (!KEYS.has(k)) bad([k], `unknown key "${k}" (title, points)`);
+  if (node.title !== undefined) {
+    if (typeof node.title !== "string") bad(["title"], "title must be a string");
+    else if (node.title.length > PT_KEY_TAKEAWAYS_LIMITS.titleChars) {
+      bad(["title"], `title is ${node.title.length} characters; at most ${PT_KEY_TAKEAWAYS_LIMITS.titleChars}`, "key_takeaways_limit_exceeded");
+    }
+  }
+  if (!Array.isArray(node.points)) {
+    bad(["points"], "points must be an array of strings");
+    return out;
+  }
+  node.points.forEach((p, i) => {
+    if (typeof p !== "string") bad(["points", i], `points[${i}] must be a string`);
+  });
+  if (node.points.length > PT_KEY_TAKEAWAYS_LIMITS.points) {
+    bad(["points"], `${node.points.length} points; at most ${PT_KEY_TAKEAWAYS_LIMITS.points}`, "key_takeaways_limit_exceeded");
+  }
+  return out;
+}
+
+/**
+ * `keyTakeawaysProblems` for every key-takeaways block in a rich-text value — top level, and
+ * inside table cells — with the block's `_key` so a refusal names the block an author has to find.
+ */
+export function portableTextKeyTakeawaysProblems(value: unknown): Array<PortableTextKeyTakeawaysProblem & { block: string }> {
+  const out: Array<PortableTextKeyTakeawaysProblem & { 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.keyTakeaways) continue;
+      const block = typeof node._key === "string" ? node._key : "";
+      for (const p of keyTakeawaysProblems(node)) out.push({ ...p, block });
+    }
+  };
+  walk(value);
+  return out;
+}
+
+/**
+ * What a reader sees of a key-takeaways block: the title, trimmed ("" for none), and the points,
+ * each trimmed, the empty ones left out (V2 `renderArticle("takeaways")`). Read defensively: a
+ * value that never passed the write check renders what it can.
+ */
+export function keyTakeawaysView(value: unknown): { title: string; points: string[] } {
+  const v = isRecord(value) ? value : {};
+  const title = typeof v.title === "string" ? v.title.trim() : "";
+  const points = (Array.isArray(v.points) ? v.points : [])
+    .map((p) => (typeof p === "string" ? p.trim() : ""))
+    .filter(Boolean);
+  return { title, points };
+}

package/src/plain.ts

@@ -1,5 +1,7 @@
 import { isPortableTextBlock, isPortableTextSpan, PT_TYPES, type PortableText, type PortableTextTable } from "./types";
-import { migrateTable } from "./table";
+import { migrateTable, tableGroupLayout } from "./table";
+import { keyTakeawaysView } from "./key-takeaways";
+import { componentCopyLines, detachedComponentCopy } from "./component-copy";
 
 /**
  * Portable Text → plain text.
@@ -30,14 +32,34 @@ export function portableTextToPlainText(value: PortableText | null | undefined):
      * over values that never passed through the reader, the corpus audit's above all.
      * `migrateTable` answers null for everything else, so the cost of asking is one comparison.
      *
-     * Every other embedded block — an image, an embed, a component — resolves against a project
-     * this function does not have, so it still contributes nothing.
+     * Every other embedded block — an image, an embed, a LINKED component — resolves against a
+     * project this function does not have, so it still contributes nothing.
      */
+    /**
+     * A pull quote is words a reader sees — the quote, then who said it — so search and the
+     * audit count them. The attribution line is the one the Markdown export writes.
+     */
+    if (node._type === PT_TYPES.pullQuote) {
+      lines.push(...pullQuoteLines(node as Record<string, unknown>));
+      continue;
+    }
+    /** Key takeaways are words a reader sees too: the title, then one line per point. */
+    if (node._type === PT_TYPES.keyTakeaways) {
+      const { title, points } = keyTakeawaysView(node);
+      lines.push(...(title ? [title] : []), ...points);
+      continue;
+    }
     const table = migrateTable(node);
     if (table) {
       lines.push(...tableLines(table));
       continue;
     }
+    // A separate copy of a component holds its own words (a linked one's live in the component).
+    const copy = detachedComponentCopy(node);
+    if (copy) {
+      lines.push(...componentCopyLines(copy));
+      continue;
+    }
     // Dividers and other embedded blocks contribute no text, which is what a reader wants.
   }
   return lines.join("\n");
@@ -51,10 +73,36 @@ export function portableTextToPlainText(value: PortableText | null | undefined):
  * because a row is a LINE and a cell that broke it would make the audit's before/after
  * comparison depend on where a paragraph happened to fall.
  */
-const tableLines = (table: PortableTextTable): string[] =>
-  (Array.isArray(table.rows) ? table.rows : []).map((row) =>
+const tableLines = (table: PortableTextTable): string[] => {
+  const rows = Array.isArray(table.rows) ? table.rows : [];
+  const rowLine = (row: (typeof rows)[number]): string =>
     (Array.isArray(row?.cells) ? row.cells : [])
       .map((cell) => portableTextToPlainText(cell?.content).replace(/\s+/g, " ").trim())
       .join(" ")
-      .trim(),
-  );
+      .trim();
+  /**
+   * Caption, column-group labels, then the rows with each row group's label before its run, then
+   * the note: the order the html draws them in. A table without them is one line per row, as
+   * before they existed.
+   */
+  const layout = tableGroupLayout(table);
+  const one = (s: unknown): string => (typeof s === "string" ? s.replace(/\s+/g, " ").trim() : "");
+  const head = layout.rows.length ? rows.slice(0, rows.length - layout.rows.reduce((n, r) => n + r.rows.length, 0)) : rows;
+  const lines = [
+    one(table.caption),
+    layout.columns.map((r) => one(r.label)).filter(Boolean).join(" "),
+    ...head.map(rowLine),
+    ...layout.rows.flatMap((run) => [...(run.label === undefined ? [] : [one(run.label)]), ...(run.rows as typeof rows).map(rowLine)]),
+    one(table.notes),
+  ];
+  // Only the NEW lines are dropped when empty: an empty row has always contributed its "" line.
+  const extras = new Set([0, 1, lines.length - 1]);
+  return lines.filter((l, i) => l !== "" || !extras.has(i));
+};
+
+/** The quote, then `— name, role` when either is set. */
+const pullQuoteLines = (v: Record<string, unknown>): string[] => {
+  const text = (x: unknown): string => (typeof x === "string" ? x.trim() : "");
+  const by = [text(v.name), text(v.role)].filter(Boolean).join(", ");
+  return [text(v.quote), ...(by ? [`— ${by}`] : [])].filter(Boolean);
+};

package/src/read.ts

@@ -1,6 +1,7 @@
 import { EMBEDDED_COMPONENT_KEY, PORTABLE_TEXT_FORMAT, PT_TYPES, type PortableText } from "./types";
 import { lexicalToPortableText } from "./from-lexical";
 import { migrateTable } from "./table";
+import { detachedComponentCopy, type DetachedComponentCopy } from "./component-copy";
 import { randomKey, type KeyGenerator } from "./key";
 
 /**
@@ -243,10 +244,13 @@ export interface EmbeddedComponentBlock {
 /**
  * A component embedded in rich text, as the ordinary `component` block every renderer already
  * draws — so an embed gets the same resolver, cycle guard and identity attributes as a placed
- * instance. Null for any other node.
+ * instance. Null for any other node, and for a separate copy (`fields.detached`): a copy is not
+ * a reference, and resolving its `componentId` would draw the shared component it left.
+ * `embeddedComponentRender` answers for both.
  */
 export function embeddedComponentBlock(value: unknown): EmbeddedComponentBlock | null {
   if (!isRecord(value) || value.schemaKey !== EMBEDDED_COMPONENT_KEY || !isRecord(value.fields)) return null;
+  if (value.fields.detached !== undefined) return null;
   const { componentId, overrides } = value.fields;
   return {
     type: "component",
@@ -254,3 +258,17 @@ export function embeddedComponentBlock(value: unknown): EmbeddedComponentBlock |
     props: { componentId: String(componentId ?? ""), overrides: isRecord(overrides) ? overrides : {} },
   };
 }
+
+/**
+ * What an embedded component renders as: a linked one, its `component` block (resolved by the
+ * host); a separate copy, its own frozen blocks, which need no lookup. Null for any other node,
+ * and for a copy whose blocks are missing (the write refuses one; a reader draws nothing for it).
+ */
+export function embeddedComponentRender(
+  value: unknown,
+): { kind: "linked"; block: EmbeddedComponentBlock } | { kind: "copy"; copy: DetachedComponentCopy } | null {
+  const block = embeddedComponentBlock(value);
+  if (block) return { kind: "linked", block };
+  const copy = detachedComponentCopy(value);
+  return copy ? { kind: "copy", copy } : null;
+}