@bettercms-ai/richtext 0.8.2 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/richtext",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "type": "module",
   "sideEffects": false,
   "description": "The one Portable Text contract for BetterCMS: schema, converters, and rendering. Shared by the backend, the dashboard and every delivery SDK.",
@@ -9,6 +9,7 @@
   "files": [
     "src",
     "!src/__tests__",
+    "!src/__fixtures__",
     "package.json",
     "README.md"
   ],

package/src/component-copy.ts

@@ -0,0 +1,138 @@
+import { EMBEDDED_COMPONENT_KEY } from "./types";
+
+/**
+ * A component embedded in rich text, kept as a SEPARATE COPY (V2 "Keep as a separate copy" /
+ * "Make a separate copy", bettercms-v2-demo features/blocks/instances.ts `instanceOps.detach`).
+ *
+ * Linked (every value stored before this existed):
+ *   { _type: "bcmsBlock", schemaKey: "component", fields: { componentId, overrides?, variant? } }
+ *   → renders the shared component with this place's overrides; edits to the component reach it.
+ *
+ * Detached:
+ *   { _type: "bcmsBlock", schemaKey: "component", fields: {
+ *       componentId,        the component it was copied from (kept for "Use shared version again")
+ *       detached: true,
+ *       props,              the values readers saw when it was copied (the component's ⊕ this place's)
+ *       blocks,             the block tree readers see, resolved and frozen: no `component` block inside
+ *       sourcePublishedAt,  the source's `lastPublishedAt` when it was copied (0454; older copies hold its first `publishedAt`): the version it was taken from
+ *       variant?
+ *   } }
+ *   → renders `blocks` and never looks the component up again.
+ *
+ * V2 keeps only `props` because its renderer draws a catalog type from props. Here a component's
+ * markup is its own block tree, so a copy that kept only props would still follow the shared
+ * component's structure; `blocks` is what makes the copy separate.
+ */
+export interface DetachedComponentCopy {
+  /** The node's `_key`. */
+  id: string;
+  componentId: string;
+  props: Record<string, unknown>;
+  blocks: unknown[];
+  sourcePublishedAt?: string;
+  variant?: string;
+}
+
+const isRecord = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
+
+const fieldsOf = (value: unknown): Record<string, unknown> | null =>
+  isRecord(value) && value.schemaKey === EMBEDDED_COMPONENT_KEY && isRecord(value.fields) ? value.fields : null;
+
+/** True when the node is an embedded component stored as a separate copy (whatever else it holds). */
+export function isDetachedComponent(value: unknown): boolean {
+  return fieldsOf(value)?.detached === true;
+}
+
+/** The separate copy a node stands for, or null (a linked embed, any other node, a malformed copy). */
+export function detachedComponentCopy(value: unknown): DetachedComponentCopy | null {
+  const f = fieldsOf(value);
+  if (!f || f.detached !== true || !Array.isArray(f.blocks)) return null;
+  return {
+    id: isRecord(value) && typeof value._key === "string" ? value._key : "",
+    componentId: typeof f.componentId === "string" ? f.componentId : "",
+    props: isRecord(f.props) ? f.props : {},
+    blocks: f.blocks,
+    ...(typeof f.sourcePublishedAt === "string" ? { sourcePublishedAt: f.sourcePublishedAt } : {}),
+    ...(typeof f.variant === "string" ? { variant: f.variant } : {}),
+  };
+}
+
+/** One reason a stored copy is refused, at its path inside the node's `fields`. */
+export type ComponentCopyProblem = { path: Array<string | number>; code: string; message: string };
+
+/**
+ * Every reason a separate copy cannot be stored, named `component_copy_invalid` (the shape) or
+ * `component_copy_not_frozen` (its blocks still reference a component, so it would keep
+ * following one).
+ *
+ * 🔴 ONLY A NODE THAT CARRIES `detached` IS JUDGED. A linked embed answers `[]`, so every value
+ * stored before copies existed saves exactly as it did.
+ */
+export function componentCopyProblems(node: unknown): ComponentCopyProblem[] {
+  const f = fieldsOf(node);
+  if (!f || f.detached === undefined) return [];
+  const out: ComponentCopyProblem[] = [];
+  const bad = (path: Array<string | number>, message: string, code = "component_copy_invalid") =>
+    out.push({ path, code, message: `${code}: ${message}` });
+  if (f.detached !== true) bad(["detached"], "detached must be true (leave it out for a linked component)");
+  if (typeof f.componentId !== "string" || !f.componentId) bad(["componentId"], "needs the componentId it was copied from");
+  if (!isRecord(f.props)) bad(["props"], "props must be an object of the values readers see");
+  if (!Array.isArray(f.blocks)) {
+    bad(["blocks"], "needs blocks, the copy readers see; get_component { detachedCopy } returns them");
+  } else {
+    const live = componentRefs(f.blocks);
+    if (live.length) {
+      bad(["blocks"], `still holds ${live.length} component block(s) (${live.slice(0, 3).join(", ")}), so it would keep following the shared one`, "component_copy_not_frozen");
+    }
+  }
+  if (f.sourcePublishedAt !== undefined && (typeof f.sourcePublishedAt !== "string" || Number.isNaN(Date.parse(f.sourcePublishedAt)))) {
+    bad(["sourcePublishedAt"], "sourcePublishedAt must be an ISO date");
+  }
+  if (isRecord(f.overrides) && Object.keys(f.overrides).length) {
+    bad(["overrides"], "a separate copy keeps its values in props; overrides belong to a linked component");
+  }
+  return out;
+}
+
+/** `componentCopyProblems` for every embedded component at the top of a rich-text value, with its `_key`. */
+export function portableTextComponentCopyProblems(value: unknown): Array<ComponentCopyProblem & { block: string }> {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((node) => {
+    const block = isRecord(node) && typeof node._key === "string" ? node._key : "";
+    return componentCopyProblems(node).map((p) => ({ ...p, block }));
+  });
+}
+
+/** The component ids a block tree still references, at any depth. */
+function componentRefs(blocks: unknown, out: string[] = [], depth = 0): string[] {
+  if (depth > 32) return out;
+  if (Array.isArray(blocks)) {
+    for (const b of blocks) componentRefs(b, out, depth + 1);
+    return out;
+  }
+  if (!isRecord(blocks)) return out;
+  if (blocks.type === "component") {
+    const p = isRecord(blocks.props) ? blocks.props : {};
+    out.push(typeof p.componentId === "string" && p.componentId ? p.componentId : "(no id)");
+  }
+  for (const v of Object.values(blocks)) if (v && typeof v === "object") componentRefs(v, out, depth + 1);
+  return out;
+}
+
+/**
+ * What a separate copy says, one line per value, for search and plain text: its own copy is
+ * content this page owns, unlike a linked embed, whose words live in the component.
+ * Strings (markup stripped), numbers, and a link's or button's label; nothing else.
+ */
+export function componentCopyLines(copy: Pick<DetachedComponentCopy, "props">): string[] {
+  const line = (v: unknown): string | null => {
+    if (typeof v === "number" && Number.isFinite(v)) return String(v);
+    if (typeof v === "string") {
+      const t = v.replace(/<[^>]+>/g, " ").replace(/&nbsp;/g, " ").replace(/\s+/g, " ").trim();
+      return t || null;
+    }
+    if (isRecord(v)) return line(v.label ?? v.text ?? v.title);
+    return null;
+  };
+  return Object.values(copy.props).map(line).filter((s): s is string => !!s);
+}

