@bettercms-ai/richtext 0.1.0

package/src/ingest.ts

@@ -0,0 +1,233 @@
+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 { randomKey, isValidKey, type KeyGenerator } from "./key";
+import { safeHref } from "./href";
+import type { PtSchema } from "./schema";
+
+/**
+ * HTML → Portable Text.
+ *
+ * This is the INGEST boundary: paste, the Management API, MCP writes, markdown, and every
+ * pre-envelope `{html}` seed still sitting in the database arrive here.
+ *
+ * ── The filter IS the schema ─────────────────────────────────────────────────────────────
+ * `htmlToPortableText` takes a schema directly, and a tag with no place in that schema
+ * produces NO NODE — `<script>` is not "sanitised away", it fails to parse into anything.
+ * That is a stronger guarantee than an allowlist, and it is why one `ptSchemaFor(accept)`
+ * object can drive the editor's toolbar, the server's write validation and this filter at
+ * once. Before, only the DASHBOARD enforced a field's Accept config, so every MCP,
+ * Management-API and AI write bypassed it entirely.
+ *
+ * ── Keys are re-minted, never trusted ────────────────────────────────────────────────────
+ * A `_key` ends up inside a Visual Editor address, which is parsed by splitting on `__`, `.`
+ * and `#`. Imported HTML can carry any key at all, so anything that is not already in our
+ * charset is replaced rather than escaped.
+ */
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  !!v && typeof v === "object" && !Array.isArray(v);
+
+export interface IngestOptions {
+  /** Required in Node: `(html) => new JSDOM(html).window.document`. Browsers pass DOMParser. */
+  parseHtml?: (html: string) => Document;
+  /** What the field accepts. Anything outside it produces no node. */
+  schema?: PtSchema;
+  keyGenerator?: KeyGenerator;
+}
+
+/**
+ * Walk the converted tree and make it ours: valid keys everywhere, and no `href` we would
+ * refuse to render. Doing it here rather than at render time means an unsafe URL never
+ * reaches storage, so it cannot be served by an older consumer that forgot to check.
+ */
+function normalise(value: unknown, key: KeyGenerator): PortableText {
+  if (!Array.isArray(value)) return [];
+  const out: PortableText = [];
+
+  for (const raw of value) {
+    if (!isRecord(raw) || typeof raw._type !== "string") continue;
+    const node: Record<string, unknown> = { ...raw };
+    if (!isValidKey(node._key)) node._key = key();
+
+    if (node._type === "block") {
+      // Two maps, because a markDef meets two fates and a span's marks must follow both:
+      //   remap  — kept defs, original key -> the key we minted for it
+      //   dropped— defs we removed (an unsafe href), whose marks must go with them
+      // A mark left pointing at a dropped def is a mark referring to nothing, which renders
+      // as an unknown mark forever.
+      const remap = new Map<string, string>();
+      const dropped = new Set<string>();
+      const keptDefs: Record<string, unknown>[] = [];
+
+      for (const rawDef of Array.isArray(node.markDefs) ? node.markDefs : []) {
+        if (!isRecord(rawDef)) continue;
+        const def: Record<string, unknown> = { ...rawDef };
+        const original = typeof def._key === "string" ? def._key : "";
+
+        if (def._type === PT_TYPES.link) {
+          const href = typeof def.href === "string" ? safeHref(def.href) : null;
+          // Drop the annotation, keep the text: a blocked link must not delete the words.
+          if (!href) {
+            if (original) dropped.add(original);
+            continue;
+          }
+          def.href = href;
+        }
+
+        if (!isValidKey(def._key)) def._key = key();
+        if (original) remap.set(original, def._key as string);
+        keptDefs.push(def);
+      }
+
+      node.markDefs = keptDefs;
+      node.children = (Array.isArray(node.children) ? node.children : []).map((rawChild) => {
+        if (!isRecord(rawChild)) return rawChild;
+        const child: Record<string, unknown> = { ...rawChild };
+        if (!isValidKey(child._key)) child._key = key();
+        if (Array.isArray(child.marks)) {
+          child.marks = (child.marks as unknown[])
+            .filter((m): m is string => typeof m === "string")
+            .filter((m) => !dropped.has(m))
+            // A decorator ("strong") is not in the map and passes through untouched.
+            .map((m) => remap.get(m) ?? m);
+        }
+        return child;
+      });
+      if (typeof node.style !== "string") node.style = "normal";
+      out.push(node as unknown as PortableTextBlock);
+      continue;
+    }
+
+    out.push(node as never);
+  }
+  return out;
+}
+
+/**
+ * `<table>` → the `builtin:table` block, 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.
+ *
+ * `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.
+ */
+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.
+ */
+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);
+
+function tableRule(key: KeyGenerator): 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);
+      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,
+        _key: key(),
+        schemaKey: BUILTIN_TABLE_KEY,
+        schemaLabel: "Table",
+        fields: { schemaVersion: 1, rows, hasHeader },
+      });
+    },
+  };
+}
+
+const allowsTables = (schema: PtSchema | undefined): boolean =>
+  !schema || schema.blockObjects.some((o) => o.name === TABLE_CAPABILITY);
+
+const isElement = (n: unknown): n is Element =>
+  !!n && typeof n === "object" && (n as Node).nodeType === 1;
+
+export function htmlToPortableText(html: string, opts: IngestOptions = {}): PortableText {
+  if (typeof html !== "string" || html.trim() === "") return [];
+  const key = opts.keyGenerator ?? randomKey;
+  const converted = ptHtmlToPortableText(html, {
+    ...(opts.parseHtml ? { parseHtml: opts.parseHtml } : {}),
+    // `ptSchemaFor` returns a schema DEFINITION — the same object `EditorProvider` takes, so
+    // the editor and this filter are literally configured from one value. The deserialiser
+    // wants the COMPILED form, so the compile happens here rather than at every call site.
+    ...(opts.schema ? { schema: compileSchema(opts.schema as never) } : {}),
+    /**
+     * 🔴 A custom rule is NOT filtered by the compiled schema — it runs before the schema is
+     * consulted and its output is taken as given. So an unconditional table rule would hand a
+     * `<table>` to a field whose Accept config forbids one, which is exactly the Management
+     * 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.
+     */
+    ...(allowsTables(opts.schema) ? { rules: [tableRule(key)] } : {}),
+    keyGenerator: key,
+  });
+  return normalise(converted, key);
+}
+
+/**
+ * Plain text → Portable Text, one block per line.
+ *
+ * Kept separate from the HTML path on purpose, and the distinction has to survive: a bare
+ * string typed by an author is LITERAL. Running it through a markdown or HTML parser is how a
+ * line starting with "#" silently became a heading and "1." became a list — the author's copy
+ * rewritten by a parser they never invoked.
+ */
+export function plainTextToPortableText(text: string, opts: { keyGenerator?: KeyGenerator } = {}): PortableText {
+  const key = opts.keyGenerator ?? randomKey;
+  if (typeof text !== "string" || text === "") return [];
+  return text.split("\n").map((line) => ({
+    _type: "block" as const,
+    _key: key(),
+    style: "normal",
+    markDefs: [],
+    children: [{ _type: "span" as const, _key: key(), text: line, marks: [] }],
+  }));
+}

