@bettercms-ai/richtext 0.1.0 → 0.3.0

package/README.md

@@ -63,6 +63,27 @@ is not "sanitised away", it fails to parse into anything. One `ptSchemaFor(accep
 drives the editor's toolbar, the server's write validation, and this filter at once, so they
 cannot drift.
 
+## Tables
+
+A table is a block object of its own — `{_type:"table", rows:[{_key, cells:[{_key, content}]}]}` —
+and a cell holds **blocks**, not a string. So a link, a bolded word or a second paragraph inside a
+cell is ordinary rich text, and the ingest keeps it by ingesting each cell through the same
+converter as the document around it.
+
+```ts
+htmlToPortableText('<table><tbody><tr><td>Pro</td></tr></tbody></table>', { parseHtml, schema })
+// → [{ _type: "table", _key: "…", rows: [{ _key: "…", cells: [{ _key: "…", content: [/* blocks */] }] }] }]
+```
+
+`header` sits on the cell (`<th>`), `head` on the row (`<thead>`), and `span` records a `colspan`
+without collapsing the grid. All three are recorded rather than inferred so that rendering a table
+reproduces the markup it came from — the property the corpus audit's `--tables` pass measures over
+every stored value, and the reason a table may be converted at all.
+
+Tables stored before this — a generic `bcmsBlock` keyed `builtin:table`, holding a string matrix —
+are migrated **on read** by `migrateTable`. Nothing rewrites the database; the reader, the renderer
+and the plain-text pass all recognise the old shape and return the new one.
+
 ## Subpath exports
 
 | import | pulls in | use it for |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/richtext",
-  "version": "0.1.0",
+  "version": "0.3.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/accept.ts

@@ -1,5 +1,6 @@
 import { RICH_TEXT_CAPABILITY_MANIFEST, type RichTextFeature } from './features'
 import type { AllowEntry } from './features'
+import { STYLED_TAGS } from './styled'
 
 /**
  * The Accept model — which HTML elements a rich-text field is allowed to contain.
@@ -123,7 +124,11 @@ export const DEFAULT_RICHTEXT_CONFIG: RichTextConfig = {
 
 /** The tag allowlist the sanitiser enforces for a given Accept set. */
 export function allowedTags(accept: AcceptElement[]): string[] {
-  const tags = new Set<string>(['span']) // spans carry marks; never the reason content is stripped
+  // `span` carries marks and is never the reason content is stripped; the rest of `STYLED_TAGS`
+  // is the site's OWN inline markup, admitted on the same terms and for the same reason the
+  // `styled` annotation is granted to every field — see `styled.ts`. Gating them on an Accept
+  // element would let the sanitiser undo the round trip the annotation exists to make lossless.
+  const tags = new Set<string>(['span', ...STYLED_TAGS])
   for (const el of accept) for (const t of ELEMENT_TAGS[el] ?? []) tags.add(t)
   return [...tags]
 }

package/src/from-lexical.ts

@@ -1,4 +1,4 @@
-import { BUILTIN_TABLE_KEY, PT_TYPES, type PortableText, type PortableTextBlock, type PortableTextMarkDef, type PortableTextSpan } from "./types";
+import { PT_TYPES, type PortableText, type PortableTextBlock, type PortableTextMarkDef, type PortableTextSpan, type PortableTextTable } from "./types";
 import { randomKey, type KeyGenerator } from "./key";
 import { safeHref } from "./href";
 
@@ -190,30 +190,32 @@ function listBlocks(node: LexNode, ctx: Ctx, level: number): PortableText {
   return out;
 }
 
-/** Cells hold TEXT: `builtin:table` stores a string matrix, and matching it keeps one table. */
-function tableBlock(node: LexNode, ctx: Ctx): PortableTextBlock {
+/**
+ * A Lexical table → the `table` block object.
+ *
+ * A cell's own children are BLOCKS — Lexical wraps cell content in paragraphs — and they go
+ * through `blocksFrom` like any other content, so a bolded word, a link or a second paragraph
+ * inside a cell survives the import. Its predecessor flattened every cell to a string, because
+ * the string matrix it wrote had nowhere else to put them.
+ *
+ * `headerState` is Lexical's own flag; `> 0` means the cell is a header. A row whose cells are
+ * ALL headers is a `<thead>` row, which is the only header a Lexical table expresses.
+ */
+function tableBlock(node: LexNode, ctx: Ctx): PortableTextTable {
   const rowNodes = (node.children ?? []).filter(isRecord).filter((r) => (r as LexNode).type === "tablerow");
-  // A cell's own children are BLOCKS (Lexical wraps cell content in paragraphs), and `textOf`
-  // concatenates. Joining the blocks with a space keeps "First" and "Second" two words rather
-  // than the portmanteau a straight concatenation makes of them.
-  const rows = rowNodes.map((r) =>
-    ((r as LexNode).children ?? []).filter(isRecord).map((c) =>
-      ((c as LexNode).children ?? [])
-        .map((b) => textOf(b))
-        .join(" ")
-        .replace(/\s+/g, " ")
-        .trim(),
-    ),
-  );
-  const firstCells = ((rowNodes[0] as LexNode | undefined)?.children ?? []).filter(isRecord);
-  const hasHeader = firstCells.length > 0 && firstCells.every((c) => Number((c as { headerState?: unknown }).headerState ?? 0) > 0);
-  return {
-    _type: PT_TYPES.block,
-    _key: ctx.key(),
-    schemaKey: BUILTIN_TABLE_KEY,
-    schemaLabel: "Table",
-    fields: { schemaVersion: 1, rows, hasHeader },
-  } as unknown as PortableTextBlock;
+  const rows = rowNodes.map((r) => {
+    const cells = ((r as LexNode).children ?? []).filter(isRecord).map((c) => ({
+      _key: ctx.key(),
+      content: ((c as LexNode).children ?? []).flatMap((b) => blocksFrom(b, ctx)),
+      ...(Number((c as { headerState?: unknown }).headerState ?? 0) > 0 ? { header: true } : {}),
+    }));
+    return {
+      _key: ctx.key(),
+      cells,
+      ...(cells.length > 0 && cells.every((c) => c.header) ? { head: true } : {}),
+    };
+  });
+  return { _type: PT_TYPES.table, _key: ctx.key(), rows };
 }
 
 function blocksFrom(value: unknown, ctx: Ctx): PortableText {
@@ -242,13 +244,12 @@ function blocksFrom(value: unknown, ctx: Ctx): PortableText {
       return [{ _type: PT_TYPES.divider, _key: ctx.key() }];
     /**
      * A NATIVE Lexical table — the kind that arrives through paste or import, as opposed to the
-     * versioned `builtin:table` an author inserts. It quarantined here, which was correct while
+     * table an author inserts. It quarantined here, which was correct while
      * nothing could represent it and is now just a migration that refuses to finish.
      *
-     * It lands on the SAME `builtin:table` block the authored one uses, so the product has one
-     * table rather than two with different powers, and `BuiltInBlockCard` can edit a pasted
-     * table the day it converts. `headerState` is Lexical's own flag; `> 0` means the cell is a
-     * header, which is exactly what `hasHeader` records.
+     * It lands on the SAME `table` block object an author inserts, so the product has one table
+     * rather than two with different powers — and because that block object carries real blocks
+     * per cell, a pasted table keeps the marks and links Lexical had in it.
      *
      * ⚠️ This converter is NOT the validation layer, and mapping the node widens what a raw
      * Lexical state can carry into a field that forbids tables — it used to quarantine, and a

package/src/html.ts

@@ -1,6 +1,8 @@
 import { toHTML, type PortableTextHtmlComponents } from "@portabletext/to-html";
-import { BUILTIN_TABLE_KEY, PT_TYPES, type PortableText } from "./types";
+import { PT_TYPES, type PortableText, type PortableTextTable } from "./types";
+import { builtInTableToTable } from "./table";
 import { safeHref } from "./href";
+import { isStyledTag, styledAttrEntries } from "./styled";
 
 /**
  * Portable Text → HTML.
@@ -27,27 +29,59 @@ const esc = (s: string): string =>
 /** Colour marks carry a TOKEN name, never a baked hex, so a rebrand does not orphan content. */
 const TOKEN = /^[a-z0-9-]+$/i;
 
-/** Rows are read defensively: `fields` is `unknown` by type, and one bad row must not throw. */
-const tableRows = (value: Record<string, unknown>): string[][] => {
-  const raw = (value.fields as { rows?: unknown } | undefined)?.rows;
-  if (!Array.isArray(raw)) return [];
-  return raw
-    .filter(Array.isArray)
-    .map((row) => (row as unknown[]).map((c) => (typeof c === "string" ? c : "")));
-};
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  !!v && typeof v === "object" && !Array.isArray(v);
+
+/**
+ * A table, back to the markup it was ingested from.
+ *
+ * 🔴 NO CLASS, NO INVENTED SECTIONS. This renderer emits `<thead>` only where a row carries
+ * `head`, `<th>` only where a cell carries `header`, and `colspan` only where a cell carries a
+ * span greater than one — because the html it produces is COMPARED against the stored markup,
+ * by the block-props parity gate and by the corpus audit's table pass. Its predecessor added
+ * `class="bcms-table"` and promoted the first row to a header, so every stored table diverged
+ * from its own rendition and stayed quarantined html-only forever. Rendering exactly what the
+ * value says is what lets a table convert at all.
+ *
+ * `<tbody>` is the one thing written that the value does not name, and it is not an invention:
+ * every HTML parser inserts one, so the stored markup already has it by the time either side of
+ * that comparison is reparsed.
+ *
+ * Read defensively throughout — `rows` is `unknown` by type, and one bad row must not throw
+ * mid-audit.
+ */
+/** A span attribute, written only when it spans more than one — as the markup writes it. */
+const attr = (name: string, value: unknown): string =>
+  typeof value === "number" && Number.isInteger(value) && value > 1 ? ` ${name}="${value}"` : "";
 
-function tableHtml(value: Record<string, unknown>): string {
-  const rows = tableRows(value);
+function tableHtml(table: PortableTextTable): string {
+  const rows: unknown[] = Array.isArray(table.rows) ? table.rows : [];
   if (rows.length === 0) return "";
-  const width = rows.reduce((max, r) => Math.max(max, r.length), 0);
-  const cells = (row: string[], tag: "th" | "td") =>
-    Array.from({ length: width }, (_, i) => `<${tag}>${esc(row[i] ?? "")}</${tag}>`).join("");
-  // `hasHeader` defaults TRUE when absent, matching the built-in renderer, so a value written
-  // before the flag existed keeps the header row it has always displayed.
-  const hasHeader = (value.fields as { hasHeader?: unknown } | undefined)?.hasHeader !== false;
-  const head = hasHeader ? `<thead><tr>${cells(rows[0]!, "th")}</tr></thead>` : "";
-  const body = rows.slice(hasHeader ? 1 : 0).map((r) => `<tr>${cells(r, "td")}</tr>`).join("");
-  return `<table class="bcms-table">${head}${body ? `<tbody>${body}</tbody>` : ""}</table>`;
+
+  const cellHtml = (raw: 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 attrs = `${attr("colspan", cell.span)}${attr("rowspan", cell.rowSpan)}`;
+    return `<${tag}${attrs}>${portableTextToHtml(cell.content as PortableText, { inline: true })}</${tag}>`;
+  };
+  const rowHtml = (raw: unknown): string => {
+    const cells = isRecord(raw) && Array.isArray(raw.cells) ? raw.cells : [];
+    return `<tr>${cells.map(cellHtml).join("")}</tr>`;
+  };
+
+  // The LEADING RUN of head rows, not every row flagged one: `<thead>` is a section, and a
+  // header row appearing after body rows cannot be lifted out of document order without moving
+  // content the author placed.
+  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);
+  // 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>`;
 }
 
 export interface RenderOptions {
@@ -71,6 +105,7 @@ export interface RenderOptions {
 const components: Partial<PortableTextHtmlComponents> = {
   types: {
     [PT_TYPES.divider]: () => "<hr>",
+    [PT_TYPES.table]: ({ value }) => tableHtml(value as PortableTextTable),
     [PT_TYPES.code]: ({ value }) => {
       const v = value as { code?: unknown; language?: unknown };
       const code = typeof v.code === "string" ? v.code : "";
@@ -87,14 +122,17 @@ const components: Partial<PortableTextHtmlComponents> = {
     [PT_TYPES.block]: ({ value }) => {
       const v = value as { schemaKey?: unknown };
       /**
-       * A 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 — and
-       * that is a regression rather than a status quo, because before tables were ingested at
-       * all their cells at least survived as paragraphs. Every other built-in block (an image,
-       * a video, a component) carries a reference this serialiser cannot resolve, so those stay
-       * markers.
+       * 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.
+       * Every other built-in block (an image, a video, a component) carries a reference this
+       * serialiser cannot resolve, so those stay markers.
+       *
+       * Migrating it here rather than rendering the matrix directly is what keeps ONE table
+       * renderer: a value that came through the reader and one that did not produce the same
+       * page, which is the property four surfaces used to get wrong independently.
        */
-      if (v.schemaKey === BUILTIN_TABLE_KEY) return tableHtml(value as Record<string, unknown>);
+      const legacy = builtInTableToTable(value);
+      if (legacy) return tableHtml(legacy);
       const key = typeof v.schemaKey === "string" && TOKEN.test(v.schemaKey.replace(/^builtin:/, ""))
         ? v.schemaKey
         : "block";
@@ -118,6 +156,25 @@ const components: Partial<PortableTextHtmlComponents> = {
       const target = v.target === "_blank" ? ' target="_blank" rel="noopener noreferrer"' : "";
       return `<a href="${esc(href)}"${target}>${children}</a>`;
     },
+    /**
+     * The site's own inline markup, written back out as itself.
+     *
+     * Every value here came from content, so every value here is escaped and the tag is
+     * re-checked against `STYLED_TAGS` — a markDef can arrive from an import, the Management
+     * API or an AI write, and `<${value.tag}>` with no check is how a stored string becomes a
+     * `<script>`. An unrecognised tag renders its CHILDREN rather than nothing: the words are
+     * the author's, the wrapper is only the design.
+     */
+    [PT_TYPES.styled]: ({ value, children }) => {
+      const v = (value ?? {}) as { tag?: unknown; className?: unknown; attrs?: unknown };
+      const tag = typeof v.tag === "string" ? v.tag.toLowerCase() : "";
+      if (!isStyledTag(tag)) return children;
+      const cls = typeof v.className === "string" && v.className ? ` class="${esc(v.className)}"` : "";
+      const attrs = styledAttrEntries(v.attrs)
+        .map(([name, val]) => ` ${name}="${esc(val)}"`)
+        .join("");
+      return `<${tag}${cls}${attrs}>${children}</${tag}>`;
+    },
     highlight: ({ children }) => `<mark>${children}</mark>`,
     "strike-through": ({ children }) => `<s>${children}</s>`,
   },

package/src/index.ts

@@ -4,6 +4,8 @@ export * from "./href";
 export * from "./key";
 export * from "./from-lexical";
 export * from "./plain";
+export * from "./table";
+export * from "./styled";
 export * from "./read";
 export * from "./accept";
 export * from "./features";

package/src/ingest.ts

@@ -1,8 +1,9 @@
 import { htmlToPortableText as ptHtmlToPortableText, type DeserializerRule } from "@portabletext/html";
 import { compileSchema } from "@portabletext/schema";
-import { BUILTIN_TABLE_KEY, PT_TYPES, TABLE_CAPABILITY, type PortableText, type PortableTextBlock } from "./types";
+import { PT_TYPES, type PortableText, type PortableTextBlock } from "./types";
 import { randomKey, isValidKey, type KeyGenerator } from "./key";
 import { safeHref } from "./href";
+import { isStyledTag, styledAttrsOf, type StyledMarkDef } from "./styled";
 import type { PtSchema } from "./schema";
 
 /**
@@ -105,82 +106,136 @@ function normalise(value: unknown, key: KeyGenerator): PortableText {
 }
 
 /**
- * `<table>` → the `builtin:table` block, which is the ONLY table BetterCMS has.
+ * `<table>` → the `table` block object, which is the ONLY table BetterCMS has.
  *
  * Without this rule a table produces no node — the deserialiser has no table in its schema, so
  * the cells come through as loose paragraphs and the grid is gone. Measured before it existed:
  * two published pages (privacy, gdpr) lost a whole table on conversion, and the text check
  * could not see it because the CELLS survived as text.
  *
- * It lands on the generic block object rather than a bespoke `table` type on purpose, and the
- * reason is written down in `schema.ts`: image, embed, table and columns already store as one
- * `builtin:` block, so this reuses a lane four renderers and `BuiltInBlockCard` already speak.
- * A `table` type would have meant a new schema entry, a new html component and four new
- * renderer branches to carry content that has a home today.
+ * ── A cell is ingested by INGESTING IT ────────────────────────────────────────────────────
+ * Each cell's own markup goes back through `htmlToPortableText`, with the same schema, the same
+ * key generator and the same rules. That is what makes nested markup inside a cell take the
+ * NORMAL span/mark path: a link keeps its markDef, `<strong>` keeps its decorator, two
+ * paragraphs stay two blocks, and a table nested in a cell keeps its own grid. The alternative —
+ * the deserialiser's `next()` on the cell's child nodes — returns spans whose annotation marks
+ * point at markDefs it never hands back, so every link inside a cell would silently become
+ * plain text.
  *
- * `rows` is a string matrix because that IS the built-in table's model — a cell holds text,
- * not marks. Matching it keeps one table in the product instead of two with different powers.
- * `colspan`/`rowspan` collapse to one cell each; short rows are padded by the renderer.
+ * The recursion terminates because a cell's markup is strictly smaller than the table's.
  */
-const BLOCK_TAGS = new Set(["p", "div", "h1", "h2", "h3", "h4", "h5", "h6", "li", "ul", "ol", "blockquote", "pre"]);
-
-/**
- * A cell's text, in order, with a separator only at block boundaries.
- *
- * Two ways to get this wrong, both of which LOSE WORDS. `textContent` alone merges across
- * blocks, so `<p>First</p><p>Second</p>` reads "FirstSecond". Taking only the block children
- * drops everything outside them, so `Before<p>Middle</p>After` keeps just "Middle" — a cell
- * that the deserialiser used to carry whole. Walking the child nodes in order is the version
- * with neither hole.
- */
-const cellText = (cell: Node): string => {
-  let out = "";
-  for (const child of [...cell.childNodes]) {
-    const isBlock = child.nodeType === 1 && BLOCK_TAGS.has(child.nodeName.toLowerCase());
-    out += (isBlock ? " " : "") + (child.textContent ?? "") + (isBlock ? " " : "");
-  }
-  return out.replace(/\s+/g, " ").trim();
-};
 
 /**
  * Rows and cells belonging to THIS table.
  *
  * `querySelectorAll` is a DESCENDANT search, so a table nested inside a cell hands its rows to
- * the outer table and its cells to the outer row: the matrix gains phantom columns and the
- * nested rows are emitted twice.
+ * the outer table and its cells to the outer row: the grid gains phantom columns and the nested
+ * rows are emitted twice.
  */
 const rowsOf = (table: Element): Element[] =>
   [...table.querySelectorAll("tr")].filter((r) => r.closest("table") === table);
 
-const cellsOf = (row: Element): string[] =>
-  [...row.querySelectorAll("th,td")].filter((c) => c.closest("tr") === row).map(cellText);
+const cellsOf = (row: Element): Element[] =>
+  [...row.querySelectorAll("th,td")].filter((c) => c.closest("tr") === row);
 
-function tableRule(key: KeyGenerator): DeserializerRule {
+/** A span attribute, recorded and not honoured — see `PortableTextTableCell`. */
+const spanOf = (cell: Element, name: "colspan" | "rowspan"): number | undefined => {
+  const n = Number(cell.getAttribute(name));
+  return Number.isInteger(n) && n > 1 ? n : undefined;
+};
+
+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(cellsOf).filter((r) => r.length > 0);
+      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;
-      // A header is what the markup SAYS it is. Defaulting to true (as the renderer does when
-      // the flag is absent) would promote the first data row of a headerless table.
-      const headerCell = el.querySelector("thead th, thead td, tr:first-child th");
-      const hasHeader = !!headerCell && headerCell.closest("table") === el;
       // `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 createBlock({
-        _type: PT_TYPES.block,
+      // `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 } : {}) });
+    },
+  };
+}
+
+/**
+ * An inline element Portable Text does not model → the `styled` annotation.
+ *
+ * 🔴 THE REASON THIS EXISTS is measured, not theoretical: 13–28% of the visible text on an
+ * imported site sits inside a `<span class>` in a heading or a paragraph, and none of it could
+ * be made editable while this round trip was lossy — the span came back as bare words and the
+ * design died on the author's first save. `derive-schema` refused those elements ON PURPOSE
+ * for exactly that reason.
+ *
+ * A `<span>` with nothing on it is NOT annotated: it carries no design, so recording it would
+ * mint a markDef per stray wrapper and bloat every value for nothing. The other tags are
+ * annotated bare, because there the TAG is the design (`<small>`, `<sup>`, `<kbd>`).
+ *
+ * Decorator tags (`b/strong`, `i/em`, `u`, `s`, `mark`, `code`) are deliberately absent: they
+ * have real decorators and the standard rules run right after this one.
+ *
+ * `__annotation` is the deserialiser's own internal placeholder — the same one its built-in
+ * link rule returns — so nesting composes for free: `<strong><span class>` comes back as one
+ * span carrying both marks, in that order, and renders back out nested the same way.
+ */
+function styledRule(key: KeyGenerator): DeserializerRule {
+  return {
+    deserialize(el: Node, next) {
+      if (!isElement(el)) return undefined;
+      const tag = el.nodeName.toLowerCase();
+      if (!isStyledTag(tag)) return undefined;
+      const className = el.getAttribute("class")?.trim() || undefined;
+      const attrs = styledAttrsOf(el);
+      if (tag === "span" && !className && !attrs) return undefined;
+      const markDef: StyledMarkDef = {
+        _type: PT_TYPES.styled,
         _key: key(),
-        schemaKey: BUILTIN_TABLE_KEY,
-        schemaLabel: "Table",
-        fields: { schemaVersion: 1, rows, hasHeader },
-      });
+        tag,
+        ...(className ? { className } : {}),
+        ...(attrs ? { attrs } : {}),
+      };
+      return { _type: "__annotation", markDef, children: next(el.childNodes) } as never;
     },
   };
 }
 
+/**
+ * Does this field's schema carry the `styled` annotation?
+ *
+ * Gated for the same reason the table rule is: a custom rule runs BEFORE the compiled schema
+ * and its output is taken as given, so an unconditional rule would be a way past the Accept
+ * config. `ptSchemaFor` grants `styled` to every field, because it is the site's design rather
+ * than an authoring capability — but a caller passing a hand-built schema still decides.
+ */
+const allowsStyled = (schema: PtSchema | undefined): boolean =>
+  !schema || schema.annotations.some((a) => a.name === PT_TYPES.styled);
+
+/** Does this field's schema carry the table block object? Asked by name, not by capability. */
 const allowsTables = (schema: PtSchema | undefined): boolean =>
-  !schema || schema.blockObjects.some((o) => o.name === TABLE_CAPABILITY);
+  !schema || schema.blockObjects.some((o) => o.name === PT_TYPES.table);
 
 const isElement = (n: unknown): n is Element =>
   !!n && typeof n === "object" && (n as Node).nodeType === 1;
@@ -201,12 +256,15 @@ export function htmlToPortableText(html: string, opts: IngestOptions = {}): Port
      * API / MCP bypass this boundary exists to close (see the header).
      *
      * With no schema there is no field context — the backfill and direct callers — and the
-     * full node set is correct. With one, the rule is installed only when that schema carries
-     * the table capability marker. The GENERIC block object is not that test: `ptSchemaFor`
-     * emits it for image, embed, table or columns alike, so gating on it would let a
-     * `<table>` into a field that accepts only images.
+     * full node set is correct. With one, the rule is installed only when that schema declares
+     * the TABLE block object. The GENERIC block object is not that test: `ptSchemaFor` emits it
+     * for an image or an embed alike, so gating on it would let a `<table>` into a field that
+     * accepts only images.
      */
-    ...(allowsTables(opts.schema) ? { rules: [tableRule(key)] } : {}),
+    rules: [
+      ...(allowsTables(opts.schema) ? [tableRule(key, (cell) => htmlToPortableText(cell, opts))] : []),
+      ...(allowsStyled(opts.schema) ? [styledRule(key)] : []),
+    ],
     keyGenerator: key,
   });
   return normalise(converted, key);

