Auto-transform the Bible HTML from getPassage so the consumer doesn't have extra steps

.changeset/auto-transform-bible-html.md

@@ -0,0 +1,7 @@
+---
+"@youversion/platform-core": minor
+"@youversion/platform-react-hooks": minor
+"@youversion/platform-react-ui": minor
+---
+
+Auto-transform Bible HTML in `getPassage` — verse wrapping, footnote extraction, sanitization, and table fixes now happen automatically. Consumers no longer need to call `transformBibleHtml` manually. Uses native DOMParser in browser, dynamic `import('linkedom')` on server. Added `data-yv-transformed` idempotency marker so double-transforms are a no-op.

packages/core/src/__tests__/bible.test.ts

@@ -507,18 +507,16 @@ describe('BibleClient', () => {
   });
 
   describe('getPassage', () => {
-    it('should fetch a passage for a verse', async () => {
+    it('should fetch a passage for a verse and auto-transform HTML', async () => {
       const passage = await bibleClient.getPassage(111, 'GEN.1.1');
 
       const { success } = BiblePassageSchema.safeParse(passage);
       expect(success).toBe(true);
 
-      expect(passage).toEqual({
-        id: 'GEN.1.1',
-        content:
-          '<div><div class="pi"><span class="yv-v" v="1"></span><span class="yv-vlbl">1</span>In the beginning God created the heavens and the earth. </div></div>',
-        reference: 'Genesis 1:1',
-      });
+      expect(passage.id).toBe('GEN.1.1');
+      expect(passage.reference).toBe('Genesis 1:1');
+      expect(passage.content).toContain('data-yv-transformed');
+      expect(passage.content).toContain('In the beginning God created');
     });
 
     it('should fetch a passage for a chapter', async () => {
@@ -534,36 +532,39 @@ describe('BibleClient', () => {
     it('should fetch a passage with html format by default', async () => {
       const passage = await bibleClient.getPassage(111, 'GEN.1.1');
 
-      expect(passage.content).toContain('<div>');
+      expect(passage.content).toContain('<div');
+      expect(passage.content).toContain('data-yv-transformed');
     });
 
-    it('should fetch a passage with text format', async () => {
+    it('should not transform text format', async () => {
       const passage = await bibleClient.getPassage(111, 'GEN.1.1', 'text');
 
       expect(passage.content).not.toContain('<div>');
+      expect(passage.content).not.toContain('data-yv-transformed');
     });
 
     it('should fetch a passage with include_headings', async () => {
       const passage = await bibleClient.getPassage(111, 'ROM.1', 'html', true);
 
       expect(passage.id).toBe('ROM.1');
       expect(passage.content).toContain('yv-h');
-      expect(passage.content).not.toContain('yv-n');
+      expect(passage.content).not.toContain('data-verse-footnote');
     });
 
-    it('should fetch a passage with include_notes', async () => {
+    it('should fetch a passage with include_notes and transform footnotes', async () => {
       const passage = await bibleClient.getPassage(111, 'ROM.1', 'html', undefined, true);
 
       expect(passage.id).toBe('ROM.1');
-      expect(passage.content).toContain('yv-n');
+      // Footnotes are transformed into data-verse-footnote anchors
+      expect(passage.content).toContain('data-verse-footnote');
       expect(passage.content).not.toContain('yv-h');
     });
 
     it('should fetch a passage with both include_headings and include_notes', async () => {
       const passage = await bibleClient.getPassage(111, 'ROM.1', 'html', true, true);
 
       expect(passage.id).toBe('ROM.1');
-      expect(passage.content).toContain('yv-n');
+      expect(passage.content).toContain('data-verse-footnote');
       expect(passage.content).toContain('yv-h');
     });
 

packages/core/src/bible-html-transformer.test.ts

@@ -308,7 +308,7 @@ describe('transformBibleHtml - sanitization', () => {
     const result = transformBibleHtml(html, createAdapters());
 
     expect(result.html).not.toContain('onclick');
-    expect(result.html).toContain('<p>');
+    expect(result.html).toContain('<p');
     expect(result.html).toContain('Click me');
   });
 
@@ -336,7 +336,7 @@ describe('transformBibleHtml - sanitization', () => {
     const result = transformBibleHtml(html, createAdapters());
 
     expect(result.html).not.toContain('style');
-    expect(result.html).toContain('<div>');
+    expect(result.html).toContain('<div');
     expect(result.html).toContain('text');
   });
 
@@ -387,6 +387,34 @@ describe('transformBibleHtml - sanitization', () => {
   });
 });
 
+describe('transformBibleHtml - idempotency', () => {
+  it('should add data-yv-transformed marker after transforming', () => {
+    const html =
+      '<div><div class="p"><span class="yv-v" v="1"></span><span class="yv-vlbl">1</span>Text.</div></div>';
+    const result = transformBibleHtml(html, createAdapters());
+
+    expect(result.html).toContain('data-yv-transformed');
+  });
+
+  it('should short-circuit when HTML is already transformed', () => {
+    const html =
+      '<div><div class="p"><span class="yv-v" v="1"></span><span class="yv-vlbl">1</span>Text.</div></div>';
+    const first = transformBibleHtml(html, createAdapters());
+    const second = transformBibleHtml(first.html, createAdapters());
+
+    expect(second.html).toBe(first.html);
+  });
+
+  it('should produce identical output when transformed twice (idempotent)', () => {
+    const html =
+      '<div><div class="p"><span class="yv-v" v="1"></span><span class="yv-vlbl">1</span>Verse text<span class="yv-n f"><span class="ft">A note</span></span>.</div></div>';
+    const first = transformBibleHtml(html, createAdapters());
+    const second = transformBibleHtml(first.html, createAdapters());
+
+    expect(second.html).toBe(first.html);
+  });
+});
+
 describe('transformBibleHtmlForBrowser - DOMParser fallback', () => {
   it('should throw when DOMParser is unavailable', () => {
     const original = globalThis.DOMParser;

packages/core/src/bible-html-transformer.ts

@@ -2,6 +2,8 @@ const NON_BREAKING_SPACE = '\u00A0';
 
 const FOOTNOTE_KEY_ATTR = 'data-footnote-key';
 
+const TRANSFORMED_ATTR = 'data-yv-transformed';
+
 const NEEDS_SPACE_BEFORE = /^[^\s.,;:!?)}\]'"'»›]/;
 
 const ALLOWED_TAGS = new Set([
@@ -339,6 +341,11 @@ export function transformBibleHtml(
   const doc = options.parseHtml(html);
 
   sanitizeBibleHtmlDocument(doc);
+
+  // Already transformed — skip structural transforms
+  if (doc.querySelector(`[${TRANSFORMED_ATTR}]`)) {
+    return { html: options.serializeHtml(doc) };
+  }
   wrapVerseContent(doc);
   assignFootnoteKeys(doc);
 
@@ -348,6 +355,10 @@ export function transformBibleHtml(
   addNbspToVerseLabels(doc);
   fixIrregularTables(doc);
 
+  // Mark as transformed for idempotency
+  const root = doc.body?.firstElementChild ?? doc.body;
+  root?.setAttribute(TRANSFORMED_ATTR, '');
+
   const transformedHtml = options.serializeHtml(doc);
   return { html: transformedHtml };
 }

packages/core/src/bible.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { ApiClient } from './client';
+import { transformBibleHtml, type TransformBibleHtmlOptions } from './bible-html-transformer';
 import { BibleVersionSchema } from './schemas';
 import type {
   BibleBook,
@@ -13,6 +14,33 @@ import type {
   VOTD,
 } from './types';
 
+async function getHtmlAdapters(): Promise<TransformBibleHtmlOptions> {
+  if (typeof globalThis.DOMParser !== 'undefined') {
+    return {
+      parseHtml: (h) =>
+        new globalThis.DOMParser().parseFromString(h, 'text/html') as unknown as Document,
+      serializeHtml: (doc) => doc.body.innerHTML,
+    };
+  }
+  let linkedom;
+  try {
+    linkedom = await import('linkedom');
+  } catch {
+    throw new Error(
+      'Server-side HTML transformation requires "linkedom". ' +
+        'Install it as a dependency or pass format: "text" to skip transformation.',
+    );
+  }
+  return {
+    parseHtml: (h) =>
+      new linkedom.DOMParser().parseFromString(
+        `<html><body>${h}</body></html>`,
+        'text/html',
+      ) as unknown as Document,
+    serializeHtml: (doc) => doc.body.innerHTML,
+  };
+}
+
 /**
  * Client for interacting with Bible API endpoints.
  */
@@ -234,18 +262,18 @@ export class BibleClient {
 
   /**
    * Fetches a passage (range of verses) from the Bible using the passages endpoint.
-   * This is the new API format that returns HTML-formatted content.
    *
-   * Note: The HTML returned from the API contains inline footnote content that should
-   * be transformed before rendering. Use `transformBibleHtml()` or
-   * `transformBibleHtmlForBrowser()` to clean up the HTML and extract footnotes.
+   * When format is "html" (the default), the returned content is automatically
+   * sanitized and transformed — verse content is wrapped for CSS targeting,
+   * footnotes are extracted into data attributes, and verse labels get
+   * non-breaking spaces. No manual call to `transformBibleHtml` is needed.
    *
    * @param versionId The version ID.
    * @param usfm The USFM reference (e.g., "JHN.3.1-2", "GEN.1", "JHN.3.16").
    * @param format The format to return ("html" or "text", default: "html").
    * @param include_headings Whether to include headings in the content.
    * @param include_notes Whether to include notes in the content.
-   * @returns The requested BiblePassage object with HTML content.
+   * @returns The requested BiblePassage object.
    *
    * @example
    * ```ts
@@ -258,9 +286,8 @@ export class BibleClient {
    * // Get an entire chapter
    * const chapter = await bibleClient.getPassage(3034, "GEN.1");
    *
-   * // Transform HTML before rendering
-   * const passage = await bibleClient.getPassage(3034, "JHN.3.16", "html", true, true);
-   * const transformed = transformBibleHtmlForBrowser(passage.content);
+   * // Get plain text (no transformation applied)
+   * const text = await bibleClient.getPassage(3034, "JHN.3.16", "text");
    * ```
    */
   async getPassage(
@@ -286,7 +313,18 @@ export class BibleClient {
     if (include_notes !== undefined) {
       params.include_notes = include_notes;
     }
-    return this.client.get<BiblePassage>(`/v1/bibles/${versionId}/passages/${usfm}`, params);
+    const passage = await this.client.get<BiblePassage>(
+      `/v1/bibles/${versionId}/passages/${usfm}`,
+      params,
+    );
+
+    if (format === 'html') {
+      const adapters = await getHtmlAdapters();
+      const { html } = transformBibleHtml(passage.content, adapters);
+      return { ...passage, content: html };
+    }
+
+    return passage;
   }
 
   /**

packages/ui/src/components/verse.tsx

@@ -345,9 +345,8 @@ export const Verse = {
       }: VerseHtmlProps,
       ref,
     ): ReactNode => {
-      // transformBibleHtml uses the browser's native DOMParser, which doesn't
-      // exist during SSR. Return raw html on the server; the client-side
-      // useLayoutEffect in BibleTextHtml will handle it after hydration.
+      // SSR safety: DOMParser doesn't exist during server render.
+      // Idempotent — already-transformed HTML from getPassage is a no-op.
       const transformedHtml = useMemo(
         () => (typeof window === 'undefined' ? html : transformBibleHtml(html).html),
         [html],