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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@designcrowd/library.brand-page",
   "description": "A collection of Maker/Designer applications",
-  "version": "6.0.25-json-prereq-2",
+  "version": "6.0.25-json-prereq-3",
   "author": "Design.com Eng",
   "license": "UNLICENSED",
   "type": "module",

package/src/brand-page/utils/migration/migration-20.server.test.ts

@@ -1,16 +1,13 @@
 /**
  * BP-5787 — migration-20 must convert HTML RTE → Tiptap JSON on the SERVER, not
- * just the browser. `generateJSON` (via toRteJson) needs `window.DOMParser`,
- * which pure-node SSR lacks; migration-20 provides a jsdom window for its pass.
+ * just the browser. The HTML→JSON parse needs a DOM parser, which pure-node SSR
+ * lacks. migration-20 resolves one via `resolveHtmlParser` — a jsdom `DOMParser`
+ * INSTANCE on the server (no global mutation), threaded explicitly into the pass.
  *
  * These tests run under the default jsdom environment but DELETE the global
- * `window`/`document` around each case, so `migration20` takes its DOM-less
- * server branch for real (dynamic jsdom import via a runtime-assembled specifier
- * + transient global install + restore). The sibling migration-20.test.ts
- * guards the browser path.
- *
- * (We simulate DOM-less rather than switch this file to a node environment,
- * because the shared test/vitest.setup.js assumes a jsdom `global.window`.)
+ * `window`/`document`/`DOMParser` around each case, so `resolveHtmlParser` takes
+ * its real pure-node branch (dynamic jsdom import → parser instance). The sibling
+ * migration-20.test.ts guards the browser path (native global DOMParser).
  */
 import { describe, test, expect, beforeEach, afterEach } from 'vitest';
 import { migration20 } from './migration-20';
