@bettercms-ai/richtext 0.10.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/richtext",
-  "version": "0.10.0",
+  "version": "0.12.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.",

package/src/html.ts

@@ -1,14 +1,16 @@
 import { toHTML, type PortableTextHtmlComponents } from "@portabletext/to-html";
 import {
+  BUILTIN_CALLOUT_KEY,
   BUILTIN_EMBED_KEY,
   BUILTIN_IMAGE_KEY,
+  BUILTIN_TOGGLE_KEY,
   PT_TYPES,
   pullQuoteHref,
   type PortableText,
   type PortableTextTable,
 } from "./types";
 import { resolveVideoSource } from "./video";
-import { builtInTableToTable, designOf, highlightedColumns, jsonLdOf, sortableColumns, tableGroupLayout, tableSections } from "./table";
+import { builtInTableToTable, designOf, footnoteNumbers, footnotesOf, highlightedColumns, isTypedTable, jsonLdOf, sortableColumns, tableColumns, tableGroupLayout, tableSections, typedCellView } from "./table";
 import { portableTextToPlainText } from "./plain";
 import { safeHref } from "./href";
 import { isStyledTag, styledAttrEntries } from "./styled";
@@ -97,26 +99,42 @@ function tableHtml(table: PortableTextTable): string {
       at += w;
     }
   }
