@designcrowd/library.brand-page 6.0.25 → 6.0.26-json-prereq-2

package/src/brand-page-maker/utils/rte-features.test.ts

@@ -0,0 +1,351 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { Editor } from '@tiptap/vue-3';
+import { getRteExtensions } from '../composables/rich-text-editor/getRteExtensions';
+import { toRteJson, renderRteToHtml } from './rte-render.util';
+import { sanitizeRteJson } from './rte-sanitize.util';
+
+/**
+ * BP-5787 — feature-by-feature coverage of the whole RTE JSON pipeline.
+ *
+ * Each case runs a piece of authored HTML through the exact production path:
+ *   HTML → toRteJson (headless editor parse) → sanitizeRteJson → renderRteToHtml
+ *          (DOM-less serialiser)
+ * and asserts the feature survives end-to-end. One combined golden-master lives
+ * in rte-render-parity.test.ts; this file isolates every feature so a
+ * regression in any single one (a mark, a textStyle attr, a link, alignment, a
+ * block node) fails on its own line instead of inside one opaque snapshot.
+ */
+const pipe = (html: string): string => {
+  const json = toRteJson(html);
+
+  return renderRteToHtml(sanitizeRteJson(json));
+};
+
+describe('RTE features — inline marks', () => {
+  it('bold → <strong>', () => {
+    expect(pipe('<p><strong>x</strong></p>')).toContain('<strong>x</strong>');
+  });
+  it('italic → <em>', () => {
+    expect(pipe('<p><em>x</em></p>')).toContain('<em>x</em>');
+  });
+  it('underline → <u>', () => {
+    expect(pipe('<p><u>x</u></p>')).toContain('<u>x</u>');
+  });
+  it('strikethrough → <s>', () => {
+    expect(pipe('<p><s>x</s></p>')).toContain('<s>x</s>');
+  });
+  it('inline code → <code>', () => {
+    expect(pipe('<p><code>x</code></p>')).toContain('<code>x</code>');
+  });
+});
+
+describe('RTE features — mark nesting (decoration must inherit font-size)', () => {
+  // BP-5787 regression: the textStyle <span> that carries font-size must render
+  // OUTSIDE <u>/<s>, so the decoration marks inherit the applied size. Otherwise
+  // text-decoration thickness AND vertical position are computed from the base
+  // paragraph font, giving thin, mis-centred lines on large text (v3 default
+  // priority regression vs v2). Guarded by TextStyle priority: 99.
+  it('font-size <span> wraps <u> (not the reverse)', () => {
+    const out = pipe('<p><span style="font-size: 40px"><u>x</u></span></p>');
+
+    expect(out).toContain('<span style="font-size: 40px"><u>x</u></span>');
+    expect(out).not.toMatch(/<u><span/);
+  });
+
+  it('font-size <span> wraps <s> (not the reverse)', () => {
+    const out = pipe('<p><span style="font-size: 40px"><s>x</s></span></p>');
+
+    expect(out).toContain('<span style="font-size: 40px"><s>x</s></span>');
+    expect(out).not.toMatch(/<s><span/);
+  });
+});
+
+describe('RTE features — textStyle attrs (colour/font/spacing)', () => {
+  it('rgb colour is preserved', () => {
+    expect(
+      pipe('<p><span style="color: rgb(255, 0, 0)">x</span></p>'),
+    ).toContain('color: rgb(255, 0, 0)');
+  });
+
+  it('hex colour is preserved verbatim (Tiptap v3 no longer normalises to rgb)', () => {
+    expect(pipe('<p><span style="color: #00ff00">x</span></p>')).toContain(
+      'color: #00ff00',
+    );
+  });
+
+  it('theme token var(--…) colour survives verbatim (NOT flattened to rgb)', () => {
+    const out = pipe(
+      '<p><span style="color: var(--logo-text-color)">x</span></p>',
+    );
+
+    expect(out).toContain('color: var(--logo-text-color)');
+    expect(out).not.toContain('rgb(');
+  });
+
+  it('single-word font-family is preserved', () => {
+    expect(
+      pipe('<p><span style="font-family: Montserrat">x</span></p>'),
+    ).toContain('font-family: Montserrat');
+  });
+
+  it('multi-word font-family is preserved UNQUOTED (BP-5787 quote-strip)', () => {
+    const out = pipe('<p><span style="font-family: Open Sans">x</span></p>');
+
+    expect(out).toContain('font-family: Open Sans');
+    // must not carry the CSS quotes that the sanitiser would otherwise drop
+    expect(out).not.toContain('font-family: "Open Sans"');
+    expect(out).not.toContain('&quot;');
+  });
+
+  it('font-size / letter-spacing / line-height are preserved', () => {
+    expect(pipe('<p><span style="font-size: 2em">x</span></p>')).toContain(
+      'font-size: 2em',
+    );
+    expect(
+      pipe('<p><span style="letter-spacing: 0.1em">x</span></p>'),
+    ).toContain('letter-spacing: 0.1em');
+    expect(pipe('<p><span style="line-height: 1.5">x</span></p>')).toContain(
+      'line-height: 1.5',
+    );
+  });
+});
+
+describe('RTE features — background colour (highlight)', () => {
+  it('highlight → <mark> with data-color + background-color + color:inherit', () => {
+    const out = pipe(
+      '<p><mark data-color="#ffe08a" style="background-color: #ffe08a">x</mark></p>',
+    );
+
+    expect(out).toContain(
+      '<mark data-color="#ffe08a" style="background-color: #ffe08a; color: inherit">x</mark>',
+    );
+  });
+
+  it('theme token background colour survives verbatim', () => {
+    const out = pipe(
+      '<p><mark data-color="var(--logo-primary-color)" style="background-color: var(--logo-primary-color)">x</mark></p>',
+    );
+
+    expect(out).toContain('background-color: var(--logo-primary-color)');
+  });
+});
+
+describe('RTE features — hyperlinks', () => {
+  it('external link keeps href + target + rel', () => {
+    const out = pipe(
+      '<p><a target="_blank" rel="noopener noreferrer" href="https://example.com">x</a></p>',
+    );
+
+    expect(out).toContain('href="https://example.com"');
+    expect(out).toContain('target="_blank"');
+    expect(out).toContain('rel="noopener noreferrer"');
+  });
+
+  it('internal relative link keeps its href', () => {
+    expect(pipe('<p><a href="/about">x</a></p>')).toContain('href="/about"');
+  });
+
+  it('internal page reference (pageid:) survives the sanitiser', () => {
+    // pageid: hrefs are resolved to real routes later in the view-model
+    // transform; the sanitiser must not strip them.
+    expect(pipe('<p><a href="pageid:abc-123">x</a></p>')).toContain(
+      'href="pageid:abc-123"',
+    );
+  });
+
+  it('javascript: link is dropped (mark removed, text kept)', () => {
+    const out = pipe('<p><a href="javascript:alert(1)">x</a></p>');
+
+    expect(out).not.toContain('<a');
+    expect(out).not.toContain('javascript:');
+    expect(out).toContain('x');
+  });
+
+  it('data: link is dropped', () => {
+    const out = pipe(
+      '<p><a href="data:text/html,<script>1</script>">x</a></p>',
+    );
+
+    expect(out).not.toContain('<a');
+    expect(out).not.toContain('data:');
+  });
+});
+
+describe('RTE features — text alignment', () => {
+  for (const align of ['center', 'right', 'justify', 'left'] as const) {
+    it(`paragraph text-align: ${align}`, () => {
+      expect(pipe(`<p style="text-align: ${align}">x</p>`)).toContain(
+        `<p style="text-align: ${align}">`,
+      );
+    });
+  }
+
+  it('heading carries its alignment', () => {
+    expect(pipe('<h2 style="text-align: center">x</h2>')).toContain(
+      '<h2 style="text-align: center">',
+    );
+  });
+});
+
+describe('RTE features — block nodes', () => {
+  it('headings h1–h6', () => {
+    for (const level of [1, 2, 3, 4, 5, 6]) {
+      expect(pipe(`<h${level}>x</h${level}>`)).toContain(`<h${level}`);
+      expect(pipe(`<h${level}>x</h${level}>`)).toContain(`</h${level}>`);
+    }
+  });
+
+  it('bullet list → <ul><li>', () => {
+    const out = pipe('<ul><li>a</li><li>b</li></ul>');
+
+    expect(out).toContain('<ul>');
+    expect(out).toContain('<li>');
+    expect(out).toContain('a');
+    expect(out).toContain('b');
+  });
+
+  it('ordered list → <ol><li>', () => {
+    expect(pipe('<ol><li>a</li></ol>')).toContain('<ol>');
+  });
+
+  it('blockquote → <blockquote>', () => {
+    expect(pipe('<blockquote><p>q</p></blockquote>')).toContain('<blockquote>');
+  });
+
+  it('code block → <pre><code>', () => {
+    expect(pipe('<pre><code>c</code></pre>')).toContain('<pre><code>');
+  });
+
+  it('hard break → <br/>', () => {
+    expect(pipe('<p>a<br>b</p>')).toContain('<br/>');
+  });
+
+  it('horizontal rule → <hr/>', () => {
+    expect(pipe('<p>a</p><hr><p>b</p>')).toContain('<hr/>');
+  });
+});
+
+describe('RTE features — combinations & escaping', () => {
+  it('nested marks (colour + bold + italic) all survive on the same run', () => {
+    const out = pipe(
+      '<p><span style="color: rgb(1, 2, 3)"><strong><em>x</em></strong></span></p>',
+    );
+
+    expect(out).toContain('color: rgb(1, 2, 3)');
+    expect(out).toContain('<strong>');
+    expect(out).toContain('<em>');
+  });
+
+  it('a styled hyperlink keeps both the colour and the link', () => {
+    const out = pipe(
+      '<p><a href="https://x.com"><span style="color: rgb(0, 151, 215)">x</span></a></p>',
+    );
+
+    expect(out).toContain('href="https://x.com"');
+    expect(out).toContain('color: rgb(0, 151, 215)');
+  });
+
+  it('HTML-special characters in text are escaped', () => {
+    const out = pipe('<p>a &lt;b&gt; &amp; "c"</p>');
+
+    expect(out).toContain('&lt;b&gt;');
+    expect(out).toContain('&amp;');
+    expect(out).not.toContain('<b>');
+  });
+
+  it('serialisation is idempotent (serialize(json) === serialize(reparse))', () => {
+    const html =
+      '<h2 style="text-align: center"><span style="color: var(--logo-text-color); font-family: Open Sans; font-size: 1.5em">Heading</span></h2>' +
+      '<p><strong>bold</strong> <em>italic</em> <u>u</u> <s>s</s> ' +
+      '<mark data-color="#ffe08a" style="background-color: #ffe08a">hl</mark> ' +
+      '<a target="_blank" rel="noopener noreferrer" href="https://x.com">link</a></p>';
+    const once = pipe(html);
+    const twice = renderRteToHtml(sanitizeRteJson(toRteJson(once)));
+
+    expect(twice).toEqual(once);
+  });
+});
+
+describe('RTE features — maker toolbar commands (emit path)', () => {
+  let editors: Editor[] = [];
+
+  afterEach(() => {
+    editors.forEach((e) => e.destroy());
+    editors = [];
+  });
+
+  // Apply a real editor command to a full selection (as the toolbar does),
+  // then run the emitted JSON through sanitise + serialise.
+  const applied = (fn: (e: Editor) => void): string => {
+    const editor = new Editor({
+      extensions: getRteExtensions({ restrictStarterKit: true }),
+    });
+
+    editors.push(editor);
+    editor.commands.setContent('<p>styled text</p>');
+    editor.commands.selectAll();
+    fn(editor);
+
+    return renderRteToHtml(sanitizeRteJson(editor.getJSON()));
+  };
+
+  it('setColor', () => {
+    expect(applied((e) => e.commands.setColor('rgb(255, 0, 0)'))).toContain(
+      'color: rgb(255, 0, 0)',
+    );
+  });
+
+  it('setHighlight (background colour)', () => {
+    const out = applied((e) => e.commands.setHighlight({ color: '#ffe08a' }));
+
+    expect(out).toContain('background-color: #ffe08a');
+    expect(out).toContain('<mark');
+  });
+
+  it('toggleBold / toggleItalic / toggleUnderline / toggleStrike', () => {
+    expect(applied((e) => e.commands.toggleBold())).toContain('<strong>');
+    expect(applied((e) => e.commands.toggleItalic())).toContain('<em>');
+    expect(applied((e) => e.commands.toggleUnderline())).toContain('<u>');
+    expect(applied((e) => e.commands.toggleStrike())).toContain('<s>');
+  });
+
+  it('setFontFamily (multi-word, unquoted)', () => {
+    const out = applied((e) =>
+      (e.commands as { setFontFamily: (f: string) => boolean }).setFontFamily(
+        'Open Sans',
+      ),
+    );
+
+    expect(out).toContain('font-family: Open Sans');
+    expect(out).not.toContain('&quot;');
+  });
+
+  it('setFontSize / setLetterSpacing', () => {
+    expect(
+      applied((e) =>
+        (e.commands as { setFontSize: (v: string) => boolean }).setFontSize(
+          '2em',
+        ),
+      ),
+    ).toContain('font-size: 2em');
+    expect(
+      applied((e) =>
+        (
+          e.commands as { setLetterSpacing: (v: string) => boolean }
+        ).setLetterSpacing('0.1em'),
+      ),
+    ).toContain('letter-spacing: 0.1em');
+  });
+
+  it('setTextAlign', () => {
+    expect(applied((e) => e.commands.setTextAlign('center'))).toContain(
+      'text-align: center',
+    );
+  });
+
+  it('setLink keeps the href through the pipeline', () => {
+    expect(
+      applied((e) => e.commands.setLink({ href: 'https://x.com' })),
+    ).toContain('href="https://x.com"');
+  });
+});

