Merge pull request #1778 from maizzle/fix/entities-comment-nodes

cossssmin · web-flow · commit 0cb1d65a3a35 · 2026-07-03T15:10:22.000+03:00
fix(transformers): encode entities in comment nodes before purge
diff --git a/src/tests/transformers/entities.test.ts b/src/tests/transformers/entities.test.ts
@@ -118,6 +118,30 @@ describe('entities', () => {
     })
   })
 
+  describe('comment nodes', () => {
+    it('encodes entities inside comments by default', () => {
+      const result = run('<!--[if mso]>\u00A0\u00A0<![endif]-->', true)
+      expect(result).toBe('<!--[if mso]>&nbsp;&nbsp;<![endif]-->')
+    })
+
+    it('encodes comments regardless of conditional syntax', () => {
+      const result = run('<!-- \u00A0 -->', true)
+      expect(result).toBe('<!-- &nbsp; -->')
+    })
+
+    it('scope.comments false leaves comments untouched', () => {
+      const html = '<!--[if mso]>\u00A0<![endif]--><p>\u00A0</p>'
+      const result = entities(html, true, { comments: false })
+      expect(result).toBe('<!--[if mso]>\u00A0<![endif]--><p>&nbsp;</p>')
+    })
+
+    it('scope.text false leaves text nodes untouched', () => {
+      const html = '<!--[if mso]>\u00A0<![endif]--><p>\u00A0</p>'
+      const result = entities(html, true, { text: false })
+      expect(result).toBe('<!--[if mso]>&nbsp;<![endif]--><p>\u00A0</p>')
+    })
+  })
+
   describe('edge cases', () => {
     it('handles empty HTML', () => {
       const result = run('', true)
diff --git a/src/tests/transformers/runTransformers.test.ts b/src/tests/transformers/runTransformers.test.ts
@@ -77,4 +77,11 @@ describe('runTransformers config branches', () => {
     expect(result).not.toContain('data-x')
     expect(result).toContain('data-keep')
   })
+
+  it('preserves whitespace-only MSO conditionals through purge and minify', async () => {
+    const spacer = '<html><head></head><body><!--[if mso]>\u00A0\u00A0<![endif]--><p>x</p></body></html>'
+    const result = await runTransformers(spacer, { css: { purge: true }, html: { minify: true } })
+    expect(result).toContain('<!--[if mso]>&nbsp;&nbsp;')
+    expect(result).toContain('<![endif]-->')
+  })
 })
diff --git a/src/transformers/entities.ts b/src/transformers/entities.ts
@@ -30,9 +30,25 @@ const DEFAULT_ENTITIES: Record<string, string> = {
 }
 
 /**
- * Replace literal Unicode characters in text nodes with their HTML entity
- * equivalents (zero-width joiners, non-breaking spaces, smart quotes,
- * dashes, etc.) for better email-client rendering.
+ * Node types {@link entitiesDom} encodes. Both default to `true`.
+ */
+export interface EntitiesScope {
+  /** Encode entities in text nodes */
+  text?: boolean
+  /**
+   * Encode entities in comment nodes. MSO conditional comment content is
+   * rendered by Outlook, and comment data survives parse round-trips
+   * un-decoded — so encoding here protects whitespace-only conditionals
+   * (e.g. `<Outlook>&nbsp;</Outlook>` spacers) from being collapsed
+   * or removed by email-comb and html-crush downstream.
+   */
+  comments?: boolean
+}
+
+/**
+ * Replace literal Unicode characters in text and comment nodes with their
+ * HTML entity equivalents (zero-width joiners, non-breaking spaces, smart
+ * quotes, dashes, etc.) for better email-client rendering.
  *
  * @param html   HTML string to transform.
  * @param custom Extra entries merged on top of the built-in entity map, or
@@ -52,24 +68,27 @@ const DEFAULT_ENTITIES: Record<string, string> = {
  * // Disable the transform
  * entities('hello world', false)
  */
-export function entities(html: string, custom: EntitiesConfig = true): string {
-  return serialize(entitiesDom(parse(html), custom))
+export function entities(html: string, custom: EntitiesConfig = true, scope: EntitiesScope = {}): string {
+  return serialize(entitiesDom(parse(html), custom, scope))
 }
 
 /**
  * DOM-form of {@link entities} used by the internal transformer pipeline.
  * Takes a parsed DOM, returns a parsed DOM — avoids redundant
  * serialize/parse round-trips when chained with other transformers.
  */
-export function entitiesDom(dom: ChildNode[], custom: EntitiesConfig = true): ChildNode[] {
+export function entitiesDom(dom: ChildNode[], custom: EntitiesConfig = true, scope: EntitiesScope = {}): ChildNode[] {
   if (!custom) return dom
 
   const map = typeof custom === 'object'
     ? merge(custom as Record<string, string>, DEFAULT_ENTITIES)
     : DEFAULT_ENTITIES
 
   walk(dom, (node) => {
-    if (node.type === 'text') {
+    if (
+      (node.type === 'text' && scope.text !== false)
+      || (node.type === 'comment' && scope.comments !== false)
+    ) {
       for (const [char, entity] of Object.entries(map)) {
         node.data = node.data.split(char).join(entity)
       }
diff --git a/src/transformers/index.ts b/src/transformers/index.ts
@@ -47,6 +47,7 @@ import type { TailwindBlock } from '../composables/renderContext.ts'
  * 9.  Filters
  * 10. Base URL
  * 11. URL query
+ * 11.5 Entities in comment nodes (before purge — protects MSO conditionals)
  * 12. Purge CSS (serializes/parses internally around email-comb)
  * 13. Entities
  * + Vue-generated comments stripped here (on serialized string)
@@ -165,6 +166,16 @@ export async function runTransformers(
     dom = urlQueryDom(dom, queryParams, (queryOptions ?? {}) as import('../types/config.ts').UrlQueryOptions)
   }
 
+  /**
+   * 11.5. Encode entities in comment nodes before purge/minify. Raw
+   * invisible chars (e.g. U+00A0 from Vue decoding &nbsp; at compile
+   * time) inside MSO conditionals make email-comb remove the whole
+   * "whitespace-only" conditional and html-crush collapse the chars.
+   * Text nodes are skipped here — purge's internal parse round-trip
+   * would decode them again — comment data survives un-decoded.
+   */
+  if (enabled('entities')) dom = entitiesDom(dom, effective.html?.decodeEntities, { text: false })
+
   // 12. Remove unused CSS (serializes/parses internally around email-comb)
   if (enabled('purgeCss') && effective.css?.purge) {
     const purgeOptions = typeof effective.css.purge === 'object' ? effective.css.purge : {}