package/src/plain.ts

@@ -1,4 +1,5 @@
-import { BUILTIN_TABLE_KEY, isPortableTextBlock, isPortableTextSpan, PT_TYPES, type PortableText } from "./types";
+import { isPortableTextBlock, isPortableTextSpan, PT_TYPES, type PortableText, type PortableTextTable } from "./types";
+import { migrateTable } from "./table";
 
 /**
  * Portable Text → plain text.
@@ -25,21 +26,35 @@ export function portableTextToPlainText(value: PortableText | null | undefined):
      * called 104 sound values a text loss. Cells join with a space and rows with a newline, the
      * same shape `portableTextToHtml` gives them.
      *
+     * Both spellings arrive here — the `table` and the pre-P1c `bcmsBlock` — because this runs
+     * 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.
      */
-    if (node._type === PT_TYPES.block && (node as Record<string, unknown>).schemaKey === BUILTIN_TABLE_KEY) {
-      // `fields` is `unknown` by type and normalisation does not police it, so a table whose
-      // `rows` is an object would throw here and abort the WHOLE corpus audit on one bad row.
-      const rows = (node as { fields?: { rows?: unknown } }).fields?.rows;
-      if (Array.isArray(rows)) {
-        for (const row of rows) {
-          if (Array.isArray(row)) lines.push(row.map((c) => (typeof c === "string" ? c : "")).join(" "));
-        }
-      }
+    const table = migrateTable(node);
+    if (table) {
+      lines.push(...tableLines(table));
       continue;
     }
     // Dividers and other embedded blocks contribute no text, which is what a reader wants.
   }
   return lines.join("\n");
 }