package/src/brand-page-maker/utils/rte-render-parity.test.ts

@@ -0,0 +1,157 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import type { Editor } from '@tiptap/vue-3';
+import { useExternalRichTextEditor } from '../composables/rich-text-editor/useRichTextEditor';
+import {
+  renderRteToHtml,
+  toRteJson,
+  getRteJsonPlainText,
+} from './rte-render.util';
+import {
+  COMPLEX_RTE_HTML,
+  THEME_TOKEN_REF,
+} from '../__fixtures__/complex-rte.fixture';
+
+/**
+ * BP-5787 — golden-master render-parity baseline.
+ *
+ * Captured on the CURRENT (HTML) pipeline. These committed snapshots are the
+ * frozen reference for the HTML→JSON migration:
+ *
+ *   - `editor-normalized-html` is what the editor renders the fixture to today.
+ *     After the migration, `htmlFromJson(getJSON())` MUST equal this snapshot —
+ *     i.e. the JSON pipeline reproduces identical rendered output (no drift).
+ *
+ *   - `editor-json` freezes the JSON shape that BECOMES the stored form. It is
+ *     expected to change exactly once, intentionally, when storage flips to JSON
+ *     (see "expected vs forbidden drift" in docs/plans/BP-5787-...html).
+ *
+ * The headless editor uses the SAME extension set as the live editor
+ * (useExternalRichTextEditor), so it is a faithful stand-in for the renderer.
+ */
+describe('BP-5787 RTE render parity (golden master)', () => {
+  let editor: Editor;
+
+  const makeEditor = (): Editor => {
+    editor = useExternalRichTextEditor().externalEditor;
+
+    return editor;
+  };
+
+  afterEach(() => {
+    editor?.destroy();
+  });
+
+  it('T1 — editor renders the complex fixture to the frozen HTML baseline', () => {
+    const ed = makeEditor();
+
+    ed.commands.setContent(COMPLEX_RTE_HTML);
+
+    // The golden master. The JSON pipeline must reproduce this exactly.
+    expect(ed.getHTML()).toMatchSnapshot('editor-normalized-html');
+  });
+
+  it('T1 — round-trip is idempotent (html → json → html === json → html)', () => {
+    const ed = makeEditor();
+
+    ed.commands.setContent(COMPLEX_RTE_HTML);
+    const pass1 = ed.getHTML();
+    const json = ed.getJSON();
+
+    // Re-seed from the JSON the migration will store, render again.
+    ed.commands.setContent(json);
+    const pass2 = ed.getHTML();
+
+    expect(pass2).toEqual(pass1);
+  });
+
+  it('T6 — freezes the JSON shape that becomes the stored form', () => {
+    const ed = makeEditor();
+
+    ed.commands.setContent(COMPLEX_RTE_HTML);
+
+    expect(ed.getJSON()).toMatchSnapshot('editor-json');
+  });
+
+  it('T2 — theme token ref survives the round-trip (NOT flattened to rgb)', () => {
+    const ed = makeEditor();
+
+    ed.commands.setContent(COMPLEX_RTE_HTML);
+
+    // Today the editor preserves var(--…) in marks; the migration must keep it.
+    expect(ed.getHTML()).toContain(THEME_TOKEN_REF);
+    expect(JSON.stringify(ed.getJSON())).toContain(THEME_TOKEN_REF);
+  });
+
+  it('T1 — render-from-JSON (DOM-less renderer) produces equivalent HTML', () => {
+    // renderRteToHtml serialises JSON → HTML via @tiptap/static-renderer from the
+    // extension schema (no editor/DOM, so it works on the server). Output is
+    // semantically identical to the editor's — the Playwright visual golden-master
+    // is the authority on pixel parity; here we freeze the renderer output and
+    // assert structure.
+    const viaJson = renderRteToHtml(toRteJson(COMPLEX_RTE_HTML));
+
+    expect(viaJson).toMatchSnapshot('serializer-html');
+
+    // marks/nodes preserved
+    expect(viaJson).toContain('<strong>bold</strong>');
+    expect(viaJson).toContain('<em>italic</em>');
+    expect(viaJson).toContain('<u>underline</u>');
+    expect(viaJson).toContain('<s>strike</s>');
+    expect(viaJson).toContain('font-family: Montserrat');
+    expect(viaJson).toContain('font-size: 1.5em');
+    // theme token ref preserved (the crux of BP-5787)
+    expect(viaJson).toContain('color: var(--logo-text-color)');
+    // links + alignment
+    expect(viaJson).toContain('href="/about"');
+    expect(viaJson).toContain('href="https://example.com"');
+    expect(viaJson).toContain('text-align: center');
+    expect(viaJson).toContain('text-align: right');
+  });
+
+  it('T4 — legacy HTML strings render unchanged (back-compat passthrough)', () => {
+    expect(renderRteToHtml(COMPLEX_RTE_HTML)).toEqual(COMPLEX_RTE_HTML);
+  });
+
+  it('T8 — getRteJsonPlainText extracts visible text only (for fraud/translate)', () => {
+    const json = toRteJson(COMPLEX_RTE_HTML)!;
+    const text = getRteJsonPlainText(json);
+
+    expect(text).toContain('Themed heading');
+    expect(text).toContain('bold');
+    expect(text).toContain('external link');
+    // no markup or token refs leak into the extracted text
+    expect(text).not.toContain('<');
+    expect(text).not.toContain('var(--');
+    expect(text).not.toContain('font-size');
+  });
+
+  it('T1 — preserves every mark/node in the fixture', () => {
+    const ed = makeEditor();
+
+    ed.commands.setContent(COMPLEX_RTE_HTML);
+    const html = ed.getHTML();
+
+    // bold / italic / underline / strike
+    expect(html).toContain('<strong>');
+    expect(html).toContain('<em>');
+    expect(html).toContain('<u>');
+    expect(html).toContain('<s>');
+    // textStyle attrs
+    expect(html).toContain('font-family: Montserrat');
+    expect(html).toContain('font-size: 1.5em');
+    expect(html).toContain('letter-spacing: 0.05em');
+    expect(html).toContain('line-height: 1.4');
+    // highlight: data-color keeps the hex; the rendered style is normalised to rgb()
+    expect(html).toContain('data-color="#ffe08a"');
+    expect(html).toContain('background-color: rgb(255, 224, 138)');
+    // literal hex colour is normalised to rgb() by the editor...
+    expect(html).toContain('color: rgb(255, 0, 0)');
+    // ...but the THEME TOKEN ref is preserved verbatim (the crux of BP-5787)
+    expect(html).toContain('color: var(--logo-text-color)');
+    expect(html).toContain('text-align: center');
+    expect(html).toContain('text-align: right');
+    // links
+    expect(html).toContain('href="/about"');
+    expect(html).toContain('href="https://example.com"');
+  });
+});