package/src/key.ts

@@ -0,0 +1,48 @@
+/**
+ * `_key` minting.
+ *
+ * THE CHARSET IS LOAD-BEARING, not cosmetic. A `_key` ends up inside a Visual Editor address
+ * (`<blockId>__<prop>#<key>`), and that address is parsed by splitting on `__`, `.`, `[`, `]`
+ * and `#`. A key containing any of those characters would silently retarget an edit to the
+ * wrong node, so we mint from `[A-Za-z0-9-]` only — no underscore, no dot, no separator.
+ *
+ * Foreign keys are RE-MINTED, never trusted: imported content and pasted HTML can carry
+ * anything, and the address grammar is not a place to find out.
+ *
+ * Determinism matters at migration time. Converting a field twice — once for `data`, once for
+ * `published_data` — with random keys makes two semantically identical copies compare unequal,
+ * which lights up the change feed and the parity check on every entry in the project. The
+ * backfill converts once and writes the same object to both columns; `deterministicKeys()`
+ * exists for the cases that cannot.
+ */
+const ALPHABET = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+
+export const KEY_PATTERN = /^[A-Za-z0-9-]{1,32}$/;
+
+export const isValidKey = (k: unknown): k is string =>
+  typeof k === "string" && KEY_PATTERN.test(k);
+
+/** A fresh random key. 12 chars of this alphabet is ~71 bits; collisions are not a concern. */
+export function randomKey(length = 12): string {
+  let out = "";
+  for (let i = 0; i < length; i += 1) {
+    out += ALPHABET[Math.floor(Math.random() * ALPHABET.length)];
+  }
+  return out;
+}
+
+/**
+ * A counter-based generator, for conversions that must be byte-reproducible.
+ *
+ * Same input, same keys, every run — so a value converted for the draft column and the
+ * published column produces identical output and `jsonbEqual` still says they match.
+ */
+export function deterministicKeys(prefix = "k"): () => string {
+  let n = 0;
+  return () => {
+    n += 1;
+    return `${prefix}${n}`;
+  };
+}
+
+export type KeyGenerator = () => string;