package/src/html.ts

@@ -3,14 +3,16 @@ import {
   BUILTIN_EMBED_KEY,
   BUILTIN_IMAGE_KEY,
   PT_TYPES,
+  pullQuoteHref,
   type PortableText,
   type PortableTextTable,
 } from "./types";
 import { resolveVideoSource } from "./video";
-import { builtInTableToTable } from "./table";
+import { builtInTableToTable, tableGroupLayout } from "./table";
 import { safeHref } from "./href";
 import { isStyledTag, styledAttrEntries } from "./styled";
 import { richTextImageLayout } from "./image-layout";
+import { keyTakeawaysView } from "./key-takeaways";
 
 /**
  * Portable Text → HTML.
@@ -85,11 +87,35 @@ function tableHtml(table: PortableTextTable): string {
   const headCount = rows.findIndex((r) => !isRecord(r) || r.head !== true);
   const head = rows.slice(0, headCount === -1 ? rows.length : headCount);
   const body = rows.slice(head.length);
+  const layout = tableGroupLayout(table);
   // The platform's own class, on migrated values only — see `PortableTextTable["legacy"]`.
   const cls = table.legacy === true ? ' class="bcms-table"' : "";
-  return `<table${cls}>${head.length ? `<thead>${head.map(rowHtml).join("")}</thead>` : ""}${
-    body.length ? `<tbody>${body.map(rowHtml).join("")}</tbody>` : ""
-  }</table>`;
+  const notes = typeof table.notes === "string" ? table.notes.trim() : "";
+  const notesId = notes && typeof table._key === "string" && table._key ? `${table._key}-notes` : "";
+  const caption = typeof table.caption === "string" && table.caption.trim() ? `<caption>${esc(table.caption.trim())}</caption>` : "";
+
+  // Column groups: one `<colgroup>` per run of columns, and a `scope="colgroup"` header over each
+  // grouped run, as the first row of `<thead>` (the V2 table's layout).
+  const colgroups = layout.columns.map((run) => `<colgroup${attr("span", run.width)}></colgroup>`).join("");
+  const groupRow = layout.columns.length
+    ? `<tr>${layout.columns
+        .map((run) => (run.label === undefined ? "<td></td>".repeat(run.width) : `<th scope="colgroup"${attr("colspan", run.width)} data-group="${esc(run.key ?? "")}">${esc(run.label)}</th>`))
+        .join("")}</tr>`
+    : "";
+  const thead = groupRow || head.length ? `<thead>${groupRow}${head.map(rowHtml).join("")}</thead>` : "";
+
+  // Row groups: each run of body rows sharing a group is its own `<tbody>`, under a
+  // `scope="rowgroup"` label row. With no grouped row, ONE `<tbody>`, exactly as before.
+  const tbody = layout.rows.length
+    ? layout.rows
+        .map((run) => `<tbody${run.key === undefined ? "" : ` data-key="${esc(run.key)}"`}>${run.label === undefined ? "" : `<tr><th scope="rowgroup"${attr("colspan", layout.width)}>${esc(run.label)}</th></tr>`}${run.rows.map(rowHtml).join("")}</tbody>`)
+        .join("")
+    : body.length ? `<tbody>${body.map(rowHtml).join("")}</tbody>` : "";
+
+  const html = `<table${cls}${notesId ? ` aria-describedby="${esc(notesId)}"` : ""}>${caption}${colgroups}${thead}${tbody}</table>`;
+  // A note sits UNDER the table, so it needs a container to stay with it: the V2 kit's
+  // `<figure data-rt="table">`, which the ingest reads back.
+  return notes ? `<figure data-rt="table">${html}<p data-notes${notesId ? ` id="${esc(notesId)}"` : ""}>${esc(notes)}</p></figure>` : html;
 }
 
 /**
@@ -215,6 +241,49 @@ function fileHtml(value: unknown, classes: HtmlClasses): string {
   return `<a${cls(classes, "a")} href="${esc(src)}" download>${esc(name)}</a>`;
 }
 
+/**
+ * A pull quote, as the V2 kit renders it (`renderArticle("pullquote")`, article.ts): the same
+ * markup when no classes are passed, with one byte-level difference — a `"` in text comes out
+ * as `&quot;` here (as everywhere in this serialiser, and as React writes it) where the kit
+ * leaves it bare. Both parse to the same DOM, and the kit reads the markup through the DOM, so
+ * only a raw string comparison could tell them apart. The `data-rt`, `data-name` and
+ * `data-role` hooks are the contract, not decoration.
+ *
+ * The name links to `link` (and the blockquote cites it) only through `safeHref`; a refused
+ * link keeps the name, unlinked.
+ */
+function pullQuoteHtml(value: unknown, classes: HtmlClasses): string {
+  const v = isRecord(value) ? value : {};
+  const quote = typeof v.quote === "string" ? v.quote : "";
+  const name = str(v.name);
+  const role = str(v.role);
+  const href = safeHref(pullQuoteHref(v.link));
+  const nameHtml = name
+    ? href
+      ? `<a href="${esc(href)}" data-name>${esc(name)}</a>`
+      : `<span data-name>${esc(name)}</span>`
+    : "";
+  const roleHtml = role ? `<span data-role>${esc(role)}</span>` : "";
+  const caption = nameHtml || roleHtml
+    ? `<figcaption>${nameHtml}${nameHtml && roleHtml ? ", " : ""}${roleHtml}</figcaption>`
+    : "";
+  const cite = href ? ` cite="${esc(href)}"` : "";
+  return `<figure${cls(classes, "figure")} data-rt="pullquote"><blockquote${cls(classes, "blockquote")}${cite}><p>${esc(quote)}</p></blockquote>${caption}</figure>`;
+}
+
+/**
+ * Key takeaways, as the V2 kit renders them (`renderArticle("takeaways")`, article.ts):
+ * `<aside data-rt="takeaways"><p data-title>…</p><ul><li>…</li></ul></aside>`, the title only
+ * when there is one, each point trimmed and the empty ones left out. The same bytes when no
+ * classes are passed, save the pull quote's one difference: a `"` in text is `&quot;` here.
+ * A site's own list classes dress the `<ul>` and `<li>`, as they dress its other lists.
+ */
+function keyTakeawaysHtml(value: unknown, classes: HtmlClasses): string {
+  const { title, points } = keyTakeawaysView(value);
+  const items = points.map((p) => `<li${cls(classes, "li")}>${esc(p)}</li>`).join("");
+  return `<aside data-rt="takeaways">${title ? `<p data-title>${esc(title)}</p>` : ""}<ul${cls(classes, "ul")}>${items}</ul></aside>`;
+}
+
 export interface RenderOptions {
   /**
    * Render a single value with no wrapping `<p>`, for a field whose consumer supplies its own
@@ -303,6 +372,8 @@ const buildComponents = (
     },
     [PT_TYPES.video]: ({ value }) => videoHtml(value, classes),
     [PT_TYPES.file]: ({ value }) => fileHtml(value, classes),
+    [PT_TYPES.pullQuote]: ({ value }) => pullQuoteHtml(value, classes),
+    [PT_TYPES.keyTakeaways]: ({ value }) => keyTakeawaysHtml(value, classes),
     /**
      * A generic embedded block. A block whose payload this serialiser can READ renders as
      * content; one carrying a reference it would have to resolve against a project renders as a

package/src/index.ts

@@ -5,8 +5,10 @@ export * from "./key";
 export * from "./from-lexical";
 export * from "./plain";
 export * from "./table";
+export * from "./key-takeaways";
 export * from "./styled";
 export * from "./read";
+export * from "./component-copy";
 export * from "./accept";
 export * from "./features";
 export * from "./video";

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 { PT_TABLE_LIMITS } from "./table";
+import { PT_KEY_TAKEAWAYS_LIMITS } from "./key-takeaways";
 import type { PtSchema } from "./schema";
 
 /**
@@ -150,50 +155,196 @@ const spanOf = (cell: Element, name: "colspan" | "rowspan"): number | undefined
   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);
+  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 }),
+      };
+    });
+    if (cells.length === 0) continue;
+    const head = isTag(row.parentElement, "thead");
+    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 ? { group: current.key } : {}),
+    });
+  }
+  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;
     },
   };
 }
 
-/** A code block's text, line breaks included: Lexical writes them as `<br>`, not newlines. */
+/**
+ * `<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 } : {}) });
+    },
+  };
+}
+
+/** A highlighter's line box (Expressive Code): a `<div>` directly under the `<code>` or the `<pre>`. */
+const isCodeLine = (node: Node): boolean =>
+  node.nodeName.toLowerCase() === "div" && /^(code|pre)$/i.test(node.parentNode?.nodeName ?? "");
+
+/**
+ * A code block's text, line breaks included: Lexical writes them as `<br>`, a highlighter that
+ * boxes each line writes none at all, and read without one two commands became one word.
+ */
 const codeText = (node: Node): string =>
   node.nodeName.toLowerCase() === "br"
     ? "\n"
     : node.nodeType === 3
       ? (node.textContent ?? "")
-      : [...node.childNodes].map(codeText).join("");
+      : [...node.childNodes].map(codeText).join("") + (isCodeLine(node) ? "\n" : "");
 
 /** `language-x` on the `<code>` (Markdown, our renderer) or `data-language` on the `<pre>` (Lexical, Shiki). */
 const codeLanguage = (pre: Element): string | undefined =>
@@ -402,6 +553,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?
  *
@@ -442,8 +713,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;
+}