-  const cellHtml = (raw: unknown, col: number): string => {
+  // The V2 table's typed columns (a first-row cell's `column`): a table with one renders V2's typed markup (cellHtml).
+  const columns = tableColumns(table);
+  const typed = isTypedTable(table);
+  const headRows = new Set(tableSections(table).head);
+  const fnNumber = footnoteNumbers(table);
+  const footnotes = footnotesOf(table.footnotes) ?? [];
+  const tableId = typeof table._key === "string" && table._key ? table._key : "tbl";
+  const cellHtml = (raw: unknown, col: number, row: unknown): string => {
     const cell = isRecord(raw) ? raw : {};
     const tag = cell.header === true ? "th" : "td";
     // `colspan` before `rowspan`, the order every table in the corpus writes them in: the
     // comparison is on serialised markup, and a parser preserves the order it was given.
     const label = stacked && tag === "td" ? ` data-label="${esc(labels[col] || `Column ${col + 1}`)}"` : "";
-    const attrs = `${attr("colspan", cell.span)}${attr("rowspan", cell.rowSpan)}${label}${marked.has(col) ? ' data-highlight="true"' : ""}`;
-    return `<${tag}${attrs}>${portableTextToHtml(cell.content as PortableText, { inline: true })}</${tag}>`;
+    // A footnote: V2 renderTableHtml's data-note (after the value, before data-align) and its numbered marker after the
+    // cell's words (V2 cellHtml `inner + sup`)
+    const n = typeof cell.note === "string" ? fnNumber.get(cell.note) : undefined;
+    const sup = n ? `<sup><a href="#${esc(tableId)}-fn-${n}" aria-label="Note ${n}">${n}</a></sup>` : "";
+    const content = portableTextToHtml(cell.content as PortableText, { inline: true });
+    if (!typed) return `<${tag}${attr("colspan", cell.span)}${attr("rowspan", cell.rowSpan)}${label}${marked.has(col) ? ' data-highlight="true"' : ""}${n ? ` data-note="${esc(cell.note as string)}"` : ""}>${content}${sup}</${tag}>`;
+    const view = typedCellView(columns[col], row, cell, headRows.has(row));
+    const tail: [string, string][] = n ? [...view.tail.filter(([k]) => k !== "data-align"), ["data-note", cell.note as string], ...view.tail.filter(([k]) => k === "data-align")] : view.tail;
+    const out = (list: [string, string][]) => list.map(([k, v]) => ` ${k}="${esc(v)}"`).join("");
+    return `<${tag}${attr("colspan", cell.span)}${attr("rowspan", cell.rowSpan)}${out(view.lead)}${label}${marked.has(col) ? ' data-highlight="true"' : ""}${out(tail)}>${view.inner ?? content}${sup}</${tag}>`;
   };
   const rowHtml = (raw: unknown): string => {
     const cells = isRecord(raw) && Array.isArray(raw.cells) ? raw.cells : [];
-    // "Highlight this row": the V2 table's own attribute (src/schema/table.ts rowHtml).
+    // "Highlight this row": the V2 table's own attribute (src/schema/table.ts rowHtml), after the row's type (data-type).
+    const type = isRecord(raw) && typeof raw.type === "string" ? ` data-type="${esc(raw.type)}"` : "";
     const highlight = isRecord(raw) && raw.highlight === true ? ' data-highlight="true"' : "";
     let col = 0;
     const html = cells.map((c) => {
-      const out = cellHtml(c, col);
+      const out = cellHtml(c, col, raw);
       col += isRecord(c) && typeof c.span === "number" && Number.isInteger(c.span) && c.span > 1 ? c.span : 1;
       return out;
     });
-    return `<tr${highlight}>${html.join("")}</tr>`;
+    return `<tr${type}${highlight}>${html.join("")}</tr>`;
   };
 
   // The LEADING RUN of head rows, not every row flagged one: `<thead>` is a section, and a
@@ -128,7 +146,7 @@ function tableHtml(table: PortableTextTable): string {
   // The platform's own class, on migrated values only — see `PortableTextTable["legacy"]`.
   const cls = table.legacy === true ? ' class="bcms-table"' : "";
   const notes = typeof table.notes === "string" ? table.notes.trim() : "";
-  const notesId = notes && typeof table._key === "string" && table._key ? `${table._key}-notes` : "";
+  const notesId = (notes || footnotes.length) && 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
@@ -138,11 +156,27 @@ function tableHtml(table: PortableTextTable): string {
   const sortable = sortableColumns(table);
   let colAt = 0;
   const cols = (width: number): string => {
-    const out = Array.from({ length: width }, (_, i) => (sortable.has(colAt + i) ? '<col data-sortable="true">' : "<col>")).join("");
+    const out = Array.from({ length: width }, (_, i) => `<col${colAttrs(colAt + i)}>`).join("");
     colAt += width;
     return out;
   };
-  const colgroups = sortable.size
+  // A typed column's `<col>`: V2 renderTableHtml's attributes in its order (schema/table.ts:511-526), data-sortable among them
+  const colAttrs = (i: number): string => {
+    const c = columns[i];
+    const a = c
+      ? [
+          ` data-type="${c.type ?? "text"}"`,
+          c.unit ? ` data-unit="${esc(c.unit)}"` : "",
+          c.currency ? ` data-currency="${esc(c.currency)}"` : "",
+          c.decimals != null ? ` data-decimals="${c.decimals}"` : "",
+          c.align ? ` data-align="${c.align}"` : "",
+        ]
+      : [];
+    a.push(sortable.has(i) ? ' data-sortable="true"' : "");
+    if (c) a.push(c.trueLabel ? ` data-true="${esc(c.trueLabel)}"` : "", c.falseLabel ? ` data-false="${esc(c.falseLabel)}"` : "", c.max != null ? ` data-max="${c.max}"` : "", c.description ? ` data-description="${esc(c.description)}"` : "");
+    return a.join("");
+  };
+  const colgroups = sortable.size || columns.some(Boolean)
     ? (layout.columns.length ? layout.columns.map((run) => run.width) : [layout.width]).map((w) => `<colgroup>${cols(w)}</colgroup>`).join("")
     : layout.columns.map((run) => `<colgroup${attr("span", run.width)}></colgroup>`).join("");
   const groupRow = layout.columns.length
@@ -173,8 +207,15 @@ function tableHtml(table: PortableTextTable): string {
   // stacked table takes V2's withTableRoles (explicit ARIA roles, since display:block drops the implicit ones)
   const designAttrs = design ? `${design.responsive ? ` data-responsive="${design.responsive}"` : ""}${design.sticky ? ' data-sticky="true"' : ""}` : "";
   const html = stacked ? withTableRoles(plainHtml) : plainHtml;
-  if (!notes && !filter && !jsonLd && !designAttrs) return html;
-  return `<figure data-rt="table"${designAttrs}${filter}${jsonLd}>${html}${notes ? `<p data-notes${notesId ? ` id="${esc(notesId)}"` : ""}>${esc(notes)}</p>` : ""}</figure>`;
+  if (!notes && !filter && !jsonLd && !designAttrs && !footnotes.length) return html;
+  // Footnotes: V2 renderTableHtml's notes block, `<div class="bt-notes" id="<key>-notes">` holding the note and the
+  // `<ol data-footnotes>`, each `<li id="<key>-fn-<n>" data-key>`. A note with no footnotes keeps the one `<p>` it had.
+  const under = footnotes.length
+    ? `<div class="bt-notes" id="${esc(tableId)}-notes">${notes ? `<p data-notes>${esc(notes)}</p>` : ""}<ol data-footnotes>${footnotes
+        .map((f, i) => `<li id="${esc(tableId)}-fn-${i + 1}" data-key="${esc(f._key)}">${esc(f.text)}</li>`)
+        .join("")}</ol></div>`
+    : notes ? `<p data-notes${notesId ? ` id="${esc(notesId)}"` : ""}>${esc(notes)}</p>` : "";
+  return `<figure data-rt="table"${designAttrs}${filter}${jsonLd}>${html}${under}</figure>`;
 }
 
 /**
@@ -268,6 +309,42 @@ function embedHtml(value: unknown, _classes: HtmlClasses): string {
   return `<iframe src="${esc(src)}"${title ? ` title="${esc(title)}"` : ""}${IFRAME_ATTRS}></iframe>`;
 }
 
+/** Plain multi-line text as paragraphs: a blank line starts a new one, a single newline is a `<br>`. */
+const paragraphs = (text: string): string =>
+  text.split(/\n\s*\n/).map((p) => p.trim()).filter(Boolean)
+    .map((p) => `<p>${p.split("\n").map(esc).join("<br>")}</p>`).join("");
+
+const CALLOUT_TONES = new Set(["info", "tip", "warning"]);
+
+/**
+ * A callout: a titled note in its tone. Its payload is its own text, so it renders as content — a marker
+ * here was the whole note missing from every delivered page. An unknown tone renders as `info`.
+ */
+function calloutHtml(value: unknown): string {
+  const f = fieldsOf(value);
+  const tone = CALLOUT_TONES.has(str(f.tone)) ? str(f.tone) : "info";
+  const title = str(f.title);
+  const body = paragraphs(typeof f.message === "string" ? f.message : "");
+  if (!title && !body) return "";
+  return `<div class="bcms-callout bcms-callout--${tone}" data-rt="callout" data-callout="${tone}" role="note">`
+    + (title ? `<p class="bcms-callout__title" data-title>${esc(title)}</p>` : "")
+    + `<div class="bcms-callout__body" data-body>${body}</div></div>`;
+}
+
+/** A toggle: `<details>`, so it opens and closes on a page with no script. */
+function toggleHtml(value: unknown): string {
+  const f = fieldsOf(value);
+  const title = str(f.title);
+  const body = paragraphs(typeof f.body === "string" ? f.body : "");
+  if (!title && !body) return "";
+  return `<details class="bcms-toggle" data-rt="toggle"><summary class="bcms-toggle__title">${esc(title)}</summary>`
+    + `<div class="bcms-toggle__body" data-body>${body}</div></details>`;
+}
+
+/** Built-in blocks this serialiser renders from their own fields (no project lookup): read-time html re-derives them. */
+export const isSelfRenderedBlock = (node: unknown): boolean =>
+  isRecord(node) && (node.schemaKey === BUILTIN_CALLOUT_KEY || node.schemaKey === BUILTIN_TOGGLE_KEY);
+
 /**
  * A video: the file itself where the URL is one, the provider's player where it is a provider's.
  *
@@ -447,6 +524,8 @@ const buildComponents = (
       const v = value as { schemaKey?: unknown };
       if (v.schemaKey === BUILTIN_IMAGE_KEY) return imageHtml(value, classes);
       if (v.schemaKey === BUILTIN_EMBED_KEY) return embedHtml(value, classes);
+      if (v.schemaKey === BUILTIN_CALLOUT_KEY) return calloutHtml(value);
+      if (v.schemaKey === BUILTIN_TOGGLE_KEY) return toggleHtml(value);
       /**
        * A pre-P1c TABLE is the exception to the marker, and it has to be: it resolves against
        * nothing. Its rows are text, held right here, so a marker would DELETE visible content.

package/src/ingest.ts

@@ -7,13 +7,15 @@ import {
   type PortableText,
   type PortableTextBlock,
   type PortableTextTable,
+  type PortableTextTableColumn,
+  type PortableTextTableColumnType,
   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 { cellTypeOf, columnOf, designOf, isColumnType, isValueType, jsonLdOf, PT_TABLE_LIMITS, typedCellText } from "./table";
 import { PT_KEY_TAKEAWAYS_LIMITS } from "./key-takeaways";
 import type { PtSchema } from "./schema";
 
@@ -156,6 +158,7 @@ const spanOf = (cell: Element, name: "colspan" | "rowspan" | "span"): number | u
 };
 
 /** An element's words, whitespace collapsed. */
+const escText = (s: string): string => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 const wordsOf = (el: Element | null | undefined): string => (el?.textContent ?? "").replace(/\s+/g, " ").trim();
 
 const scopeOf = (cell: Element): string => (cell.getAttribute("scope") ?? "").toLowerCase();
@@ -210,6 +213,8 @@ function readTableElement(el: Element, key: KeyGenerator, ingestCell: (html: str
   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>();
+  // A typed column's `<col data-type …>` (V2 renderTableHtml) → the column, as V2 parseTableElement reads it.
+  const typedCols = new Map<number, PortableTextTableColumn>();
   let colAt = 0;
   for (const group of [...el.children].filter((c) => isTag(c, "colgroup"))) {
     const cols = [...group.children].filter((c) => isTag(c, "col"));
@@ -217,6 +222,10 @@ function readTableElement(el: Element, key: KeyGenerator, ingestCell: (html: str
     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);
+      const d = (name: string) => col.getAttribute(`data-${name}`) ?? undefined;
+      const num = (name: string) => (d(name) === undefined ? undefined : Number(d(name)));
+      const typed = d("type") === undefined ? undefined : columnOf({ type: d("type"), unit: d("unit"), currency: d("currency"), decimals: num("decimals"), align: d("align"), trueLabel: d("true"), falseLabel: d("false"), max: num("max"), description: d("description") });
+      if (typed) for (let i = 0; i < width; i += 1) typedCols.set(colAt + i, typed);
       colAt += width;
     }
   }
@@ -258,14 +267,35 @@ function readTableElement(el: Element, key: KeyGenerator, ingestCell: (html: str
     const first = rows.length === 0;
     // Minted BEFORE the cells, as it always was: a deterministic key sequence is a contract.
     const rowKey = key();
+    // The V2 table's per-row type (`<tr data-type>`)
+    const rowType = isColumnType(row.getAttribute("data-type")) ? (row.getAttribute("data-type") as PortableTextTableColumnType) : undefined;
+    const inHead = isTag(row.parentElement, "thead");
     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;
+      // A footnote marker (V2: `<sup><a href="#<key>-fn-<n>">`) is the cell's note, not its words: taken out, and the note
+      // kept as the cell's `data-note`, else as `#<n>` for the figure to resolve against its footnotes (`resolveNotes`).
+      const own = cell.cloneNode(true) as Element;
+      let mark: string | undefined;
+      for (const sup of [...own.querySelectorAll("sup")]) {
+        const n = /-fn-(\d+)$/.exec(sup.querySelector("a")?.getAttribute("href") ?? "")?.[1];
+        if (!n) continue;
+        mark ??= `#${n}`;
+        sup.remove();
+      }
+      const note = cell.getAttribute("data-note") || mark;
+      // A typed cell (V2 cellHtml): its per-cell type, its value (`data-value`), its words as content; `data-empty` is no words.
+      const column = typedCols.get(start);
+      const ownType = isColumnType(cell.getAttribute("data-type")) ? (cell.getAttribute("data-type") as PortableTextTableColumnType) : undefined;
+      const type = cellTypeOf(column, { type: rowType }, { type: ownType });
+      const raw = cell.getAttribute("data-value");
+      const value = inHead || raw === null || !isValueType(type) ? undefined : type === "boolean" ? raw === "true" : Number.isFinite(Number(raw)) && raw.trim() !== "" ? Number(raw) : undefined;
+      const empty = !inHead && cell.hasAttribute("data-empty");
       return {
         _key: key(),
-        content: ingestCell(cell.innerHTML),
+        content: empty ? [] : value !== undefined ? ingestCell(escText(typedCellText(column, type, value))) : ingestCell(own.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.
@@ -277,6 +307,10 @@ function readTableElement(el: Element, key: KeyGenerator, ingestCell: (html: str
         ...(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 } : {}),
+        ...(first && column ? { column } : {}),
+        ...(ownType && !inHead ? { type: ownType } : {}),
+        ...(value === undefined ? {} : { value }),
+        ...(note ? { note } : {}),
       };
     });
     if (cells.length === 0) continue;
@@ -294,6 +328,7 @@ function readTableElement(el: Element, key: KeyGenerator, ingestCell: (html: str
       ...(current && !head && !footer ? { group: current.key } : {}),
       ...(footer ? { footer: true } : {}),
       ...(highlight ? { highlight: true } : {}),
+      ...(rowType ? { type: rowType } : {}),
     });
   }
   if (rows.length === 0) return undefined;
@@ -314,6 +349,32 @@ function readTableElement(el: Element, key: KeyGenerator, ingestCell: (html: str
   };
 }
 
+/**
+ * A cell's note against the table's footnotes: a `data-note` key kept when it names one, a `#<n>` marker resolved to the
+ * n-th footnote's key, anything else dropped (a note must name a footnote; a bare table has none).
+ */
+function resolveNotes(table: PortableTextTable, footnotes: { _key: string }[]): PortableTextTable {
+  const keys = new Set(footnotes.map((f) => f._key));
+  const resolve = (note: string | undefined): string | undefined => {
+    if (!note) return undefined;
+    const n = /^#(\d+)$/.exec(note)?.[1];
+    const k = n ? footnotes[Number(n) - 1]?._key : note;
+    return k && keys.has(k) ? k : undefined;
+  };
+  return {
+    ...table,
+    rows: table.rows.map((r) => ({
+      ...r,
+      cells: r.cells.map((c) => {
+        if (c.note === undefined) return c;
+        const { note, ...rest } = c;
+        const k = resolve(note);
+        return k ? { ...rest, note: k } : rest;
+      }),
+    })),
+  };
+}
+
 function tableRule(key: KeyGenerator, ingestCell: (html: string) => PortableText): DeserializerRule {
   return {
     deserialize(el: Node, _next, createBlock) {
@@ -322,7 +383,7 @@ function tableRule(key: KeyGenerator, ingestCell: (html: string) => PortableText
       // `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.
-      return table ? createBlock(table) : undefined;
+      return table ? createBlock(resolveNotes(table, [])) : undefined;
     },
   };
 }
@@ -349,12 +410,18 @@ function tableFigureRule(key: KeyGenerator, ingestCell: (html: string) => Portab
       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 } : {}),
+      // Footnotes (V2 `<ol data-footnotes>`): kept as footnotes, each with its `data-key` (else a minted one).
+      const taken = new Set<string>();
+      const footnotes = [...el.querySelectorAll("[data-footnotes] li")].map((li) => {
+        const k = li.getAttribute("data-key");
+        const _key = k && k.length <= PT_TABLE_LIMITS.keyChars && !taken.has(k) ? k : key();
+        taken.add(_key);
+        return { _key, text: clip(wordsOf(li), PT_TABLE_LIMITS.notesChars) };
+      });
+      const notes = clip(wordsOf(noteEl), PT_TABLE_LIMITS.notesChars);
+      const notesBox = noteEl?.closest(".bt-notes") ?? el.querySelector(".bt-notes");
+      const own = [el.getAttribute("data-id"), (notesBox?.getAttribute("id") ?? noteEl?.getAttribute("id"))?.replace(/-notes$/, "")].find((k) => isValidKey(k));
+      return createBlock({ ...resolveNotes(table, footnotes), ...(own ? { _key: own } : {}), ...(notes ? { notes } : {}), ...(footnotes.length ? { footnotes } : {}), ...(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.

package/src/plain.ts

@@ -94,9 +94,12 @@ const tableLines = (table: PortableTextTable): string[] => {
     ...head.map(rowLine),
     ...layout.rows.flatMap((run) => [...(run.label === undefined ? [] : [one(run.label)]), ...(run.rows as typeof rows).map(rowLine)]),
     one(table.notes),
+    // footnotes, numbered as the html numbers them (V2 tableSearchText reads them too)
+    ...(Array.isArray(table.footnotes) ? table.footnotes : []).map((f, i) => one(`[${i + 1}] ${typeof f?.text === "string" ? f.text : ""}`)),
   ];
   // 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]);
+  const fnCount = Array.isArray(table.footnotes) ? table.footnotes.length : 0;
+  const extras = new Set([0, 1, lines.length - 1 - fnCount]);
   return lines.filter((l, i) => l !== "" || !extras.has(i));
 };
 

package/src/table.ts

@@ -1,11 +1,15 @@
 import {
   BUILTIN_TABLE_KEY,
+  PT_TABLE_COLUMN_TYPES,
   PT_TYPES,
   type PortableText,
   type PortableTextTable,
   type PortableTextTableCell,
+  type PortableTextTableColumn,
+  type PortableTextTableColumnType,
   type PortableTextTableGroup,
   type PortableTextTableDesign,
+  type PortableTextTableFootnote,
   type PortableTextTableJsonLd,
   type PortableTextTableRow,
 } from "./types";
@@ -149,6 +153,11 @@ function normalizeCell(raw: unknown, at: [number, number], mint: Mint, read: Cel
     ...(typeof raw.group === "string" ? { group: raw.group } : {}),
     ...(raw.highlight === true ? { highlight: true } : {}),
     ...(raw.sortable === true ? { sortable: true } : {}),
+    // The V2 table's typed cells: the column (first-row cell), the per-cell type, the typed value.
+    ...(columnOf(raw.column) ? { column: columnOf(raw.column) } : {}),
+    ...(isColumnType(raw.type) ? { type: raw.type } : {}),
+    ...(typeof raw.value === "boolean" || (typeof raw.value === "number" && Number.isFinite(raw.value)) ? { value: raw.value } : {}),
+    ...(typeof raw.note === "string" && raw.note ? { note: raw.note } : {}),
   };
 }
 
@@ -164,6 +173,7 @@ function normalizeRow(raw: unknown, at: number, mint: Mint, read: CellContentRea
     // The V2 table's two row flags ("Totals row", "Highlight this row"); see `PortableTextTableRow`.
     ...(isRecord(raw) && raw.footer === true ? { footer: true } : {}),
     ...(isRecord(raw) && raw.highlight === true ? { highlight: true } : {}),
+    ...(isRecord(raw) && isColumnType(raw.type) ? { type: raw.type } : {}),
   };
 }
 
@@ -265,9 +275,24 @@ function tableExtras(node: Record<string, unknown>): Partial<PortableTextTable>
     ...(node.filterable === true ? { filterable: true } : {}),
     ...(jsonLdOf(node.jsonLd) ? { jsonLd: jsonLdOf(node.jsonLd) } : {}),
     ...(designOf(node.design) ? { design: designOf(node.design) } : {}),
+    ...(footnotesOf(node.footnotes) ? { footnotes: footnotesOf(node.footnotes) } : {}),
   };
 }
 
+/** Stored footnotes read permissively: entries with a string `_key`, their text ("" when missing); none is nothing. */
+export function footnotesOf(v: unknown): PortableTextTableFootnote[] | undefined {
+  if (!Array.isArray(v)) return undefined;
+  const out = v
+    .filter((f): f is Record<string, unknown> => isRecord(f) && typeof f._key === "string" && f._key !== "")
+    .map((f) => ({ _key: f._key as string, text: typeof f.text === "string" ? f.text : "" }));
+  return out.length ? out : undefined;
+}
+
+/** footnote `_key` → its number (1-based, in order), as V2's footnoteIndex. */
+export function footnoteNumbers(table: PortableTextTable): Map<string, number> {
+  return new Map((footnotesOf(table.footnotes) ?? []).map((f, i) => [f._key, i + 1]));
+}
+
 const DESIGN_KEYS = new Set(["responsive", "sticky"]);
 
 /**
@@ -372,14 +397,32 @@ export function tableProblems(node: unknown): PortableTextTableProblem[] {
   };
   const rowGroups = keyed(node.rowGroups, "rowGroups");
   const columnGroups = keyed(node.columnGroups, "columnGroups");
+  // Footnotes: [{ _key, text }], the field-lane table's (`text` held to the note's limit)
+  const footnoteKeys = new Set<string>();
+  if (node.footnotes !== undefined) {
+    if (!Array.isArray(node.footnotes)) bad(["footnotes"], "footnotes must be an array of { _key, text }");
+    else
+      node.footnotes.forEach((f, i) => {
+        if (!isRecord(f)) return bad(["footnotes", i], `footnotes[${i}] must be an object { _key, text }`);
+        for (const k of Object.keys(f)) if (k !== "_key" && k !== "text") bad(["footnotes", i, k], `unknown key "${k}" (_key, text)`);
+        if (typeof f._key !== "string" || f._key === "" || f._key.length > PT_TABLE_LIMITS.keyChars) bad(["footnotes", i, "_key"], `needs a _key string of 1 to ${PT_TABLE_LIMITS.keyChars} characters`);
+        else if (footnoteKeys.has(f._key)) bad(["footnotes", i, "_key"], `_key "${f._key}" is used twice`);
+        else footnoteKeys.add(f._key);
+        text(f.text, ["footnotes", i, "text"], "text", PT_TABLE_LIMITS.notesChars, true);
+      });
+  }
 
   const rows = Array.isArray(node.rows) ? node.rows : [];
+  // The columns' types, by cell index, as the first row names them (a typed value is judged against its column).
+  const firstCells = isRecord(rows[0]) && Array.isArray(rows[0].cells) ? (rows[0].cells as unknown[]) : [];
+  const columns = firstCells.map((c) => (isRecord(c) ? columnOf(c.column) : undefined));
   rows.forEach((row, r) => {
     if (!isRecord(row)) return;
     for (const flag of ["footer", "highlight"] as const) {
       if (row[flag] !== undefined && typeof row[flag] !== "boolean") bad(["rows", r, flag], `${flag} must be true or false`);
     }
     if (row.head === true && row.footer === true) bad(["rows", r, "footer"], "a head row cannot also be a footer (totals) row");
+    if (row.type !== undefined && !isColumnType(row.type)) bad(["rows", r, "type"], `type must be one of ${PT_TABLE_COLUMN_TYPES.join(", ")}`);
     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)) {
@@ -387,6 +430,10 @@ export function tableProblems(node: unknown): PortableTextTableProblem[] {
       }
     }
     (Array.isArray(row.cells) ? row.cells : []).forEach((cell, c) => {
+      if (isRecord(cell)) for (const p of typedCellProblems(cell, row, r, c, columns[c])) bad(p.path, p.message);
+      if (isRecord(cell) && cell.note !== undefined && (typeof cell.note !== "string" || !footnoteKeys.has(cell.note))) {
+        bad(["rows", r, "cells", c, "note"], `note "${String(cell.note)}" is not a key of footnotes`);
+      }
       for (const flag of ["highlight", "sortable"] as const) {
         if (!isRecord(cell) || cell[flag] === undefined) continue;
         const at = ["rows", r, "cells", c, flag];
@@ -520,3 +567,223 @@ export function tableGroupLayout(table: PortableTextTable): { columns: TableColu
     width,
   };
 }
+
+/* ── Typed cells (the V2 table's column types, src/schema/table.ts) ─────────────────────── */
+
+const COLUMN_KEYS = new Set(["type", "description", "unit", "currency", "decimals", "align", "trueLabel", "falseLabel", "max"]);
+const NUMERIC_TYPES = new Set<string>(["number", "money", "rating"]);
+
+export const isColumnType = (v: unknown): v is PortableTextTableColumnType => (PT_TABLE_COLUMN_TYPES as readonly unknown[]).includes(v);
+
+/** A stored `column` read permissively: each V2 key kept when well formed, a type this table offers; nothing left is nothing. */
+export function columnOf(v: unknown): PortableTextTableColumn | undefined {
+  if (!isRecord(v)) return undefined;
+  const str = (x: unknown) => (typeof x === "string" && x !== "" ? x : undefined);
+  const int = (x: unknown, lo: number, hi: number) => (Number.isInteger(x) && (x as number) >= lo && (x as number) <= hi ? (x as number) : undefined);
+  const c: PortableTextTableColumn = {
+    ...(isColumnType(v.type) ? { type: v.type } : {}),
+    ...(str(v.description) ? { description: str(v.description) } : {}),
+    ...(str(v.unit) ? { unit: str(v.unit) } : {}),
+    ...(typeof v.currency === "string" && /^[A-Z]{3}$/.test(v.currency) ? { currency: v.currency } : {}),
+    ...(int(v.decimals, 0, 10) !== undefined ? { decimals: int(v.decimals, 0, 10) } : {}),
+    ...(v.align === "start" || v.align === "center" || v.align === "end" ? { align: v.align } : {}),
+    ...(str(v.trueLabel) ? { trueLabel: str(v.trueLabel) } : {}),
+    ...(str(v.falseLabel) ? { falseLabel: str(v.falseLabel) } : {}),
+    ...(int(v.max, 1, 10) !== undefined ? { max: int(v.max, 1, 10) } : {}),
+  };
+  return Object.keys(c).length ? c : undefined;
+}
+
+/** Each column's `column`, by column index (spans counted), from the FIRST-row cells. */
+export function tableColumns(table: PortableTextTable): (PortableTextTableColumn | undefined)[] {
+  const out: (PortableTextTableColumn | undefined)[] = [];
+  const first = Array.isArray(table.rows) ? table.rows[0] : undefined;
+  for (const cell of isRecord(first) && Array.isArray(first.cells) ? first.cells : []) {
+    const w = isRecord(cell) && typeof cell.span === "number" && Number.isInteger(cell.span) && cell.span > 1 ? cell.span : 1;
+    const col = isRecord(cell) ? columnOf(cell.column) : undefined;
+    for (let i = 0; i < w; i += 1) out.push(col);
+  }
+  return out;
+}
+
+/**
+ * A table that draws V2's typed markup: its first row names a `column`, or a row or cell carries a type or a value (a "Write
+ * words instead" cell in a link column is typed even when no column is).
+ */
+export function isTypedTable(table: PortableTextTable): boolean {
+  if (tableColumns(table).some(Boolean)) return true;
+  return (Array.isArray(table.rows) ? (table.rows as unknown[]) : []).some(
+    (r) => isRecord(r) && (r.type !== undefined || (Array.isArray(r.cells) && r.cells.some((c: unknown) => isRecord(c) && (c.type !== undefined || c.value !== undefined)))),
+  );
+}
+
+/** V2 `cellType`: the cell's own type, else the row's, else the column's (text when none says). */
+export const cellTypeOf = (col: PortableTextTableColumn | undefined, row: unknown, cell: unknown): PortableTextTableColumnType =>
+  (isRecord(cell) && isColumnType(cell.type) ? cell.type : undefined) ?? (isRecord(row) && isColumnType(row.type) ? row.type : undefined) ?? col?.type ?? "text";
+
+/** V2 `alignOf` (schema/table.ts:365): numbers, money and ratings align end unless the column says otherwise. */
+export const columnAlign = (col: PortableTextTableColumn | undefined, type: PortableTextTableColumnType): "start" | "center" | "end" =>
+  col?.align ?? (NUMERIC_TYPES.has(type) ? "end" : "start");
+
+/** The types whose cell is a value rather than words: V2 renders them from the value (cellHtml). */
+export const isValueType = (t: PortableTextTableColumnType): boolean => t === "boolean" || NUMERIC_TYPES.has(t);
+
+const TRUE_WORDS = new Set(["✓", "✔", "✔️", "☑", "✅", "yes", "y", "true", "included", "available", "supported", "x ✓", "check", "●"]);
+const FALSE_WORDS = new Set(["✗", "✕", "✖", "❌", "×", "x", "no", "n", "false", "not included", "unavailable", "not available", "unsupported", "—", "–", "-", "○"]);
+/** V2 `toBool` (schema/table.ts:315). */
+export function toBool(v: unknown): boolean | null {
+  if (typeof v === "boolean") return v;
+  if (typeof v !== "string") return null;
+  const s = v.trim().toLowerCase();
+  return TRUE_WORDS.has(s) ? true : FALSE_WORDS.has(s) ? false : null;
+}
+/** V2 `toNumber` (schema/table.ts:273). */
+export function toNumber(v: unknown): number | null {
+  if (typeof v === "number") return Number.isFinite(v) ? v : null;
+  if (typeof v !== "string") return null;
+  const s = v.replace(/[,\s]/g, "").replace(/[^\d.+-]/g, "");
+  if (!s || !/^[+-]?\d*\.?\d+$/.test(s)) return null;
+  return Number(s);
+}
+/** V2 `formatNumber` (schema/table.ts:262). */
+export const formatNumber = (n: number, decimals?: number): string =>
+  new Intl.NumberFormat("en-US", decimals != null ? { minimumFractionDigits: decimals, maximumFractionDigits: decimals } : { maximumFractionDigits: 6 }).format(n);
+/** V2 `formatMoney` (schema/table.ts:265). */
+export function formatMoney(n: number, currency = "USD", decimals?: number): string {
+  try {
+    const whole = Number.isInteger(n) && decimals == null;
+    return new Intl.NumberFormat("en-US", { style: "currency", currency, minimumFractionDigits: whole ? 0 : decimals ?? 2, maximumFractionDigits: whole ? 0 : decimals ?? 2 }).format(n);
+  } catch {
+    return `${formatNumber(n, decimals)} ${currency}`;
+  }
+}
+/** V2 `boolLabels` (schema/table.ts:252). */
+export const boolLabels = (col: PortableTextTableColumn | undefined) => ({ yes: col?.trueLabel || "Included", no: col?.falseLabel || "Not included" });
+
+/**
+ * V2 `cellText` (schema/table.ts:282) for a value type: the words a Number, Price, Yes / No or Rating cell says, which is what a
+ * typed cell's `content` holds. `v` is the typed value, or the cell's words when it has none.
+ */
+export function typedCellText(col: PortableTextTableColumn | undefined, type: PortableTextTableColumnType, v: unknown): string {
+  if (v == null || v === "") return "";
+  const words = String(v).replace(/\s+/g, " ").trim();
+  switch (type) {
+    case "boolean": {
+      const b = toBool(v);
+      return b == null ? words : b ? boolLabels(col).yes : boolLabels(col).no;
+    }
+    case "number": {
+      const n = toNumber(v);
+      return n == null ? words : `${formatNumber(n, col?.decimals)}${col?.unit ? (/^[%°]/.test(col.unit) ? col.unit : ` ${col.unit}`) : ""}`;
+    }
+    case "money": {
+      const n = toNumber(v);
+      return n == null ? words : formatMoney(n, col?.currency || "USD", col?.decimals);
+    }
+    case "rating": {
+      const n = toNumber(v);
+      return n == null ? words : `${formatNumber(n, 1).replace(/\.0$/, "")} out of ${col?.max ?? 5}`;
+    }
+    default:
+      return words;
+  }
+}
+
+const escHtml = (s: string): string => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+/**
+ * What a cell of a TYPED table (one whose first row names a `column`) draws, shared by both renderers so they cannot disagree:
+ *   a head-row cell  → `lead` data-align (V2: not when start), `tail` the column's description as `title`
+ *                      (V2 renderTableHtml's `<th scope="col" data-align data-highlight title>`, schema/table.ts:564)
+ *   any other cell   → `tail` data-type (its own type), data-value / data-empty, data-align, and `inner`, V2 cellHtml's markup
+ *                      (schema/table.ts:369-437) when the cell is empty or of a value type; text and link cells draw their blocks.
+ * Attribute values are raw (the caller escapes them); `inner` is markup, its text already escaped.
+ */
+export function typedCellView(
+  column: PortableTextTableColumn | undefined,
+  row: unknown,
+  cell: Record<string, unknown>,
+  inHead: boolean,
+): { lead: [string, string][]; tail: [string, string][]; inner?: string } {
+  if (inHead) {
+    const align = columnAlign(column, column?.type ?? "text");
+    return { lead: align !== "start" ? [["data-align", align]] : [], tail: column?.description ? [["title", column.description]] : [] };
+  }
+  const type = cellTypeOf(column, row, cell);
+  const words = portableTextWords(cell.content);
+  const v = typeof cell.value === "number" || typeof cell.value === "boolean" ? cell.value : words;
+  const tail: [string, string][] = isColumnType(cell.type) ? [["data-type", cell.type]] : [];
+  let inner: string | undefined;
+  if (v === "") {
+    inner = cell.header === true ? "" : '<span aria-hidden="true" class="bt-dash">—</span><span class="bt-sr">No value</span>';
+    tail.push(["data-empty", ""]);
+  } else if (type === "boolean") {
+    const b = toBool(v);
+    if (b == null) inner = escHtml(words);
+    else {
+      const { yes, no } = boolLabels(column);
+      inner = `<span aria-hidden="true" class="bt-bool" data-bool="${b}">${b ? "✓" : "–"}</span><span class="bt-sr">${escHtml(b ? yes : no)}</span>`;
+      tail.push(["data-value", String(b)]);
+    }
+  } else if (type === "rating") {
+    const n = toNumber(v);
+    if (n == null) inner = escHtml(words);
+    else {
+      inner = `<span aria-hidden="true" class="bt-star">★</span> ${escHtml(formatNumber(n, 1).replace(/\.0$/, ""))}<span class="bt-dim"> / ${column?.max ?? 5}</span>`;
+      tail.push(["data-value", String(n)]);
+    }
+  } else if (type === "number" || type === "money") {
+    const n = toNumber(v);
+    inner = escHtml(typedCellText(column, type, v));
+    if (n != null) tail.push(["data-value", String(n)]);
+  }
+  const align = columnAlign(column, type);
+  if (align !== "start") tail.push(["data-align", align]);
+  return { lead: [], tail, ...(inner === undefined ? {} : { inner }) };
+}
+
+/** A cell's words: the text of its blocks, whitespace collapsed (as `portableTextToPlainText` reads a paragraph). */
+function portableTextWords(content: unknown): string {
+  return (Array.isArray(content) ? content : [])
+    .map((b) => (isRecord(b) && Array.isArray(b.children) ? b.children.map((c) => (isRecord(c) && typeof c.text === "string" ? c.text : "")).join("") : ""))
+    .join(" ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/** Why a cell's typed keys cannot be stored (`column` only on the first row, a known type, a value its type holds). */
+function typedCellProblems(cell: Record<string, unknown>, row: Record<string, unknown>, r: number, c: number, col: PortableTextTableColumn | undefined): PortableTextTableProblem[] {
+  const out: PortableTextTableProblem[] = [];
+  const bad = (k: string | string[], message: string, code = "table_value_invalid") =>
+    out.push({ path: ["rows", r, "cells", c, ...(Array.isArray(k) ? k : [k])], code, message: `${code}: ${message}` });
+  if (cell.column !== undefined) {
+    const v = cell.column;
+    if (r !== 0) bad("column", "a column's type is named on its cell in the first row only");
+    else if (!isRecord(v)) bad("column", "column must be an object { type, unit?, currency?, decimals?, align?, trueLabel?, falseLabel?, max?, description? }");
+    else {
+      for (const k of Object.keys(v)) if (!COLUMN_KEYS.has(k)) bad(["column", k], `unknown key "${k}" (${[...COLUMN_KEYS].join(", ")})`);
+      if (v.type !== undefined && !isColumnType(v.type)) bad(["column", "type"], `type must be one of ${PT_TABLE_COLUMN_TYPES.join(", ")}`);
+      const text = (k: string, max: number) => {
+        if (v[k] === undefined) return;
+        if (typeof v[k] !== "string") bad(["column", k], `${k} must be a string`);
+        else if ((v[k] as string).length > max) bad(["column", k], `${k} is ${(v[k] as string).length} characters; at most ${max}`, "table_limit_exceeded");
+      };
+      text("description", PT_TABLE_LIMITS.notesChars);
+      text("unit", 16);
+      text("trueLabel", PT_TABLE_LIMITS.labelChars);
+      text("falseLabel", PT_TABLE_LIMITS.labelChars);
+      if (v.currency !== undefined && (typeof v.currency !== "string" || !/^[A-Z]{3}$/.test(v.currency))) bad(["column", "currency"], "currency must be an ISO 4217 code such as USD");
+      if (v.decimals !== undefined && (!Number.isInteger(v.decimals) || (v.decimals as number) < 0 || (v.decimals as number) > 10)) bad(["column", "decimals"], "decimals must be a whole number from 0 to 10");
+      if (v.max !== undefined && (!Number.isInteger(v.max) || (v.max as number) < 1 || (v.max as number) > 10)) bad(["column", "max"], "max must be a whole number from 1 to 10");
+      if (v.align !== undefined && v.align !== "start" && v.align !== "center" && v.align !== "end") bad(["column", "align"], 'align must be "start", "center" or "end"');
+    }
+  }
+  if (cell.type !== undefined && !isColumnType(cell.type)) bad("type", `type must be one of ${PT_TABLE_COLUMN_TYPES.join(", ")}`);
+  if (cell.value !== undefined) {
+    const type = cellTypeOf(col, row, cell);
+    if (type === "boolean" ? typeof cell.value !== "boolean" : NUMERIC_TYPES.has(type) ? typeof cell.value !== "number" || !Number.isFinite(cell.value) : true) {
+      bad("value", `a ${type} cell's value must be ${type === "boolean" ? "true or false" : NUMERIC_TYPES.has(type) ? "a number" : "absent (its words are its content)"}`);
+    }
+  }
+  return out;
+}

package/src/types.ts

@@ -120,6 +120,52 @@ export interface PortableTextTableCell {
    * `highlight`. Renders as the column's `<col data-sortable="true">`, as the V2 table writes it.
    */
   sortable?: boolean;
+  /**
+   * The column's type and its settings (the V2 table's `TableColumn` type, unit, currency, decimals, align, trueLabel,
+   * falseLabel, max, description): named, like `group`, on the column's FIRST-row cell. Nested rather than spread on the
+   * cell because the cell's own `type` is the per-cell type. Renders as the column's `<col data-type …>`, as V2 writes it.
+   */
+  column?: PortableTextTableColumn;
+  /** The per-cell type (the V2 table's `TableCellObject.type`): wins over the row's and the column's. */
+  type?: PortableTextTableColumnType;
+  /**
+   * The typed value of a Number, Price, Yes / No or Rating cell (the V2 table's `TableCellValue`): a number, or true /
+   * false. `content` still holds the words the cell says (V2's `cellText`), so every reader that reads blocks reads it.
+   */
+  value?: number | boolean;
+  /**
+   * A footnote on this cell (the V2 table's `TableCellObject.note`): a `_key` of the table's `footnotes`. The cell renders
+   * `data-note` and the numbered marker V2 writes, `<sup><a href="#<table key>-fn-<n>" aria-label="Note <n>"><n></a></sup>`.
+   */
+  note?: string;
+}
+
+/**
+ * The column types a rich-text table offers: the V2 table's `TableColumnType`s its island offers (table-editor.tsx:80-86
+ * TYPE_UI without the two `dev` ones; V2's rich-text TableBlock passes no `developer`).
+ */
+export const PT_TABLE_COLUMN_TYPES = ["text", "number", "money", "boolean", "rating", "link"] as const;
+export type PortableTextTableColumnType = (typeof PT_TABLE_COLUMN_TYPES)[number];
+
+/** A column's type and settings, the V2 table's `TableColumn` keys (schema/table.ts:44-72), spelled the same way. */
+export interface PortableTextTableColumn {
+  /** Absent reads as `text`. */
+  type?: PortableTextTableColumnType;
+  /** Explains the column: the header's `title`. */
+  description?: string;
+  /** number: written after every value ("kg", "%", "min"). */
+  unit?: string;
+  /** money: ISO 4217 code. Default USD. */
+  currency?: string;
+  /** number / money: fixed decimals. */
+  decimals?: number;
+  /** Default: numbers, money and ratings align end, everything else start. */
+  align?: "start" | "center" | "end";
+  /** boolean: the words. Defaults "Included" / "Not included". */
+  trueLabel?: string;
+  falseLabel?: string;
+  /** rating: the scale. Default 5. */
+  max?: number;
 }
 
 export interface PortableTextTableRow {
@@ -136,6 +182,8 @@ export interface PortableTextTableRow {
   footer?: boolean;
   /** "Highlight this row": `<tr data-highlight="true">`, as the V2 table renders it. */
   highlight?: boolean;
+  /** The per-row type (the V2 table's `TableRow.type`): a pricing matrix mixes Yes / No rows with limit rows. `<tr data-type>`. */
+  type?: PortableTextTableColumnType;
 }
 
 /**
@@ -194,6 +242,17 @@ export interface PortableTextTable extends PortableTextObject {
    * on the figure as `data-responsive` / `data-sticky="true"`, as the V2 table writes them.
    */
   design?: PortableTextTableDesign;
+  /**
+   * Footnotes (the V2 table's `TableValue.footnotes`, the field-lane table's `footnotes`): numbered in order, named by a
+   * cell's `note`, written under the table as V2's `<ol data-footnotes>` inside `<div class="bt-notes">`.
+   */
+  footnotes?: PortableTextTableFootnote[];
+}
+
+/** One table footnote: a stable `_key` (what a cell's `note` names) and its text. */
+export interface PortableTextTableFootnote {
+  _key: string;
+  text: string;
 }
 
 /** The V2 table's `design` keys the rich-text table offers. */
@@ -403,6 +462,9 @@ export const STORABLE_BLOCK_TYPES: ReadonlySet<string> = new Set<string>([
  */
 export const BUILTIN_IMAGE_KEY = "builtin:image" as const;
 export const BUILTIN_EMBED_KEY = "builtin:video" as const;
+/** A callout (`{ tone: info|tip|warning, title, message }`) and a toggle (`{ title, body }`): plain text, read straight. */
+export const BUILTIN_CALLOUT_KEY = "builtin:callout" as const;
+export const BUILTIN_TOGGLE_KEY = "builtin:toggle" as const;
 
 /**
  * The `schemaKey` of a component embedded in rich text. A wire value shared with the dashboard