package/src/brand-page-maker/utils/rte-render.util.ts

@@ -0,0 +1,165 @@
+import { getSchema } from '@tiptap/core';
+import { DOMParser as ProseMirrorDOMParser } from '@tiptap/pm/model';
+import type { JSONContent } from '@tiptap/vue-3';
+import { renderToHTMLString } from '@tiptap/static-renderer/pm/html-string';
+import { getRteExtensions } from '../composables/rich-text-editor/getRteExtensions';
+import { isTiptapDocument, getRteJsonPlainText } from './rich-text-editor.util';
+
+export { isTiptapDocument, getRteJsonPlainText };
+
+/**
+ * BP-5787 — the boundary plumbing for storing RTE as Tiptap JSON.
+ *
+ * An RTE field is either a legacy inline-HTML string (pre-migration, or a
+ * not-yet-migrated published site) or a Tiptap JSON document (post-migration).
+ * These helpers let every consumer treat the two uniformly:
+ *
+ *   - isTiptapDocument — the canonical discriminator (object with type 'doc').
+ *   - renderRteToHtml  — render either form to final HTML for display.
+ *   - toRteJson        — normalise either form to JSON for storage.
+ *
+ * The schema-driven core of both directions is Tiptap/ProseMirror, fed by the
+ * single-source-of-truth extension set (getRteExtensions) — so the mapping lives
+ * in the extensions' schema, not a hand-maintained copy that drifts:
+ *
+ *   - renderRteToHtml uses @tiptap/static-renderer (renderToHTMLString). It is
+ *     DOM-less, so it runs on the server (SSR/publish/preview), not just the
+ *     browser, and needs no Editor instance.
+ *   - toRteJson turns an HTML string into a DOM node with an INJECTED parser and
+ *     feeds it to ProseMirror's schema-driven DOMParser. The HTML→DOM step needs
+ *     a DOM parser; rather than read the global `window.DOMParser` (as Tiptap's
+ *     `generateJSON` does — unusable on a pure-node server and fragile across SSR
+ *     execution contexts), the parser is supplied by the caller: the native
+ *     `DOMParser` in the browser, a jsdom `DOMParser` *instance* on the server
+ *     (see resolveHtmlParser). No global is ever mutated, so the conversion is
+ *     fully isomorphic regardless of how the SSR host bundles/executes this code.
+ */
+export type RichTextValue = string | JSONContent;
+
+// One extension set shared by both directions (render + parse). Schema knowledge
+// lives here, once — Tiptap/extension upgrades propagate to both automatically.
+const RTE_EXTENSIONS = getRteExtensions({ includeLinkRel: true });
+
+// ProseMirror schema derived once from the shared extension set. This is the
+// schema-driven heart of HTML→JSON (no drift); only the HTML→DOM step is injected.
+const RTE_SCHEMA = getSchema(RTE_EXTENSIONS);
+
+/**
+ * A `DOMParser`-compatible object: turns an HTML string into a Document whose
+ * `body` is a DOM node ProseMirror can parse. The browser's native `DOMParser`
+ * and jsdom's `DOMParser` both satisfy this, so the DOM dependency is injected
+ * rather than read from a global.
+ */
+export interface HtmlParser {
+  parseFromString(html: string, type: 'text/html'): Document;
+}
+
+/**
+ * Render an RTE value to final HTML. Legacy HTML strings pass through untouched
+ * (they are already HTML); Tiptap JSON is serialised by @tiptap/static-renderer
+ * from the extension schema — no editor, no DOM — so it works on the server
+ * (SSR/publish), not just the browser.
+ */
+export const renderRteToHtml = (
+  value: RichTextValue | null | undefined,
+): string => {
+  if (value == null || value === '') return '';
+
+  if (typeof value === 'string') return value;
+
+  return renderToHTMLString({ content: value, extensions: RTE_EXTENSIONS });
+};
+
+// Tiptap's elementFromString strips whitespace-only text nodes (pretty-print
+// indentation between tags) before parsing; replicate it so injected-parser
+// output stays identical to the previous generateJSON-based conversion.
+const stripIndentationTextNodes = (node: Node): Node => {
+  const children = node.childNodes;
+
+  for (let i = children.length - 1; i >= 0; i -= 1) {
+    const child = children[i];
+
+    if (
+      child.nodeType === 3 &&
+      child.nodeValue &&
+      /^(\n\s\s|\n)$/.test(child.nodeValue)
+    ) {
+      node.removeChild(child);
+    } else if (child.nodeType === 1) {
+      stripIndentationTextNodes(child);
+    }
+  }
+
+  return node;
+};
+
+const htmlToRteJson = (html: string, parser: HtmlParser): JSONContent => {
+  const body = parser.parseFromString(`<body>${html}</body>`, 'text/html').body;
+  const dom = stripIndentationTextNodes(body);
+
+  return ProseMirrorDOMParser.fromSchema(RTE_SCHEMA).parse(dom).toJSON();
+};
+
+let serverParserPromise: Promise<HtmlParser> | null = null;
+
+/**
+ * Resolve an HtmlParser for the current runtime: the native `DOMParser` in the
+ * browser (and jsdom-based test envs), or a jsdom `DOMParser` INSTANCE on a
+ * pure-node server — created and returned directly, never assigned to a global,
+ * so it is immune to SSR execution-context differences. The jsdom specifier is
+ * assembled at runtime so no bundler follows it into a browser build. Memoised
+ * on the server (JSDOM construction is relatively expensive).
+ */
+export const resolveHtmlParser = async (): Promise<HtmlParser> => {
+  if (typeof DOMParser !== 'undefined') return new DOMParser();
+
+  if (!serverParserPromise) {
+    const jsdomModuleId = ['js', 'dom'].join('');
+
+    serverParserPromise = import(/* @vite-ignore */ jsdomModuleId)
+      .then((mod) => {
+        const { JSDOM } = mod as {
+          JSDOM: new (html?: string) => {
+            window: { DOMParser: new () => HtmlParser };
+          };
+        };
+        const { DOMParser: JsdomDOMParser } = new JSDOM('').window;
+
+        return new JsdomDOMParser();
+      })
+      .catch((error) => {
+        // Don't cache the failure — let a later call retry the import.
+        serverParserPromise = null;
+
+        throw error;
+      });
+  }
+
+  return serverParserPromise;
+};
+
+const getDefaultParser = (): HtmlParser => {
+  if (typeof DOMParser !== 'undefined') return new DOMParser();
+
+  throw new Error(
+    'toRteJson: no global DOMParser in this environment. On the server, pass an ' +
+      'explicit parser as the second argument (see resolveHtmlParser).',
+  );
+};
+
+/**
+ * Normalise an RTE value to a Tiptap JSON document. HTML strings are parsed with
+ * `parser` (defaults to the browser's native DOMParser); JSON documents pass
+ * through unchanged. Returns undefined for empty/blank input so callers can omit
+ * empty fields.
+ */
+export const toRteJson = (
+  value: RichTextValue | null | undefined,
+  parser?: HtmlParser,
+): JSONContent | undefined => {
+  if (value == null || value === '') return undefined;
+
+  if (isTiptapDocument(value)) return value;
+
+  return htmlToRteJson(value, parser ?? getDefaultParser());
+};