package/src/plain.ts

@@ -0,0 +1,45 @@
+import { BUILTIN_TABLE_KEY, isPortableTextBlock, isPortableTextSpan, PT_TYPES, type PortableText } from "./types";
+
+/**
+ * Portable Text → plain text.
+ *
+ * Replaces `lexicalJsonToText`, and is the one place the repo's oldest formatting trap gets
+ * settled: joining spans with `""` versus `" "`. Spans are runs WITHIN one paragraph, so they
+ * join with nothing — inserting spaces would put a gap in the middle of a bolded word. Blocks
+ * are separate paragraphs, so they join with a newline.
+ */
+export function portableTextToPlainText(value: PortableText | null | undefined): string {
+  if (!Array.isArray(value)) return "";
+  const lines: string[] = [];
+  for (const node of value) {
+    if (isPortableTextBlock(node)) {
+      lines.push(node.children.map((c) => (isPortableTextSpan(c) ? c.text : "")).join(""));
+      continue;
+    }
+    if (node._type === PT_TYPES.code && typeof (node as Record<string, unknown>).code === "string") {
+      lines.push((node as Record<string, unknown>).code as string);
+    }
+    /**
+     * A TABLE is the exception, and it has to be: a reader sees every cell. Left out, the
+     * corpus audit compared a table's stored text against a conversion that reported none and
+     * called 104 sound values a text loss. Cells join with a space and rows with a newline, the
+     * same shape `portableTextToHtml` gives them.
+     *
+     * 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(" "));
+        }
+      }
+      continue;
+    }
+    // Dividers and other embedded blocks contribute no text, which is what a reader wants.
+  }
+  return lines.join("\n");
+}

package/src/read.ts

@@ -0,0 +1,222 @@
+import { PORTABLE_TEXT_FORMAT, PT_TYPES, type PortableText } from "./types";
+import { lexicalToPortableText } from "./from-lexical";
+import { randomKey, type KeyGenerator } from "./key";
+
+/**
+ * THE reader. One function, every stored shape, and it never throws.
+ *
+ * ── What this replaces ───────────────────────────────────────────────────────────────────
+ * Five readers, each guessing at the same six shapes, each maintained by hand, each with its
+ * own idea of what an unrecognised value meant:
+ *
+ *   `RichTextField.toEditorContent`        (dashboard, the dock)
+ *   `pageDocAdapter.richtextToEditorString`(dashboard, the canvas)
+ *   the `LexicalEditor` import path        (dashboard, parse-then-fallback)
+ *   `lexicalJsonToText`                    (dashboard, plain text)
+ *   `renderRichtextValue`                  (dashboard, reflection)
+ *
+ * A comment in the codebase says they "must agree on every shape or a field loads on one
+ * surface and not the other". They did not agree, five separate times, and the symptom each
+ * time was a field that opened blank and then autosaved the blank over real content. Keeping
+ * five copies in sync by hand was the bug; there is now one copy, and it lives in a package
+ * both repos import.
+ *
+ * ── Never throws, by contract ────────────────────────────────────────────────────────────
+ * This runs on every read during the dual-read window. A throw here is a blank field, and a
+ * blank field is one autosave away from being permanent. Unrecognised input returns `[]` and
+ * is reported through `onUnreadable`, never raised.
+ */
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  !!v && typeof v === "object" && !Array.isArray(v);
+
+const looksLikeHtml = (s: string): boolean => /<[a-z!/][\s\S]*>/i.test(s);
+
+export interface ReadOptions {
+  keyGenerator?: KeyGenerator;
+  /** HTML ingest, injected: this module must stay free of any DOM dependency. */
+  fromHtml?: (html: string) => PortableText;
+  /** Called instead of throwing. The migration turns this into a quarantine report. */
+  onUnreadable?: (reason: string, value: unknown) => void;
+}
+
+/**
+ * Make a Portable Text array OURS: a `_key` on every node, `markDefs` on every block.
+ *
+ * Values reach this from two places that predate the spec — a bare array persisted before
+ * `_key` was minted, and the hand-rolled `{version:1, content}` tree the `ui` package's old
+ * 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.
+ */
+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 [];
+    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 = [];
+      if (typeof node.style !== "string") node.style = "normal";
+      node.children = (Array.isArray(node.children) ? node.children : []).map((c) => {
+        if (!isRecord(c)) return c;
+        const child: Record<string, unknown> = { ...c, _key: typeof c._key === "string" && c._key ? c._key : key() };
+        if (child._type === "span" && !Array.isArray(child.marks)) child.marks = [];
+        return child;
+      });
+    }
+    return [node as never];
+  });
+}
+
+function plainBlocks(text: string, key: KeyGenerator): PortableText {
+  if (text === "") return [];
+  return text.split("\n").map((line) => ({
+    _type: "block" as const,
+    _key: key(),
+    style: "normal",
+    markDefs: [],
+    children: [{ _type: "span" as const, _key: key(), text: line, marks: [] }],
+  }));
+}
+
+function fromString(raw: string, key: KeyGenerator, opts: ReadOptions): PortableText {
+  const trimmed = raw.trim();
+  if (trimmed === "") return [];
+
+  // A serialized Lexical state arrives as a JSON STRING, which is why this is tried before
+  // the HTML sniff — `{"root":…}` contains no angle brackets but is not plain text either.
+  if (trimmed.startsWith("{")) {
+    try {
+      const parsed: unknown = JSON.parse(trimmed);
+      if (isRecord(parsed) && isRecord(parsed.root)) {
+        return lexicalToPortableText(parsed, { keyGenerator: key }).value;
+      }
+    } catch {
+      // Not JSON after all. Fall through: it is text that happens to start with a brace.
+    }
+  }
+
+  if (looksLikeHtml(trimmed) && opts.fromHtml) return opts.fromHtml(raw);
+
+  // A bare string is LITERAL. It is NOT run through a markdown parser, because that is how
+  // a line beginning "#" silently became a heading in copy the author never marked up.
+  return plainBlocks(raw, key);
+}
+
+/**
+ * Read any stored rich-text value as Portable Text.
+ *
+ * Shapes handled, in the order they are tested:
+ *   1. `null` / `""`                              → []
+ *   2. `PortableText[]`                           → as-is
+ *   3. `{format:"portable-text-1", value}`        → `.value`
+ *   4. `{format:"lexical-…", value:{root}}`       → converted
+ *   5. `{root:…}` bare Lexical state              → converted
+ *   6. `{format:"bettercms-notion-doc", blocks}`  → walked, recursing per block
+ *   7. `{html:"…"}` pre-envelope seed             → ingested
+ *   8. `"{\"root\":…}"` Lexical JSON string       → parsed, converted
+ *   9. `"<p>…</p>"` bare HTML                     → ingested
+ *  10. `"plain text"`                             → one block per line, literal
+ */
+export function toPortableText(value: unknown, opts: ReadOptions = {}): PortableText {
+  const key = opts.keyGenerator ?? randomKey;
+
+  if (value == null || value === "") return [];
+  if (Array.isArray(value)) return normalizePortableText(value, key);
+  if (typeof value === "string") return fromString(value, key, opts);
+
+  if (!isRecord(value)) {
+    opts.onUnreadable?.(`unsupported ${typeof value}`, value);
+    return [];
+  }
+
+  if (value.format === PORTABLE_TEXT_FORMAT && Array.isArray(value.value)) {
+    return normalizePortableText(value.value, key);
+  }
+
+  // The hand-rolled `{version:1, content}` tree the old `ui` renderer emitted. Structurally
+  // Portable Text, missing only `_key` and `markDefs`, so normalising is the whole conversion.
+  if (value.version === 1 && Array.isArray(value.content)) {
+    return normalizePortableText(value.content, key);
+  }
+
+  if (Array.isArray(value.blocks)) return fromNotionDoc(value.blocks, key, opts);
+
+  // A Lexical envelope carries the state under `value`; a bare state IS the state.
+  if (isRecord(value.value) && isRecord((value.value as Record<string, unknown>).root)) {
+    return lexicalToPortableText(value.value, { keyGenerator: key }).value;
+  }
+  if (isRecord(value.root)) return lexicalToPortableText(value, { keyGenerator: key }).value;
+
+  // The pre-envelope seed. Last, so a real envelope is never mistaken for one.
+  if (typeof value.html === "string") return fromString(value.html, key, opts);
+
+  opts.onUnreadable?.("unrecognised object shape", value);
+  return [];
+}
+
+/**
+ * The `document` / Body format — `{format:"bettercms-notion-doc", version:1, blocks}`.
+ *
+ * Its blocks are heterogeneous and one of them (`richtext`) nests a whole rich-text value of
+ * its own, so this recurses through `toPortableText` rather than duplicating the ladder. That
+ * recursion is the point: a Body containing a rich-text block containing a link now produces
+ * real markDefs, which the old renderer could not express at any depth.
+ */
+function fromNotionDoc(blocks: unknown[], key: KeyGenerator, opts: ReadOptions): PortableText {
+  const out: PortableText = [];
+  for (const raw of blocks) {
+    if (!isRecord(raw)) continue;
+    const type = typeof raw.type === "string" ? raw.type : "";
+
+    if (type === "paragraph") {
+      out.push(...plainBlocks(typeof raw.text === "string" ? raw.text : "", key));
+      continue;
+    }
+    if (type === "richtext") {
+      out.push(...toPortableText(raw.value, { ...opts, keyGenerator: key }));
+      continue;
+    }
+    // `field`, `component` and `reference` blocks reference something that has to be RESOLVED
+    // against the project before it renders. They keep their whole payload in a declared
+    // block object so the resolution can happen at publish time, where the project is known.
+    out.push({
+      _type: PT_TYPES.block,
+      _key: key(),
+      schemaKey: type || "block",
+      schemaLabel: typeof raw.label === "string" ? raw.label : "",
+      fields: {
+        ...(raw.value !== undefined ? { value: raw.value } : {}),
+        ...(typeof raw.fieldType === "string" ? { fieldType: raw.fieldType } : {}),
+      },
+    });
+  }
+  return out;
+}
+
+/**
+ * The structured value on a block's props, or null when there is none.
+ *
+ * Every delivery lane asks this same question — "is there structured content, or do I fall
+ * back to the html cache?" — and each one answering it locally is how the lanes drifted in the
+ * first place: the hosted renderer preferred `content`, the shared React renderer preferred
+ * `content`, and Next and Astro did not look for it at all. One implementation, four callers.
+ *
+ * Accepts every spelling in the wild: a bare array, `{value}` (the new envelope), and
+ * `{content}` (the legacy hand-rolled tree). EMPTY is treated as absent on purpose — an empty
+ * array must fall back to `html` rather than render a blank region.
+ */
+export function readStructuredContent(props: unknown): PortableText | null {
+  if (!isRecord(props)) return null;
+  const candidate = props.content ?? props.value;
+  const arr = Array.isArray(candidate)
+    ? candidate
+    : isRecord(candidate)
+      ? Array.isArray(candidate.content)
+        ? candidate.content
+        : Array.isArray(candidate.value)
+          ? candidate.value
+          : null
+      : null;
+  return arr && arr.length > 0 ? (arr as PortableText) : null;
+}