package/src/schema.ts

@@ -124,6 +124,33 @@ export function ptSchemaFor(accept: readonly AcceptElement[]): PtSchema {
 
   const blockObjects: PtObject[] = [];
   if (has("p")) blockObjects.push({ name: PT_TYPES.divider, title: "Divider" });
+  // The pull quote rides `p` as the blockquote style does: a quotation is prose, and no stored
+  // field config has to change for an author to get one. `link` is declared as the kit writes
+  // it, a URL string; a link object carrying `href` is read too (`pullQuoteHref`).
+  if (has("p")) {
+    blockObjects.push({
+      name: PT_TYPES.pullQuote,
+      title: "Pull quote",
+      fields: [
+        { name: "quote", type: "string" },
+        { name: "name", type: "string" },
+        { name: "role", type: "string" },
+        { name: "link", type: "string" },
+      ],
+    });
+  }
+  // Key takeaways ride `ul`: they ARE a bulleted list, under a title, so a field that forbids a
+  // list is not handed one in another shape. `points` is an array of strings (types.ts).
+  if (has("ul")) {
+    blockObjects.push({
+      name: PT_TYPES.keyTakeaways,
+      title: "Key takeaways",
+      fields: [
+        { name: "title", type: "string" },
+        { name: "points", type: "object" },
+      ],
+    });
+  }
   if (has("pre")) {
     blockObjects.push({
       name: PT_TYPES.code,
@@ -196,7 +223,18 @@ export function ptSchemaFor(accept: readonly AcceptElement[]): PtSchema {
    * nothing and drift from the types that do.
    */
   if (has("table")) {
-    blockObjects.push({ name: PT_TYPES.table, title: "Table", fields: [{ name: "rows", type: "object" }] });
+    blockObjects.push({
+      name: PT_TYPES.table,
+      title: "Table",
+      // `caption`, `notes` and the two group lists are the V2 table's, optional; see `types.ts`.
+      fields: [
+        { name: "rows", type: "object" },
+        { name: "caption", type: "string" },
+        { name: "notes", type: "string" },
+        { name: "rowGroups", type: "object" },
+        { name: "columnGroups", type: "object" },
+      ],
+    });
   }
 
   return {

package/src/table.ts

@@ -4,6 +4,7 @@ import {
   type PortableText,
   type PortableTextTable,
   type PortableTextTableCell,
+  type PortableTextTableGroup,
   type PortableTextTableRow,
 } from "./types";
 import { deterministicKeys, isValidKey, randomKey, type KeyGenerator } from "./key";
@@ -143,6 +144,7 @@ function normalizeCell(raw: unknown, at: [number, number], mint: Mint, read: Cel
     ...(raw.header === true ? { header: true } : {}),
     ...(span === undefined ? {} : { span }),
     ...(rowSpan === undefined ? {} : { rowSpan }),
+    ...(typeof raw.group === "string" ? { group: raw.group } : {}),
   };
 }
 
@@ -154,6 +156,7 @@ function normalizeRow(raw: unknown, at: number, mint: Mint, read: CellContentRea
     _key: isRecord(raw) && isValidKey(raw._key) ? raw._key : mint("r", at),
     cells: cells.map((c, col) => normalizeCell(c, [at, col], mint, read)),
     ...(isRecord(raw) && raw.head === true ? { head: true } : {}),
+    ...(isRecord(raw) && typeof raw.group === "string" ? { group: raw.group } : {}),
   };
 }
 
@@ -227,5 +230,181 @@ export function migrateTable(
     // Carried through: a migrated table that an author saves back is still the same table, and
     // dropping the flag on that save would change the page the next time it renders.
     ...(node.legacy === true ? { legacy: true } : {}),
+    ...tableExtras(node),
+  };
+}
+
+/**
+ * Caption, notes and the two group lists, carried through the reader. Each is written only when
+ * the stored value has it, so a table without them reads back byte for byte as it did before
+ * they existed. Permissive like the rest of the read: a group entry that is not an object with a
+ * string `_key` is skipped (nothing could name it), and a missing label reads as "". The write
+ * refuses all of it by name — see `tableProblems`.
+ */
+function tableExtras(node: Record<string, unknown>): Partial<PortableTextTable> {
+  const groups = (list: unknown): PortableTextTableGroup[] | undefined =>
+    Array.isArray(list)
+      ? list
+          .filter((g): g is Record<string, unknown> => isRecord(g) && typeof g._key === "string" && g._key !== "")
+          .map((g) => ({ _key: g._key as string, label: typeof g.label === "string" ? g.label : "" }))
+      : undefined;
+  const rowGroups = groups(node.rowGroups);
+  const columnGroups = groups(node.columnGroups);
+  return {
+    ...(typeof node.caption === "string" ? { caption: node.caption } : {}),
+    ...(typeof node.notes === "string" ? { notes: node.notes } : {}),
+    ...(rowGroups ? { rowGroups } : {}),
+    ...(columnGroups ? { columnGroups } : {}),
+  };
+}
+
+/**
+ * The limits a table's caption, notes and group labels are held to — the V2 table's
+ * (`TABLE_LIMITS` in `@bettercms-ai/types` table-value.ts), restated so this package keeps no
+ * dependency on that one.
+ */
+export const PT_TABLE_LIMITS = { captionChars: 300, notesChars: 2000, labelChars: 300, keyChars: 64 } as const;
+
+/** One reason a stored table is refused, at its own path inside the table. The V2 table's shape. */
+export type PortableTextTableProblem = { path: Array<string | number>; code: string; message: string };
+
+const GROUP_KEYS = new Set(["_key", "label"]);
+
+/**
+ * Every reason the caption, notes and groups of `node` cannot be stored, each named with the V2
+ * table's codes (`table_value_invalid`, `table_limit_exceeded`) and its path inside the table.
+ *
+ * 🔴 ONLY THE NEW KEYS ARE JUDGED. A table that carries none of them answers `[]` whatever else it
+ * holds, so every table stored before they existed keeps saving exactly as it did. None of these
+ * checks reads field config, so there is nothing to grandfather.
+ */
+export function tableProblems(node: unknown): PortableTextTableProblem[] {
+  const out: PortableTextTableProblem[] = [];
+  if (!isRecord(node)) return out;
+  const bad = (path: Array<string | number>, message: string, code = "table_value_invalid") =>
+    out.push({ path, code, message: `${code}: ${message}` });
+  const text = (v: unknown, at: Array<string | number>, what: string, max: number, required = false) => {
+    if (v === undefined && !required) return;
+    if (typeof v !== "string") bad(at, `${what} must be a string`);
+    else if (v.length > max) bad(at, `${what} is ${v.length} characters; at most ${max}`, "table_limit_exceeded");
+  };
+  text(node.caption, ["caption"], "caption", PT_TABLE_LIMITS.captionChars);
+  text(node.notes, ["notes"], "notes", PT_TABLE_LIMITS.notesChars);
+
+  const keyed = (list: unknown, at: "rowGroups" | "columnGroups"): Set<string> => {
+    const seen = new Set<string>();
+    if (list === undefined) return seen;
+    if (!Array.isArray(list)) {
+      bad([at], `${at} must be an array of { _key, label }`);
+      return seen;
+    }
+    list.forEach((g, i) => {
+      if (!isRecord(g)) return bad([at, i], `${at}[${i}] must be an object { _key, label }`);
+      for (const k of Object.keys(g)) if (!GROUP_KEYS.has(k)) bad([at, i, k], `unknown key "${k}" (_key, label)`);
+      if (typeof g._key !== "string" || g._key === "" || g._key.length > PT_TABLE_LIMITS.keyChars) {
+        bad([at, i, "_key"], `needs a _key string of 1 to ${PT_TABLE_LIMITS.keyChars} characters`);
+      } else if (seen.has(g._key)) bad([at, i, "_key"], `_key "${g._key}" is used twice`);
+      else seen.add(g._key);
+      text(g.label, [at, i, "label"], "label", PT_TABLE_LIMITS.labelChars, true);
+    });
+    return seen;
+  };
+  const rowGroups = keyed(node.rowGroups, "rowGroups");
+  const columnGroups = keyed(node.columnGroups, "columnGroups");
+
+  const rows = Array.isArray(node.rows) ? node.rows : [];
+  rows.forEach((row, r) => {
+    if (!isRecord(row)) return;
+    if (row.group !== undefined) {
+      if (row.head === true) bad(["rows", r, "group"], "a head row takes no group (row groups hold body rows)");
+      else if (typeof row.group !== "string" || !rowGroups.has(row.group)) {
+        bad(["rows", r, "group"], `group "${String(row.group)}" is not a key of rowGroups`);
+      }
+    }
+    (Array.isArray(row.cells) ? row.cells : []).forEach((cell, c) => {
+      if (!isRecord(cell) || cell.group === undefined) return;
+      const at = ["rows", r, "cells", c, "group"];
+      if (r !== 0) bad(at, "a column's group is named on its cell in the first row only");
+      else if (typeof cell.group !== "string" || !columnGroups.has(cell.group)) {
+        bad(at, `group "${String(cell.group)}" is not a key of columnGroups`);
+      }
+    });
+  });
+  return out;
+}
+
+/**
+ * `tableProblems` for every table in a rich-text value — top level, and inside cells — with the
+ * table's `_key` so a refusal names the table an author has to find.
+ */
+export function portableTextTableProblems(value: unknown): Array<PortableTextTableProblem & { table: string }> {
+  const out: Array<PortableTextTableProblem & { table: string }> = [];
+  const walk = (blocks: unknown) => {
+    if (!Array.isArray(blocks)) return;
+    for (const node of blocks) {
+      if (!isPortableTextTable(node)) continue;
+      const table = typeof node._key === "string" ? node._key : "";
+      for (const p of tableProblems(node)) out.push({ ...p, table });
+      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);
+      }
+    }
+  };
+  walk(value);
+  return out;
+}
+
+/** A run of columns, or of body rows, that share one group; `label` is absent for an ungrouped run. */
+export type TableColumnRun = { width: number; key?: string; label?: string };
+export type TableRowRun = { rows: unknown[]; key?: string; label?: string };
+
+/**
+ * How a table's groups lay out, or two empty lists when it has none.
+ *
+ * Shared by both renderers (`@bettercms-ai/ui` draws the same runs), so they cannot disagree
+ * about where a group starts. A group key that names no group is ignored here rather than
+ * thrown on: the read is permissive, and the write refuses it by name (`tableProblems`).
+ *
+ * `columns` is empty unless some first-row cell names a known column group; `rows` is empty
+ * unless some body row names a known row group. `width` is the widest row, spans counted.
+ */
+export function tableGroupLayout(table: PortableTextTable): { columns: TableColumnRun[]; rows: TableRowRun[]; width: number } {
+  const rows: unknown[] = Array.isArray(table.rows) ? table.rows : [];
+  const labels = (list: unknown): Map<string, string> =>
+    new Map(
+      (Array.isArray(list) ? list : [])
+        .filter((g): g is Record<string, unknown> => isRecord(g) && typeof g._key === "string")
+        .map((g) => [g._key as string, typeof g.label === "string" ? g.label : ""]),
+    );
+  const cellsOf = (row: unknown): unknown[] => (isRecord(row) && Array.isArray(row.cells) ? row.cells : []);
+  const spanOf = (cell: unknown): number =>
+    isRecord(cell) && typeof cell.span === "number" && Number.isInteger(cell.span) && cell.span > 1 ? cell.span : 1;
+  const width = rows.reduce<number>((max, row) => Math.max(max, cellsOf(row).reduce<number>((n, c) => n + spanOf(c), 0)), 0);
+
+  const colLabels = labels(table.columnGroups);
+  const columns: TableColumnRun[] = [];
+  for (const cell of cellsOf(rows[0])) {
+    const key = isRecord(cell) && typeof cell.group === "string" && colLabels.has(cell.group) ? cell.group : undefined;
+    const last = columns[columns.length - 1];
+    if (last && last.key === key) last.width += spanOf(cell);
+    else columns.push({ width: spanOf(cell), ...(key === undefined ? {} : { key, label: colLabels.get(key) }) });
+  }
+
+  const rowLabels = labels(table.rowGroups);
+  const headCount = rows.findIndex((r) => !isRecord(r) || r.head !== true);
+  const body = headCount === -1 ? [] : rows.slice(headCount);
+  const runs: TableRowRun[] = [];
+  for (const row of body) {
+    const key = isRecord(row) && typeof row.group === "string" && rowLabels.has(row.group) ? row.group : undefined;
+    const last = runs[runs.length - 1];
+    if (last && last.key === key) last.rows.push(row);
+    else runs.push({ rows: [row], ...(key === undefined ? {} : { key, label: rowLabels.get(key) }) });
+  }
+
+  return {
+    columns: columns.some((r) => r.key !== undefined) ? columns : [],
+    rows: runs.some((r) => r.key !== undefined) ? runs : [],
+    width,
   };
 }

package/src/types.ts

@@ -102,6 +102,14 @@ export interface PortableTextTableCell {
    * would refuse the whole table over an attribute we simply forgot to carry.
    */
   rowSpan?: number;
+  /**
+   * The COLUMN GROUP this cell's column belongs to: a `_key` of the table's `columnGroups`.
+   *
+   * Read from the FIRST row only (the V2 table puts `group` on the column; this grid has no
+   * column object, so the column's first cell carries it). Living on a cell is what keeps it
+   * right when the editor inserts, deletes or moves a column: the cell moves with its column.
+   */
+  group?: string;
 }
 
 export interface PortableTextTableRow {
@@ -109,6 +117,17 @@ export interface PortableTextTableRow {
   cells: PortableTextTableCell[];
   /** The row sat in `<thead>`. Absent means `<tbody>`, which is what a parser assumes. */
   head?: boolean;
+  /** The ROW GROUP this body row belongs to: a `_key` of the table's `rowGroups`. */
+  group?: string;
+}
+
+/**
+ * A row or column group, the V2 table's `TableGroup` (`@bettercms-ai/types` table-value.ts), so
+ * both tables speak one language: a stable `_key` and the label a reader sees.
+ */
+export interface PortableTextTableGroup {
+  _key: string;
+  label: string;
 }
 
 /** A table. The ONE table BetterCMS has — see `PT_TYPES.table`. */
@@ -129,6 +148,18 @@ export interface PortableTextTable extends PortableTextObject {
    * authored or pasted since P1c carries neither the flag nor the class.
    */
   legacy?: boolean;
+  /**
+   * The four keys below are the V2 table's (`TableValue`), spelled the same way. All optional,
+   * and a table that has none of them renders byte for byte as it did before they existed.
+   */
+  /** What the table compares, written as `<caption>`. At most 300 characters. */
+  caption?: string;
+  /** A note under the table (`<p data-notes>`), plain text. At most 2,000 characters. */
+  notes?: string;
+  /** Body rows name one with `row.group`; each run of rows is its own `<tbody>` under a label row. */
+  rowGroups?: PortableTextTableGroup[];
+  /** First-row cells name one with `cell.group`; a run of columns gets one `scope="colgroup"` header. */
+  columnGroups?: PortableTextTableGroup[];
 }
 
 /**
@@ -157,6 +188,50 @@ export interface PortableTextFile extends PortableTextObject {
   mime?: string;
 }
 
+/**
+ * A pull quote: a quotation lifted out of the body, with who said it.
+ *
+ * 🔴 THE SHAPE IS THE V2 KIT'S, 1:1 — `PullQuoteModel` in the dashboard's
+ * `kit/controls/rich-text/article.ts`, which renders `<figure data-rt="pullquote">`. The kit
+ * writes these four fields and every renderer here draws them, so the names are spelled once.
+ *
+ * `link` is where the NAME links (and the blockquote's `cite`): a URL string, as the kit stores
+ * it, or a link object carrying `href` (the shape a `link` field value takes). Anything
+ * `safeHref` refuses renders the name unlinked rather than dropping it.
+ */
+export interface PortableTextPullQuote extends PortableTextObject {
+  _type: "pullQuote";
+  quote: string;
+  name: string;
+  role?: string;
+  link?: string | { href: string; [k: string]: unknown };
+}
+
+/** The href a pull quote's `link` carries — a string, or a link object's `href`. "" for none. */
+export function pullQuoteHref(link: unknown): string {
+  if (typeof link === "string") return link.trim();
+  if (link && typeof link === "object" && typeof (link as { href?: unknown }).href === "string") {
+    return ((link as { href: string }).href).trim();
+  }
+  return "";
+}
+
+/**
+ * Key takeaways: the story in a few points, set apart near the top of a body.
+ *
+ * 🔴 THE SHAPE IS THE V2 KIT'S, 1:1 — `TakeawaysModel` and `ARTICLE_SCHEMAS.takeaways` (`name:
+ * "keyTakeaways"`, fields `title` and `points`) in the kit's `controls/rich-text/article.ts`,
+ * which renders `<aside data-rt="takeaways">`. `title` is the label over the list ("Key
+ * takeaways" by default), ABSENT rather than empty when an author cleared it. `points` are plain
+ * strings, one per bullet; V2 holds at most 8 and a title of at most 40 characters
+ * (`PT_KEY_TAKEAWAYS_LIMITS`, key-takeaways.ts).
+ */
+export interface PortableTextKeyTakeaways extends PortableTextObject {
+  _type: "keyTakeaways";
+  title?: string;
+  points: string[];
+}
+
 export const isPortableTextBlock = (n: unknown): n is PortableTextBlock =>
   !!n && typeof n === "object" && (n as PortableTextNode)._type === "block";
 
@@ -204,6 +279,10 @@ export const PT_TYPES = {
   video: "video",
   /** A downloadable document — a PDF, a spec sheet. `<a href download>`, nothing more. */
   file: "file",
+  /** A pull quote — see `PortableTextPullQuote`. The V2 kit's `<figure data-rt="pullquote">`. */
+  pullQuote: "pullQuote",
+  /** Key takeaways — see `PortableTextKeyTakeaways`. The V2 kit's `<aside data-rt="takeaways">`. */
+  keyTakeaways: "keyTakeaways",
   /**
    * 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
@@ -259,6 +338,8 @@ export const STORABLE_BLOCK_TYPES: ReadonlySet<string> = new Set<string>([
   PT_TYPES.mention,
   PT_TYPES.video,
   PT_TYPES.file,
+  PT_TYPES.pullQuote,
+  PT_TYPES.keyTakeaways,
 ]);
 
 /**
@@ -303,8 +384,15 @@ 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 is admitted by SHAPE, never by its `_type` alone — see `isStorableTable`.
-    const storable = type === PT_TYPES.table ? isStorableTable(node) : STORABLE_BLOCK_TYPES.has(type);
+    // A table, a pull quote and key takeaways are admitted by SHAPE, never by `_type` alone —
+    // see `isStorableTable`.
+    const storable = type === PT_TYPES.table
+      ? isStorableTable(node)
+      : type === PT_TYPES.pullQuote
+        ? isStorablePullQuote(node)
+        : type === PT_TYPES.keyTakeaways
+          ? isStorableKeyTakeaways(node)
+          : STORABLE_BLOCK_TYPES.has(type);
     if (storable) continue;
     const key = (node as PortableTextNode)._key;
     out.push({ _type: type, _key: typeof key === "string" ? key : "" });
@@ -347,6 +435,37 @@ export function isStorableTable(node: unknown): boolean {
   });
 }
 
+/**
+ * Is this `_type:"pullQuote"` one we can render?
+ *
+ * Same reason as the table: `pullQuote` is a name other producers use too, and a renderer that
+ * met `{_type:"pullQuote", text}` would draw an empty figure. `quote` and `name` are strings
+ * (either may be empty while an author is still typing); `role`, when present, is a string; and
+ * `link`, when present, is a string or an object carrying a string `href`.
+ */
+export function isStorablePullQuote(node: unknown): boolean {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return false;
+  const v = node as Record<string, unknown>;
+  if (typeof v.quote !== "string" || typeof v.name !== "string") return false;
+  if (v.role !== undefined && typeof v.role !== "string") return false;
+  if (v.link === undefined || typeof v.link === "string") return true;
+  return !!v.link && typeof v.link === "object" && typeof (v.link as { href?: unknown }).href === "string";
+}
+
+/**
+ * Is this `_type:"keyTakeaways"` one we can render?
+ *
+ * Same reason as the table: the name alone is not a contract, and a renderer that met another
+ * producer's `{_type:"keyTakeaways", items}` would draw an empty aside. Ours carries `points`, an
+ * array. What is IN it, the title and the limits are judged by `keyTakeawaysProblems`
+ * (key-takeaways.ts), which names each problem with a code; this only decides whether the node is
+ * ours at all.
+ */
+export function isStorableKeyTakeaways(node: unknown): boolean {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return false;
+  return Array.isArray((node as { points?: unknown }).points);
+}
+
 /**
  * @deprecated The marker a table-accepting field used to carry INSTEAD of a table.
  *