+
+/**
+ * One line per row, cells joined with a space.
+ *
+ * A cell's own blocks go back through this function — a cell is a rich-text field, so a link or
+ * a second paragraph inside one is text a reader sees — and its newlines flatten to spaces,
+ * 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) =>
+    (Array.isArray(row?.cells) ? row.cells : [])
+      .map((cell) => portableTextToPlainText(cell?.content).replace(/\s+/g, " ").trim())
+      .join(" ")
+      .trim(),
+  );

package/src/read.ts

@@ -1,5 +1,6 @@
 import { PORTABLE_TEXT_FORMAT, PT_TYPES, type PortableText } from "./types";
 import { lexicalToPortableText } from "./from-lexical";
+import { migrateTable } from "./table";
 import { randomKey, type KeyGenerator } from "./key";
 
 /**
@@ -48,11 +49,21 @@ export interface ReadOptions {
  * renderer emitted. Both are structurally Portable Text and neither carries markDefs, so
  * `@portabletext/react` would treat a block without them as malformed. Filling them in is
  * cheaper than a migration and makes every historical value renderable today.
+ *
+ * A TABLE is migrated here too, and that is the whole of the P1c read path: every table stored
+ * before P1c is a generic `bcmsBlock` holding a string matrix, and every one of them comes back
+ * out as a `table`. Nothing rewrites the database — the shape a reader sees is settled on the
+ * way out, so a value converted years ago and a value pasted this morning are the same thing to
+ * everything downstream.
  */
 export function normalizePortableText(value: unknown, key: KeyGenerator = randomKey): PortableText {
   if (!Array.isArray(value)) return [];
   return value.flatMap((raw) => {
     if (!isRecord(raw) || typeof raw._type !== "string") return [];
+    // Recursing through this same function is what gives a cell everything a block has: keys,
+    // markDefs, and a nested table in the rare cell that holds one.
+    const table = migrateTable(raw, key, (v, cellKey) => normalizePortableText(v, cellKey));
+    if (table) return [table as never];
     const node: Record<string, unknown> = { ...raw, _key: isRecord(raw) && typeof raw._key === "string" && raw._key ? raw._key : key() };
     if (node._type === "block") {
       if (!Array.isArray(node.markDefs)) node.markDefs = [];

package/src/schema.ts

@@ -1,5 +1,5 @@
 import { ALL_ELEMENTS, type AcceptElement } from "./accept";
-import { PT_TYPES, TABLE_CAPABILITY } from "./types";
+import { PT_TYPES } from "./types";
 
 /**
  * Accept elements → one Portable Text schema.
@@ -24,7 +24,17 @@ import { PT_TYPES, TABLE_CAPABILITY } from "./types";
 export interface PtStyle { name: string; title?: string }
 export interface PtDecorator { name: string; title?: string }
 export interface PtList { name: string; title?: string }
-export interface PtField { name: string; type: string }
+/**
+ * A field on an annotation or block object.
+ *
+ * `type` is the LITERAL UNION `defineSchema` requires, not `string`. Declared wider, every
+ * consumer had to cast at the boundary — the dashboard carried a documented one, and the hand
+ * copy this file replaced needed `as const` on every entry to compile at all. A cast at a
+ * boundary is where a contract gap gets written down and then forgotten, so the contract is
+ * narrowed instead.
+ */
+export type PtFieldType = "string" | "number" | "boolean" | "object";
+export interface PtField { name: string; type: PtFieldType }
 export interface PtAnnotation { name: string; title?: string; fields?: PtField[] }
 export interface PtObject { name: string; title?: string; fields?: PtField[] }
 
@@ -71,7 +81,27 @@ export function ptSchemaFor(accept: readonly AcceptElement[]): PtSchema {
     if (d && has(el)) decorators.push(d);
   }
 
-  const annotations: PtAnnotation[] = [];
+  /**
+   * `styled` is granted to EVERY field, and that is not a leak in the Accept model.
+   *
+   * It is not a capability an author can reach — no toolbar button offers it, and no ingest
+   * mints one from author input. It records the SITE'S OWN inline markup (`<span class>`,
+   * `<time datetime>`) so that a heading an importer bound as a field survives being saved.
+   * Gating it on an Accept element would mean a field that happens not to accept `b` silently
+   * strips the design out of the copy it is holding — the loss this annotation exists to stop,
+   * moved one layer down.
+   */
+  const annotations: PtAnnotation[] = [
+    {
+      name: PT_TYPES.styled,
+      title: "Styled",
+      fields: [
+        { name: "tag", type: "string" },
+        { name: "className", type: "string" },
+        { name: "attrs", type: "object" },
+      ],
+    },
+  ];
   if (has("link") || has("internalLink")) {
     annotations.push({
       name: PT_TYPES.link,
@@ -102,10 +132,10 @@ export function ptSchemaFor(accept: readonly AcceptElement[]): PtSchema {
       ],
     });
   }
-  // Image, embed, table and columns all store as ONE generic block object under their existing
-  // `builtin:` schemaKeys rather than four bespoke types. That keeps a single converter lane
+  // Image, embed and columns all store as ONE generic block object under their existing
+  // `builtin:` schemaKeys rather than three bespoke types. That keeps a single converter lane
   // and leaves `BuiltInBlockCard` (799 lines of working editor UI) untouched.
-  if (has("image") || has("embed") || has("table") || has("columns")) {
+  if (has("image") || has("embed") || has("columns")) {
     blockObjects.push({
       name: PT_TYPES.block,
       title: "Embedded block",
@@ -117,16 +147,22 @@ export function ptSchemaFor(accept: readonly AcceptElement[]): PtSchema {
     });
   }
   /**
-   * A SECOND, table-specific entry — the one exception to "one generic block object".
+   * The table, and it is a REAL block object now rather than the capability marker it used to be.
    *
-   * It exists because the generic entry cannot answer the question the HTML ingest has to ask.
-   * A custom deserializer rule runs BEFORE the compiled schema is consulted, so the rule has to
-   * decide for itself whether this field permits a table; asking "is the generic block object
-   * present?" answers yes for a field that accepts only IMAGES, and a `<table>` then lands in a
-   * field that forbids one. Nothing stores under this name — it is a capability marker read by
-   * `allowsTables`, and the value still stores as `builtin:table` on the generic block.
+   * The marker existed because a table stored on the generic block, so this schema had nothing
+   * table-shaped for the HTML ingest to gate on — and gating on the generic entry answers yes
+   * for a field that accepts only IMAGES, dropping a `<table>` into a field that forbids one.
+   * Asking for `table` by name answers the same question honestly, and the editor gets an
+   * insertable Table that inserts something, instead of a marker it had to filter out.
+   *
+   * ONE field, and it is the whole payload: `rows: [{_key, cells: [{_key, content, header?,
+   * span?}]}]`, spelled in `types.ts`. `defineSchema` describes a block object so the editor can
+   * hold and move it; it does not validate the payload, so a deeper declaration would buy
+   * nothing and drift from the types that do.
    */
-  if (has("table")) blockObjects.push({ name: TABLE_CAPABILITY, title: "Table" });
+  if (has("table")) {
+    blockObjects.push({ name: PT_TYPES.table, title: "Table", fields: [{ name: "rows", type: "object" }] });
+  }
 
   return {
     styles,

package/src/styled.ts

@@ -0,0 +1,138 @@
+/**
+ * The `styled` annotation — a site's own inline markup, carried through Portable Text.
+ *
+ * WHY IT EXISTS. An imported site writes `<h1>Notes from a <span class="serif italic">web
+ * studio</span></h1>`. Portable Text models `strong`/`em`/`underline`/`strike`/`code`/
+ * `highlight` and `link`, and NOTHING ELSE inline — so that span had no node to become,
+ * `unknownMark` rendered its children, and the class was gone the first time an author saved.
+ * That loss is why `derive-schema` deliberately refused to bind any heading containing a
+ * `<span class>`: a field that destroys the design on save is worse than no field at all.
+ *
+ * So this is NOT an authoring mark. There is no toolbar button and no editing UI: it is the
+ * site's design, recorded so the round trip is lossless, and it rides along with whatever the
+ * author actually types inside it.
+ *
+ * ── The attribute allowlist IS the threat model ──────────────────────────────────────────
+ * A markDef is data, and data reaches this platform from an import, the Management API, MCP
+ * and AI writes. Rendering an arbitrary attribute bag would be an XSS primitive wearing a
+ * design system's clothes, so exactly four names plus `data-*` are admitted, and the render
+ * escapes every value. `id` is refused because it is an addressing surface (a duplicate id
+ * breaks anchors and label association), `data-bcms-*` because those attributes ARE the Visual
+ * Editor's binding addresses and content must not be able to mint one. `style` is admitted but
+ * NOT passed through — its value is a language of its own, bounded by `safeStyle` below.
+ */
+
+/** Inline tags a `styled` annotation may wear. Nothing outside this list is ever rendered. */
+export const STYLED_TAGS = ["span", "small", "sup", "sub", "kbd", "abbr", "time"] as const;
+
+export type StyledTag = (typeof STYLED_TAGS)[number];
+
+const TAG_SET: ReadonlySet<string> = new Set<string>(STYLED_TAGS);
+
+export const isStyledTag = (tag: unknown): tag is StyledTag =>
+  typeof tag === "string" && TAG_SET.has(tag);
+
+/**
+ * Attribute names a `styled` annotation may carry.
+ *
+ * Presentational or descriptive only. Never `href`/`src` (a navigation or fetch surface),
+ * never `id` (an addressing surface), never `on*` (script), and never `data-bcms-*` — those
+ * are binding addresses the editor reads, and content that could write one could point an
+ * author's edit at somebody else's field.
+ */
+const ATTR_NAMES: ReadonlySet<string> = new Set(["title", "datetime", "style", "aria-label"]);
+
+const DATA_ATTR = /^data-[a-z][a-z0-9-]*$/;
+
+export const isStyledAttr = (name: string): boolean =>
+  ATTR_NAMES.has(name) || (DATA_ATTR.test(name) && !name.startsWith("data-bcms-"));
+
+/**
+ * CSS an inline run may carry: how the words LOOK inside their own box, and nothing else.
+ *
+ * `style` is the one admitted attribute whose value is itself a language, so the tag allowlist
+ * buys nothing here — a bare passthrough lets any markDef write
+ * `position:fixed;inset:0;z-index:9999`, which is a full-viewport overlay over the published
+ * page (clickjacking, defacement) minted by anyone who can write content, and
+ * `background:url(https://…)` which fetches a third-party URL on every page view. Neither is a
+ * design an import needs, so neither is on the list. Properties that only paint glyphs are.
+ *
+ * Values are checked as well as names, because `url()`, a CSS escape (`\75 rl(`), a comment and
+ * `expression()` are all ways to smuggle a fetch past a name check.
+ */
+const STYLE_PROPS: ReadonlySet<string> = new Set([
+  "color", "background-color", "opacity",
+  "font", "font-family", "font-size", "font-style", "font-weight", "font-variant",
+  "font-feature-settings", "font-variation-settings",
+  "letter-spacing", "line-height", "word-spacing", "white-space", "word-break",
+  "text-align", "text-decoration", "text-decoration-color", "text-decoration-line",
+  "text-decoration-style", "text-transform", "text-underline-offset", "vertical-align",
+]);
+
+const STYLE_VALUE_BAN = /url\(|expression\(|@import|\\|\/\*|[<>]/i;
+
+/**
+ * The declarations of a `style` attribute that survive, rejoined — or undefined when none do.
+ * Custom properties (`--brand`) are kept: they paint nothing on their own, and a site's own CSS
+ * is what decides whether they mean anything.
+ */
+export function safeStyle(css: string): string | undefined {
+  const kept: string[] = [];
+  for (const declaration of css.split(";")) {
+    const at = declaration.indexOf(":");
+    if (at < 0) continue;
+    const name = declaration.slice(0, at).trim().toLowerCase();
+    const value = declaration.slice(at + 1).trim();
+    if (!name || !value) continue;
+    if (!name.startsWith("--") && !STYLE_PROPS.has(name)) continue;
+    if (STYLE_VALUE_BAN.test(value)) continue;
+    kept.push(`${name}:${value}`);
+  }
+  return kept.length ? kept.join(";") : undefined;
+}
+
+/** The annotation's payload, as stored. `tag` is validated again at render time. */
+export interface StyledMarkDef {
+  _type: "styled";
+  _key: string;
+  tag: StyledTag;
+  className?: string;
+  attrs?: Record<string, string>;
+}
+
+/**
+ * The admitted attributes of an element, in source order, or undefined when there are none.
+ *
+ * `class` is deliberately absent — it lives on the markDef as `className`, because it is the
+ * one attribute every consumer of this annotation needs to reach without parsing a bag.
+ */
+export function styledAttrsOf(el: Element): Record<string, string> | undefined {
+  const out: Record<string, string> = {};
+  for (const attr of Array.from(el.attributes)) {
+    const name = attr.name.toLowerCase();
+    if (name === "class" || !isStyledAttr(name)) continue;
+    const value = name === "style" ? safeStyle(attr.value) : attr.value;
+    if (value === undefined) continue;
+    out[name] = value;
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
+/**
+ * The same filter applied to a STORED bag, which may have arrived from anywhere.
+ *
+ * Both ends, and this is the end that matters: a markDef reaches storage from an import, the
+ * Management API, MCP and AI writes, so the ingest filter is a courtesy and this one is the
+ * control. Every renderer of the annotation goes through here.
+ */
+export function styledAttrEntries(attrs: unknown): [string, string][] {
+  if (!attrs || typeof attrs !== "object" || Array.isArray(attrs)) return [];
+  const out: [string, string][] = [];
+  for (const [name, raw] of Object.entries(attrs as Record<string, unknown>)) {
+    if (!isStyledAttr(name) || typeof raw !== "string") continue;
+    const value = name === "style" ? safeStyle(raw) : raw;
+    if (value === undefined) continue;
+    out.push([name, value]);
+  }
+  return out;
+}

package/src/table.ts

@@ -0,0 +1,231 @@
+import {
+  BUILTIN_TABLE_KEY,
+  PT_TYPES,
+  type PortableText,
+  type PortableTextTable,
+  type PortableTextTableCell,
+  type PortableTextTableRow,
+} from "./types";
+import { deterministicKeys, isValidKey, randomKey, type KeyGenerator } from "./key";
+
+/**
+ * The one table, and every older spelling of it.
+ *
+ * THREE SHAPES REACH THIS FILE, and only one of them is written any more:
+ *
+ *   `{_type:"table", rows:[{cells:[{content}]}]}`   ours, since P1c
+ *   `bcmsBlock` + `schemaKey:"builtin:table"`       every table stored BEFORE P1c: a string
+ *                                                   matrix under `fields.rows`, plus `hasHeader`
+ *   `{_type:"table", rows:[{cells:["a","b"]}]}`     content from another system (Sanity's is the
+ *                                                   one found in this corpus): string cells
+ *
+ * They converge HERE rather than at each of the four readers, because the alternative is what
+ * this package was created to end — four places deciding independently what a stored value means,
+ * and a table rendering on one surface and vanishing on another. Nothing rewrites the database:
+ * a legacy row is migrated on the way OUT, every time it is read.
+ *
+ * A string cell becomes one paragraph holding one span. That is lossless in the direction that
+ * matters — the matrix never held marks to lose — and it means the rest of the pipeline has
+ * exactly one cell shape to render, not two.
+ *
+ * ── 🔴 KEYS ARE DERIVED, NEVER MINTED AT RANDOM ──────────────────────────────────────────
+ * This runs on EVERY READ of a value nothing rewrites, so a random `_key` here is a different
+ * key each time the same row is read. Three things break at once: React remounts every cell on
+ * every render because its `key` changed; a Visual Editor address minted against one read points
+ * at nothing on the next; and the migration backfill converting `data` and `published_data`
+ * produces two values that compare unequal, lighting up the change feed for every entry in the
+ * project — the exact trap `deterministicKeys` was added for.
+ *
+ * So a migrated table's keys come from the table's OWN `_key` plus the row and cell INDEX, and
+ * any key the value already carries is kept and reserved so a derived one cannot collide with it.
+ * Same value in, same keys out, on every read, in every process.
+ */
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  !!v && typeof v === "object" && !Array.isArray(v);
+
+export const isPortableTextTable = (n: unknown): n is PortableTextTable =>
+  isRecord(n) && n._type === PT_TYPES.table && Array.isArray(n.rows);
+
+/** A table as it was stored before it had a type: the generic block object under its schemaKey. */
+export const isBuiltInTableBlock = (n: unknown): boolean =>
+  isRecord(n) && n._type === PT_TYPES.block && n.schemaKey === BUILTIN_TABLE_KEY;
+
+/**
+ * How a cell's `content` is read back.
+ *
+ * Injected rather than imported so this file stays free of `read.ts` — the reader already
+ * depends on the table, and a cycle between the two is the kind of thing that resolves at type
+ * level and explodes at runtime. The reader passes `normalizePortableText`; a caller with no
+ * reader (the renderer, the plain-text pass) gets the identity, which is all a legacy string
+ * matrix ever needs.
+ *
+ * It takes the cell's OWN key generator, so a block inside a cell that arrives without a `_key`
+ * is keyed from the cell rather than from the document's random minter.
+ */
+export type CellContentReader = (value: unknown, key: KeyGenerator) => PortableText;
+
+const asIs: CellContentReader = (v) => (Array.isArray(v) ? (v as PortableText) : []);
+
+/**
+ * `<table key>-r0c1` — deterministic, unique among siblings, and inside `KEY_PATTERN`.
+ *
+ * The base is TRUNCATED because a `_key` is capped at 32 characters and an address is parsed by
+ * splitting on the separators; 16 leaves room for `-r99c99-9`, which is longer than any table a
+ * person writes. A collision with a key the value already carries is resolved by suffixing,
+ * never by falling back to randomness.
+ */
+function keyMinter(base: string, reserved: Set<string>) {
+  const prefix = (base.match(/[A-Za-z0-9-]/g) ?? []).join("").slice(0, 16) || "t";
+  return (...parts: (string | number)[]): string => {
+    const candidate = `${prefix}-${parts.join("")}`.slice(0, 30);
+    let key = candidate;
+    for (let n = 1; reserved.has(key); n += 1) key = `${candidate}-${n}`;
+    reserved.add(key);
+    return key;
+  };
+}
+
+/** Every `_key` the stored value already carries, so a derived key cannot land on one. */
+function reservedKeys(rows: unknown[]): Set<string> {
+  const out = new Set<string>();
+  for (const row of rows) {
+    if (!isRecord(row)) continue;
+    if (isValidKey(row._key)) out.add(row._key);
+    for (const cell of Array.isArray(row.cells) ? row.cells : []) {
+      if (isRecord(cell) && isValidKey(cell._key)) out.add(cell._key);
+    }
+  }
+  return out;
+}
+
+/** One line of text as the single block a cell holds. Empty text holds NO block, not an empty one. */
+const textContent = (text: string, key: KeyGenerator): PortableText =>
+  text === ""
+    ? []
+    : [{
+        _type: "block",
+        _key: key(),
+        style: "normal",
+        markDefs: [],
+        children: [{ _type: "span", _key: key(), text, marks: [] }],
+      }];
+
+/** A positive integer span, or nothing. A `colspan="0"` or `"two"` is not a span. */
+const spanOf = (value: unknown): number | undefined => {
+  const n = typeof value === "number" ? value : Number(value);
+  return Number.isInteger(n) && n > 1 ? n : undefined;
+};
+
+type Mint = (...parts: (string | number)[]) => string;
+
+function normalizeCell(raw: unknown, at: [number, number], mint: Mint, read: CellContentReader): PortableTextTableCell {
+  const [row, col] = at;
+  const key = isRecord(raw) && isValidKey(raw._key) ? raw._key : mint("r", row, "c", col);
+  // The cell's own generator: a block inside it that has no key is keyed from the CELL, so the
+  // whole subtree is reproducible from the stored value alone.
+  const inner = deterministicKeys(`${key}-`);
+
+  if (typeof raw === "string" || typeof raw === "number" || typeof raw === "boolean") {
+    return { _key: key, content: textContent(String(raw), inner) };
+  }
+  if (!isRecord(raw)) return { _key: key, content: [] };
+
+  const span = spanOf(raw.span ?? raw.colSpan ?? raw.colspan);
+  const rowSpan = spanOf(raw.rowSpan ?? raw.rowspan);
+  return {
+    _key: key,
+    // `text` is the spelling a string matrix uses once its cells have been given objects; it is
+    // read here so a half-migrated value cannot lose its words.
+    content: Array.isArray(raw.content)
+      ? read(raw.content, inner)
+      : textContent(typeof raw.text === "string" ? raw.text : "", inner),
+    ...(raw.header === true ? { header: true } : {}),
+    ...(span === undefined ? {} : { span }),
+    ...(rowSpan === undefined ? {} : { rowSpan }),
+  };
+}
+
+function normalizeRow(raw: unknown, at: number, mint: Mint, read: CellContentReader): PortableTextTableRow {
+  // A bare array IS a row: that is how the legacy matrix spells one, and how a hand-written
+  // value most often arrives.
+  const cells = Array.isArray(raw) ? raw : isRecord(raw) && Array.isArray(raw.cells) ? raw.cells : [];
+  return {
+    _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 } : {}),
+  };
+}
+
+/**
+ * A pre-P1c `builtin:table` block → the table.
+ *
+ * `hasHeader` defaults TRUE when absent, exactly as the renderer it replaces did, so a value
+ * written before that flag existed keeps the header row it has always displayed. It is a WHOLE
+ * ROW of headers, which is the only header the string matrix could express.
+ */
+export function builtInTableToTable(node: unknown, key: KeyGenerator = randomKey): PortableTextTable | null {
+  if (!isBuiltInTableBlock(node)) return null;
+  const fields = (node as { fields?: unknown }).fields;
+  const raw = isRecord(fields) && Array.isArray(fields.rows) ? fields.rows : [];
+  const hasHeader = isRecord(fields) ? fields.hasHeader !== false : true;
+  const own = (node as { _key?: unknown })._key;
+  const tableKey = isValidKey(own) ? own : key();
+  const mint = keyMinter(tableKey, reservedKeys(raw));
+
+  const rows = raw.map((row, i) => {
+    const normalized = normalizeRow(row, i, mint, asIs);
+    if (!(hasHeader && i === 0)) return normalized;
+    return {
+      ...normalized,
+      head: true,
+      cells: normalized.cells.map((c) => ({ ...c, header: true })),
+    };
+  });
+
+  // 🔴 SQUARE THE GRID. The renderer this replaces padded every row to the widest one, so a
+  // ragged matrix has always DISPLAYED as a full rectangle. Migrating without the padding drops
+  // those cells from the page — a value that rendered five columns rendering four.
+  const width = rows.reduce((max, r) => Math.max(max, r.cells.length), 0);
+  for (const [i, row] of rows.entries()) {
+    while (row.cells.length < width) {
+      row.cells.push({
+        _key: mint("r", i, "c", row.cells.length),
+        content: [],
+        ...(row.head === true ? { header: true } : {}),
+      });
+    }
+  }
+  return { _type: PT_TYPES.table, _key: tableKey, rows, legacy: true };
+}
+
+/**
+ * Any stored table shape → the one table, or `null` when the node is not a table at all.
+ *
+ * Returning `null` rather than throwing or coercing is what lets the reader call this on EVERY
+ * node cheaply: a non-table answers no, and the caller carries on.
+ *
+ * PERMISSIVE ON READ, by design: a shape it does not recognise reads as far as it can rather
+ * than throwing, because a reader that throws is a field that opens blank. The strict test lives
+ * on the WRITE, where the author is present to be told — see `isStorableTable` in `types.ts`.
+ */
+export function migrateTable(
+  node: unknown,
+  key: KeyGenerator = randomKey,
+  read: CellContentReader = asIs,
+): PortableTextTable | null {
+  const builtIn = builtInTableToTable(node, key);
+  if (builtIn) return builtIn;
+  if (!isPortableTextTable(node)) return null;
+  const rows = node.rows as unknown[];
+  const tableKey = isValidKey(node._key) ? node._key : key();
+  const mint = keyMinter(tableKey, reservedKeys(rows));
+  return {
+    _type: PT_TYPES.table,
+    _key: tableKey,
+    rows: rows.map((r, i) => normalizeRow(r, i, mint, read)),
+    // 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 } : {}),
+  };
+}

package/src/types.ts

@@ -67,6 +67,70 @@ export interface PortableTextObject extends PortableTextNode {
 /** The value of a rich-text field: a flat array of blocks and block objects. */
 export type PortableText = (PortableTextBlock | PortableTextObject)[];
 
+/**
+ * ── THE TABLE ────────────────────────────────────────────────────────────────────────────
+ *
+ * A cell holds BLOCKS, not a string. The predecessor stored a string matrix, and the price was
+ * paid on every edge of it: a link, a bolded word or a second paragraph inside a cell was
+ * flattened to text on the way in and could never be authored on the way out. A cell is a small
+ * rich-text field, so it is spelled as one, and every mark, annotation and list the rest of the
+ * document can express works inside it for free.
+ *
+ * `header` is per CELL because a row-header table is a COLUMN of `<th>`; `head` is per ROW
+ * because `<thead>` is a section of the table and a browser does not invent one. Both exist so
+ * the four spellings of a header (`thead`+`th`, `thead`+`td`, bare `th`, none) survive a round
+ * trip instead of being normalised into whichever one we happened to prefer — the html cache is
+ * compared against the stored markup, so an invented `<thead>` reads as content drift.
+ */
+export interface PortableTextTableCell {
+  _key: string;
+  /** The cell's own blocks. Usually one paragraph; a cell may hold several, or none. */
+  content: PortableText;
+  /** `<th>` rather than `<td>`. */
+  header?: boolean;
+  /**
+   * The COLUMN span (`colspan`), RECORDED but not honoured: the grid keeps exactly one cell per
+   * `<td>`, and this is what the renderer writes back out. Honouring it would mean a ragged
+   * model every consumer has to re-square, for a layout the editor cannot author anyway.
+   */
+  span?: number;
+  /**
+   * The ROW span (`rowspan`), recorded on the same terms.
+   *
+   * It is here because DROPPING it is lossy in a way the eye catches immediately: a spanning
+   * cell that comes back spanning one row leaves a hole in the grid, and the round-trip audit
+   * would refuse the whole table over an attribute we simply forgot to carry.
+   */
+  rowSpan?: number;
+}
+
+export interface PortableTextTableRow {
+  _key: string;
+  cells: PortableTextTableCell[];
+  /** The row sat in `<thead>`. Absent means `<tbody>`, which is what a parser assumes. */
+  head?: boolean;
+}
+
+/** A table. The ONE table BetterCMS has — see `PT_TYPES.table`. */
+export interface PortableTextTable extends PortableTextObject {
+  _type: "table";
+  rows: PortableTextTableRow[];
+  /**
+   * Render with the platform's own `class="bcms-table"`, and with every row squared off.
+   *
+   * 🔴 THIS IS A COMPATIBILITY FLAG, and it is the whole of what a pre-P1c table's rendition
+   * needs. The renderer this block object replaces emitted that class on every table and padded
+   * short rows to the widest one, so a value migrated from `builtin:table` MUST keep both or it
+   * renders differently than the `html` sitting beside it in the same row — which is drift, and
+   * the parity gate is right to refuse it.
+   *
+   * Set on every migrated value, and recognised on ingest (`class="bcms-table"` and nothing
+   * else), because that class only ever appears in markup that renderer produced. A table
+   * authored or pasted since P1c carries neither the flag nor the class.
+   */
+  legacy?: boolean;
+}
+
 export const isPortableTextBlock = (n: unknown): n is PortableTextBlock =>
   !!n && typeof n === "object" && (n as PortableTextNode)._type === "block";
 
@@ -104,24 +168,135 @@ export const PT_TYPES = {
   mention: "bcmsMention",
   divider: "bcmsDivider",
   code: "bcmsCode",
+  /**
+   * 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
+   * as foreign content now lands on OUR type and renders, rather than being data nothing draws.
+   */
+  table: "table",
   /** The annotation carrying a hyperlink's `href`. Spelled `link` because that is the spec's convention. */
   link: "link",
+  /**
+   * The annotation carrying a site's OWN inline markup — `<span class>`, `<small>`, `<time
+   * datetime>`. Unprefixed, like `table`, because it describes HTML rather than a BetterCMS
+   * concept. See `styled.ts` for what it may hold and why the list is that short.
+   */
+  styled: "styled",
 } as const;
 
 /**
- * The `schemaKey` of the one table BetterCMS has.
+ * The `schemaKey` a table stored under BEFORE it had a type of its own.
+ *
+ * Every table written up to P1c is a generic `bcmsBlock` carrying a string matrix under this
+ * key. Those rows are still in the database and nothing rewrites them, so this stays READABLE
+ * forever: `migrateTable` (table.ts) turns one into a `table` on the way out, which is why the
+ * reader, the renderer and the plain-text pass all still recognise it.
  *
- * Both table lanes converge here — pasted HTML through `ingest.ts` and a native Lexical
- * `TableNode` through `from-lexical.ts` — and `plain.ts` reads it back out, so it is spelled
- * once for the same reason `PT_TYPES` is: three copies of a string that renders as nothing
- * when it is wrong.
+ * Nothing WRITES it any more.
  */
 export const BUILTIN_TABLE_KEY = "builtin:table" as const;
 
 /**
- * A schema-only marker meaning "this field accepts tables". Never stored: a table's VALUE is a
- * generic block object keyed `builtin:table`. It exists because the HTML ingest's table rule
- * runs before the compiled schema is consulted and has to gate itself, and the generic block
- * object cannot tell a table-accepting field from an image-accepting one.
+ * Every `_type` that may appear at the TOP LEVEL of a stored value.
+ *
+ * Closed on purpose, and short: a text block, the table, the two standalone block objects, and
+ * the generic `bcmsBlock` envelope that carries an image, an embed or columns behind its
+ * `schemaKey` (see `ptSchemaFor`). Anything else is content from another system and has no
+ * renderer here.
+ *
+ * `table` joined the set in P1c, and it is the one member tested by SHAPE as well as by name —
+ * see `isStorableTable`. The Sanity-shaped `{_type:"table", rows:[{cells}]}` that prompted this
+ * list is the reason: refusing it was right while nothing could draw a table, and became wrong
+ * the moment something could. `migrateTable` adopts that shape on read, so the write it used to
+ * refuse now renders every cell.
+ *
+ * `bcmsMention` is included although it is an INLINE object: a mention that has somehow been
+ * hoisted to the top level is ours, harmless, and refusing an author's save over it would be
+ * the cure being worse than the disease.
+ */
+export const STORABLE_BLOCK_TYPES: ReadonlySet<string> = new Set<string>([
+  "block",
+  PT_TYPES.block,
+  PT_TYPES.table,
+  PT_TYPES.code,
+  PT_TYPES.divider,
+  PT_TYPES.mention,
+]);
+
+/**
+ * Top-level nodes whose `_type` this platform cannot store or render, in document order.
+ *
+ * WHY THIS IS A WRITE-TIME CHECK AND NOT A RENDER-TIME SHRUG. An unrecognised block survives
+ * the JSON round trip perfectly — it is data, and every reader here hands it back untouched —
+ * but `portableTextToHtml` has no component for it, so it renders as NOTHING. The `html` on
+ * the envelope is a cache that every delivery surface reads, so the node silently disappears
+ * from the live site while the stored value still looks complete. That is the "renders as
+ * nothing at 200 OK" failure this codebase keeps paying for, and the only place to catch it
+ * cheaply is the write, where the author is still present to be told.
+ *
+ * Returns the offenders rather than a boolean so the refusal can NAME them — `_type` and
+ * `_key` are what let an author find the block in a body of eighty.
+ */
+export function foreignBlocks(value: unknown): { _type: string; _key: string }[] {
+  if (!Array.isArray(value)) return [];
+  const out: { _type: string; _key: string }[] = [];
+  for (const node of value) {
+    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);
+    if (storable) continue;
+    const key = (node as PortableTextNode)._key;
+    out.push({ _type: type, _key: typeof key === "string" ? key : "" });
+  }
+  return out;
+}
+
+/**
+ * Is this `_type:"table"` a table we can actually RENDER?
+ *
+ * 🔴 THE TYPE NAME IS NOT A CONTRACT. `table` is what every Portable Text producer calls a
+ * table, and they do not agree on what is inside one. Admitting the name alone would let any
+ * foreign `rows` through the write guard, and the reader — permissive by design, because a
+ * reader that throws is a field that opens blank — would then coerce whatever it did not
+ * recognise into EMPTY cells. That is the silent-emptying failure the guard exists to stop,
+ * wearing our own type name.
+ *
+ * So exactly two shapes pass, tested cell by cell:
+ *   · ours          — `cells: [{ content: PortableText }]`
+ *   · Sanity's      — `cells: ["a", "b"]`, a row of strings
+ *
+ * Everything else is refused at the write, where the author is present to be told, and stays
+ * readable through `migrateTable` for anything already stored.
+ */
+export function isStorableTable(node: unknown): boolean {
+  if (!node || typeof node !== "object") return false;
+  const rows = (node as { rows?: unknown }).rows;
+  if (!Array.isArray(rows)) return false;
+  return rows.every((row) => {
+    if (!row || typeof row !== "object" || Array.isArray(row)) return false;
+    const cells = (row as { cells?: unknown }).cells;
+    if (!Array.isArray(cells)) return false;
+    return cells.every((cell) => {
+      if (typeof cell === "string") return true;
+      if (!cell || typeof cell !== "object" || Array.isArray(cell)) return false;
+      const content = (cell as { content?: unknown }).content;
+      return Array.isArray(content)
+        && content.every((n) => !!n && typeof n === "object" && typeof (n as PortableTextNode)._type === "string");
+    });
+  });
+}
+
+/**
+ * @deprecated The marker a table-accepting field used to carry INSTEAD of a table.
+ *
+ * It existed because a table stored as a generic block object, so `ptSchemaFor` had nothing
+ * table-shaped to gate the HTML ingest on. `PT_TYPES.table` is that thing now, and it is a real
+ * block object rather than a marker, so the ingest asks for it by name and nothing emits this.
+ *
+ * Kept exported for one release: the dashboard filters it out of the schema it hands
+ * `defineSchema` (`src/lib/richtext/ptSchema.ts`), and removing the export would fail that
+ * import rather than make the filter a harmless no-op. Delete it once that filter is gone.
  */
 export const TABLE_CAPABILITY = "bcmsTableCapability" as const;