@@ -27,25 +24,31 @@ const model = (contents: any[]) => ({
 const g = globalThis as any;
 let savedWindow: unknown;
 let savedDocument: unknown;
+let savedDOMParser: unknown;
 
 describe('migration20 (server / no DOM) — HTML RTE → Tiptap JSON', () => {
   beforeEach(() => {
-    // Force migration-20's DOM-less server branch.
+    // Force the pure-node path: no global window/document AND no global
+    // DOMParser, so resolveHtmlParser must load jsdom itself.
     savedWindow = g.window;
     savedDocument = g.document;
+    savedDOMParser = g.DOMParser;
     delete g.window;
     delete g.document;
+    delete g.DOMParser;
 
     expect(typeof window).toBe('undefined');
     expect(typeof document).toBe('undefined');
+    expect(typeof DOMParser).toBe('undefined');
   });
 
   afterEach(() => {
     g.window = savedWindow;
     g.document = savedDocument;
+    g.DOMParser = savedDOMParser;
   });
 
-  test('converts a top-level HTML RTE field with no global window', async () => {
+  test('converts a top-level HTML RTE field with no global DOM', async () => {
     const data = model([
       {
         id: '1',
@@ -106,16 +109,17 @@ describe('migration20 (server / no DOM) — HTML RTE → Tiptap JSON', () => {
     expect(c.titleStyle).toEqual({ color: '#fff', fontSize: '1em' });
   });
 
-  test('does not leak the jsdom window into globalThis after the pass', async () => {
+  test('does not mutate globalThis (no window/document/DOMParser leak)', async () => {
     const data = model([
       { id: '4', type: 'banner-section', title: '<p>Leak check</p>' },
     ]);
 
     await migration20(createMigrationData(data));
 
-    // The transient jsdom globals installed during the pass must be restored
-    // to their pre-pass state (deleted here), not leaked.
+    // The pass resolves a parser INSTANCE and never assigns to globalThis, so the
+    // deleted globals must stay absent — no transient install, nothing to leak.
     expect(typeof window).toBe('undefined');
     expect(typeof document).toBe('undefined');
+    expect(typeof DOMParser).toBe('undefined');
   });
 });

package/src/brand-page/utils/migration/migration-20.ts

@@ -1,6 +1,11 @@
 import type { BrandPageModel } from '../../models';
 import type { MigrationData } from '../migration.util';
-import { hasRTEContent, toRteJson } from '../../../brand-page-maker/utils';
+import {
+  hasRTEContent,
+  toRteJson,
+  resolveHtmlParser,
+  type HtmlParser,
+} from '../../../brand-page-maker/utils';
 
 /**
  * BP-5787 — migrate existing inline-HTML RTE content to Tiptap JSON.
@@ -9,9 +14,8 @@ import { hasRTEContent, toRteJson } from '../../../brand-page-maker/utils';
  * published/saved sites still hold RTE fields as HTML strings. This converts
  * them on load, in EVERY environment:
  *   - maker (browser): the loaded model is JSON, so the next save persists JSON.
- *   - web-renderer (SSR / server API routes): converted on read using a jsdom
- *     window (see below), so old sites are normalised without a re-save and
- *     downstream code can treat RTE as JSON.
+ *   - web-renderer (SSR / server API routes): converted on read, so old sites
+ *     are normalised without a re-save and downstream code can treat RTE as JSON.
  *
  * This is a one-time, versioned migration (runAlways is NOT set): legacy sites
  * are at model version < 20 and convert on first load in any environment; once
@@ -19,6 +23,12 @@ import { hasRTEContent, toRteJson } from '../../../brand-page-maker/utils';
  * AI section builders now emit Tiptap JSON directly (they no longer write HTML),
  * so there is no recurring post-load source of HTML to normalise.
  *
+ * HTML→JSON parsing needs a DOM parser. Rather than mutate a global `window`,
+ * the parser is resolved once (native `DOMParser` in the browser, a jsdom
+ * `DOMParser` instance on the server) and threaded explicitly through the
+ * conversion — see resolveHtmlParser / toRteJson. No global state is touched, so
+ * the pass is safe on any server runtime and under concurrent requests.
+ *
  * Scope: only HTML-RTE strings (hasRTEContent) are converted. Plain strings,
  * numbers, and already-JSON docs are left untouched, so the migration is
  * idempotent (re-running on JSON content is a no-op — non-string values are
@@ -26,9 +36,9 @@ import { hasRTEContent, toRteJson } from '../../../brand-page-maker/utils';
  * is handled by recursing into arrays; style objects are intentionally not
  * descended into (they never hold RTE content).
  */
-const convertRteStringsToJson = (value: unknown): void => {
+const convertRteStringsToJson = (value: unknown, parser: HtmlParser): void => {
   if (Array.isArray(value)) {
-    value.forEach((item) => convertRteStringsToJson(item));
+    value.forEach((item) => convertRteStringsToJson(item, parser));
 
     return;
   }
@@ -41,112 +51,37 @@ const convertRteStringsToJson = (value: unknown): void => {
     const field = record[key];
 
     if (typeof field === 'string' && hasRTEContent(field)) {
-      const json = toRteJson(field);
+      const json = toRteJson(field, parser);
 
       if (json) record[key] = json;
     } else if (Array.isArray(field)) {
-      convertRteStringsToJson(field);
+      convertRteStringsToJson(field, parser);
     }
   });
 };
 
-const convertModel = (brandPageModel: BrandPageModel): void => {
+const convertModel = (
+  brandPageModel: BrandPageModel,
+  parser: HtmlParser,
+): void => {
   for (const page of brandPageModel.pages) {
     for (const content of page.contents) {
-      convertRteStringsToJson(content);
+      convertRteStringsToJson(content, parser);
     }
   }
 };
 
-/**
- * HTML→JSON parsing (Tiptap's generateJSON, via toRteJson) needs `window.DOMParser`.
- * In pure-node SSR there is no global DOM, so we provide a jsdom-backed window.
- *
- * Memoised: JSDOM construction is relatively expensive, so one window is created
- * per process and reused. The parser is stateless (each parseFromString builds a
- * fresh document), so sharing the window across requests is safe.
- *
- * `jsdom` is dynamically imported via a runtime-assembled specifier (see
- * getServerWindow), so no bundler can follow it into a browser bundle — this
- * branch only runs when there is no global `window`.
- */
-type ServerWindow = { DOMParser: unknown; document: unknown };
-
-// Minimal shape of the jsdom module, declared locally rather than via an
-// `import()` type, so the specifier "jsdom" never appears anywhere a bundler
-// could follow it (value or type position). Only the members used below.
-type JsdomModule = { JSDOM: new (html?: string) => { window: ServerWindow } };
-
-let serverWindowPromise: Promise<ServerWindow> | null = null;
-
-const getServerWindow = (): Promise<ServerWindow> => {
-  if (!serverWindowPromise) {
-    // The specifier is assembled at runtime rather than written as the string
-    // literal "jsdom", so no bundler (Rollup/Vite in the library build, and any
-    // downstream browser consumer — BrandCrowd.Nuxt, web-renderer, …) can
-    // statically follow it and try to bundle jsdom → cssstyle, whose generated
-    // code breaks Rollup's CommonJS parser. The library stays self-contained
-    // (it still loads its own jsdom at runtime on the server) while never
-    // leaking jsdom into a browser bundle. `@vite-ignore` silences the
-    // "cannot be analyzed" warning the non-literal specifier would otherwise
-    // trigger. At Node runtime this resolves the real jsdom from node_modules.
-    const jsdomModuleId = ['js', 'dom'].join('');
-
-    serverWindowPromise = (
-      import(/* @vite-ignore */ jsdomModuleId) as Promise<JsdomModule>
-    )
-      .then(({ JSDOM }) => new JSDOM('').window)
-      .catch((error) => {
-        // Don't cache the failure — let a later migration retry the import.
-        serverWindowPromise = null;
-
-        throw error;
-      });
-  }
-
-  return serverWindowPromise;
-};
-
 export const migration20 = async (
   migrationResult: MigrationData,
 ): Promise<MigrationData> => {
   const { brandPageModel } = migrationResult;
 
-  // Browser / jsdom test: a DOM is already present — convert directly.
-  if (typeof window !== 'undefined' && typeof document !== 'undefined') {
-    convertModel(brandPageModel);
-
-    return migrationResult;
-  }
-
-  // Pure-node SSR: install a memoised jsdom window as the global for the duration
-  // of the conversion pass, then restore. The pass is fully synchronous (no await
-  // between install and restore), so in Node's single thread no concurrent request
-  // can observe the temporary globals.
-  const serverWindow = await getServerWindow();
-  const globals = globalThis as unknown as {
-    window?: unknown;
-    document?: unknown;
-  };
-  // Track whether the globals existed so we restore exactly — deleting keys we
-  // added rather than leaving `window: undefined` own-properties behind.
-  const hadWindow = 'window' in globals;
-  const hadDocument = 'document' in globals;
-  const prevWindow = globals.window;
-  const prevDocument = globals.document;
-
-  globals.window = serverWindow;
-  globals.document = serverWindow.document;
+  // Resolve a DOM parser for this environment (native in the browser, a jsdom
+  // instance on the server — never touching globals), then convert every
+  // HTML-RTE field to Tiptap JSON with it.
+  const parser = await resolveHtmlParser();
 
-  try {
-    convertModel(brandPageModel);
-  } finally {
-    if (hadWindow) globals.window = prevWindow;
-    else delete globals.window;
-
-    if (hadDocument) globals.document = prevDocument;
-    else delete globals.document;
-  }
+  convertModel(brandPageModel, parser);
 
   return migrationResult;
 };

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

@@ -1,4 +1,5 @@
-import { generateJSON } from '@tiptap/core';
+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';
@@ -17,18 +18,21 @@ export { isTiptapDocument, getRteJsonPlainText };
  *   - renderRteToHtml  — render either form to final HTML for display.
  *   - toRteJson        — normalise either form to JSON for storage.
  *
- * Both directions delegate to Tiptap's own schema-driven converters, fed by the
+ * 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' `renderHTML`, not a hand-maintained copy that drifts when
- * Tiptap changes:
+ * 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 uses generateJSON, which PARSES HTML and so needs a DOM
- *     (window.DOMParser). In the browser and in jsdom tests that global exists;
- *     on the server the only caller is migration-20, which installs a jsdom
- *     window around its conversion pass (see migration/migration-20.ts).
+ *   - 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;
 
@@ -36,6 +40,20 @@ export type RichTextValue = string | JSONContent;
 // 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
@@ -52,17 +70,96 @@ export const renderRteToHtml = (
   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 via
- * generateJSON (needs a DOM — browser/jsdom); documents pass through unchanged.
- * Returns undefined for empty/blank input so callers can omit empty fields.
+ * 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 generateJSON(value, RTE_EXTENSIONS);
+  return htmlToRteJson(value, parser ?? getDefaultParser());
 };