@youversion/platform-core 1.20.2 → 1.21.0

package/.turbo/turbo-build.log

@@ -1,18 +1,29 @@
 
-> @youversion/platform-core@1.20.2 build /home/runner/work/platform-sdk-react/platform-sdk-react/packages/core
-> tsup src/index.ts --format cjs,esm --dts
+> @youversion/platform-core@1.21.0 build /home/runner/work/platform-sdk-react/platform-sdk-react/packages/core
+> tsup src/index.ts src/browser.ts src/server.ts --format cjs,esm --dts
 
-CLI Building entry: src/index.ts
+CLI Building entry: src/browser.ts, src/index.ts, src/server.ts
 CLI Using tsconfig: tsconfig.json
 CLI tsup v8.5.0
 CLI Target: es2022
 CJS Build start
 ESM Build start
-CJS dist/index.cjs 56.19 KB
-CJS ⚡️ Build success in 59ms
-ESM dist/index.js 53.04 KB
-ESM ⚡️ Build success in 59ms
+ESM dist/browser.js        135.00 B
+ESM dist/server.js         443.00 B
+ESM dist/index.js          53.56 KB
+ESM dist/chunk-2Z2S2WY3.js 7.74 KB
+ESM ⚡️ Build success in 65ms
+CJS dist/browser.cjs 8.75 KB
+CJS dist/index.cjs   64.03 KB
+CJS dist/server.cjs  8.76 KB
+CJS ⚡️ Build success in 66ms
 DTS Build start
-DTS ⚡️ Build success in 1992ms
-DTS dist/index.d.cts 33.09 KB
-DTS dist/index.d.ts  33.09 KB
+DTS ⚡️ Build success in 3000ms
+DTS dist/server.d.cts           863.00 B
+DTS dist/index.d.cts            33.68 KB
+DTS dist/browser.d.cts          93.00 B
+DTS dist/browser-DzQ1yOHv.d.cts 2.67 KB
+DTS dist/server.d.ts            862.00 B
+DTS dist/index.d.ts             33.68 KB
+DTS dist/browser.d.ts           92.00 B
+DTS dist/browser-DzQ1yOHv.d.ts  2.67 KB

package/AGENTS.md

@@ -17,6 +17,11 @@ highlights.ts                # HighlightsClient - user highlights
 YouVersionAPI.ts             # Base YouVersion API client
 SignInWithYouVersionPKCE.ts  # PKCE auth implementation
 StorageStrategy.ts           # Storage interface (SessionStorage, MemoryStorage)
+bible-html-transformer.ts    # Runtime-agnostic transformer (also contains browser convenience fn)
+bible-html-transformer-server.ts # Server convenience wrapper (uses linkedom)
+browser.ts                   # Browser entry point
+server.ts                    # Server entry point
+index.ts                     # Main entry point (runtime-agnostic)
 ```
 
 ## PUBLIC API
@@ -26,18 +31,58 @@ StorageStrategy.ts           # Storage interface (SessionStorage, MemoryStorage)
 - `HighlightsClient`: Manage user highlights
 - `SignInWithYouVersionPKCE()`: PKCE auth flow function
 - `SessionStorage`, `MemoryStorage`: Storage strategies
+- `transformBibleHtml`: Runtime-agnostic Bible HTML transformer (requires DOM adapters)
+- `TransformBibleHtmlOptions`: Options for DOM parsing and serialization
 
 ## DOs / DON'Ts
 
-✅ Do: Keep this package **framework-agnostic** (no React, no DOM, no browser-only APIs)
+✅ Do: Keep this package **framework-agnostic** (no React, no environment-specific dependencies in main export)
+✅ Do: Provide pure, runtime-agnostic functions as the main export
+✅ Do: Use environment-specific entry points (`/browser`, `/server`) for convenience wrappers
 ✅ Do: Define all input/output types in `schemas/` using Zod; schemas are the single source of truth
 ✅ Do: Reuse `YouVersionAPI` base client for new service clients
 ✅ Do: Parse API responses with Zod schemas for validation
 
-❌ Don't: Import React, `window`, `document`, or browser storage APIs directly
+❌ Don't: Import React or React-specific APIs
+❌ Don't: Bundle linkedom in browser builds (use `/server` entry point for server-side code)
+❌ Don't: Include environment-specific code in the default entry point
 ❌ Don't: Bypass Zod validation for API responses
 ❌ Don't: Implement UI, hooks, or React state here
 
+## ENVIRONMENT-SPECIFIC EXPORTS
+
+The Bible HTML transformer provides both a runtime-agnostic core and environment-specific convenience wrappers:
+
+- `@youversion/platform-core` → Runtime-agnostic `transformBibleHtml` (requires DOM adapters)
+- `@youversion/platform-core/browser` → Browser convenience wrapper (uses native DOMParser)
+- `@youversion/platform-core/server` → Server convenience wrapper (uses linkedom)
+
+**Examples:**
+
+```ts
+// Runtime-agnostic (works anywhere with custom adapters)
+import { transformBibleHtml } from '@youversion/platform-core';
+
+const result = transformBibleHtml(html, {
+  parseHtml: (h) => new DOMParser().parseFromString(h, 'text/html'),
+  serializeHtml: (doc) => doc.body.innerHTML,
+});
+
+// Browser convenience (uses native DOMParser)
+import { transformBibleHtml } from '@youversion/platform-core/browser';
+
+const result = transformBibleHtml(html);
+
+// Server convenience (uses linkedom, requires: npm install linkedom)
+import { transformBibleHtml } from '@youversion/platform-core/server';
+
+const result = transformBibleHtml(html);
+```
+
+**Why separate entry points?**
+
+This architecture keeps the main export truly runtime-agnostic while providing ergonomic convenience wrappers for common environments. The separate `/browser` and `/server` entry points ensure optimal bundle sizes - linkedom won't be bundled in browser builds.
+
 ## ADDING A NEW ENDPOINT OR CLIENT
 
 1. **Define types** in `schemas/` using Zod:

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @youversion/platform-core
 
+## 1.21.0
+
+### Minor Changes
+
+- 87ad436: **`@youversion/platform-core`**: Add `transformBibleHtml` — a runtime-agnostic Bible HTML transformer with new `/browser` and `/server` subpath exports.
+  - `@youversion/platform-core` — runtime-agnostic core; accepts `parseHtml`/`serializeHtml` adapters so it works with any DOM implementation
+  - `@youversion/platform-core/browser` — zero-config convenience wrapper using the native `DOMParser`
+  - `@youversion/platform-core/server` — zero-config convenience wrapper using `linkedom` (optional peer dependency)
+
+  The transformer sanitizes API HTML (custom allowlist-based sanitizer, no DOMPurify dependency), wraps verse content for CSS targeting, and embeds footnote data as `data-verse-footnote` / `data-verse-footnote-content` attributes directly in the HTML.
+
+  **`@youversion/platform-react-ui`**: Migrate Bible HTML transformation from the UI package to `@youversion/platform-core/browser`.
+  - Removed `isomorphic-dompurify` dependency (lighter bundle)
+  - Footnote popover data is now read from DOM attributes at render time instead of a separate data structure
+  - Added SSR safety guard — `Verse.Html` returns raw HTML during server rendering and transforms on the client after hydration
+
 ## 1.20.2
 
 ### Patch Changes

package/dist/browser-DzQ1yOHv.d.cts

@@ -0,0 +1,69 @@
+/**
+ * Options for transforming Bible HTML. Requires DOM adapter functions
+ * to parse and serialize HTML, making the transformer runtime-agnostic.
+ */
+type TransformBibleHtmlOptions = {
+    /** Parses an HTML string into a DOM Document */
+    parseHtml: (html: string) => Document;
+    /** Serializes a Document back to an HTML string */
+    serializeHtml: (doc: Document) => string;
+};
+/**
+ * The result of transforming Bible HTML.
+ *
+ * The returned HTML is self-contained — footnote data is embedded as attributes:
+ * - `data-verse-footnote="KEY"` marks the footnote position
+ * - `data-verse-footnote-content="HTML"` contains the footnote's inner HTML
+ *
+ * Consumers can access verse context by walking up from a footnote anchor
+ * to `.closest('.yv-v[v]')`.
+ */
+type TransformedBibleHtml = {
+    /** The transformed HTML with footnotes replaced by marker elements */
+    html: string;
+};
+/**
+ * Transforms Bible HTML by cleaning up verse structure, extracting footnotes,
+ * and replacing them with self-contained anchor elements.
+ *
+ * Footnote data is embedded directly in the HTML via attributes:
+ * - `data-verse-footnote="KEY"` — the footnote key (verse number or `intro-N`)
+ * - `data-verse-footnote-content="HTML"` — the footnote's inner HTML content
+ *
+ * Verse context is available by walking up from a footnote anchor:
+ * `anchor.closest('.yv-v[v]')` returns the verse wrapper (null for intro footnotes).
+ *
+ * @param html - The raw Bible HTML from the YouVersion API
+ * @param options - DOM adapter options for parsing and serializing HTML
+ * @returns The transformed HTML
+ *
+ * @example
+ * ```ts
+ * import { transformBibleHtml } from '@youversion/platform-core';
+ *
+ * const result = transformBibleHtml(rawHtml, {
+ *   parseHtml: (html) => new DOMParser().parseFromString(html, 'text/html'),
+ *   serializeHtml: (doc) => doc.body.innerHTML,
+ * });
+ *
+ * console.log(result.html); // Clean HTML with self-contained footnote anchors
+ * ```
+ */
+declare function transformBibleHtml(html: string, options: TransformBibleHtmlOptions): TransformedBibleHtml;
+/**
+ * Transforms Bible HTML for browser environments using the native DOMParser API.
+ *
+ * @param html - The raw Bible HTML from the YouVersion API
+ * @returns The transformed HTML
+ *
+ * @example
+ * ```ts
+ * import { transformBibleHtmlForBrowser } from '@youversion/platform-core/browser';
+ *
+ * const result = transformBibleHtmlForBrowser(rawHtml);
+ * console.log(result.html); // Clean HTML with self-contained footnote anchors
+ * ```
+ */
+declare function transformBibleHtmlForBrowser(html: string): TransformedBibleHtml;
+
+export { type TransformedBibleHtml as T, type TransformBibleHtmlOptions as a, transformBibleHtmlForBrowser as b, transformBibleHtml as t };

package/dist/browser-DzQ1yOHv.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Options for transforming Bible HTML. Requires DOM adapter functions
+ * to parse and serialize HTML, making the transformer runtime-agnostic.
+ */
+type TransformBibleHtmlOptions = {
+    /** Parses an HTML string into a DOM Document */
+    parseHtml: (html: string) => Document;
+    /** Serializes a Document back to an HTML string */
+    serializeHtml: (doc: Document) => string;
+};
+/**
+ * The result of transforming Bible HTML.
+ *
+ * The returned HTML is self-contained — footnote data is embedded as attributes:
+ * - `data-verse-footnote="KEY"` marks the footnote position
+ * - `data-verse-footnote-content="HTML"` contains the footnote's inner HTML
+ *
+ * Consumers can access verse context by walking up from a footnote anchor
+ * to `.closest('.yv-v[v]')`.
+ */
+type TransformedBibleHtml = {
+    /** The transformed HTML with footnotes replaced by marker elements */
+    html: string;
+};
+/**
+ * Transforms Bible HTML by cleaning up verse structure, extracting footnotes,
+ * and replacing them with self-contained anchor elements.
+ *
+ * Footnote data is embedded directly in the HTML via attributes:
+ * - `data-verse-footnote="KEY"` — the footnote key (verse number or `intro-N`)
+ * - `data-verse-footnote-content="HTML"` — the footnote's inner HTML content
+ *
+ * Verse context is available by walking up from a footnote anchor:
+ * `anchor.closest('.yv-v[v]')` returns the verse wrapper (null for intro footnotes).
+ *
+ * @param html - The raw Bible HTML from the YouVersion API
+ * @param options - DOM adapter options for parsing and serializing HTML
+ * @returns The transformed HTML
+ *
+ * @example
+ * ```ts
+ * import { transformBibleHtml } from '@youversion/platform-core';
+ *
+ * const result = transformBibleHtml(rawHtml, {
+ *   parseHtml: (html) => new DOMParser().parseFromString(html, 'text/html'),
+ *   serializeHtml: (doc) => doc.body.innerHTML,
+ * });
+ *
+ * console.log(result.html); // Clean HTML with self-contained footnote anchors
+ * ```
+ */
+declare function transformBibleHtml(html: string, options: TransformBibleHtmlOptions): TransformedBibleHtml;
+/**
+ * Transforms Bible HTML for browser environments using the native DOMParser API.
+ *
+ * @param html - The raw Bible HTML from the YouVersion API
+ * @returns The transformed HTML
+ *
+ * @example
+ * ```ts
+ * import { transformBibleHtmlForBrowser } from '@youversion/platform-core/browser';
+ *
+ * const result = transformBibleHtmlForBrowser(rawHtml);
+ * console.log(result.html); // Clean HTML with self-contained footnote anchors
+ * ```
+ */
+declare function transformBibleHtmlForBrowser(html: string): TransformedBibleHtml;
+
+export { type TransformedBibleHtml as T, type TransformBibleHtmlOptions as a, transformBibleHtmlForBrowser as b, transformBibleHtml as t };

package/dist/browser.cjs

@@ -0,0 +1,270 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/browser.ts
+var browser_exports = {};
+__export(browser_exports, {
+  transformBibleHtml: () => transformBibleHtmlForBrowser
+});
+module.exports = __toCommonJS(browser_exports);
+
+// src/bible-html-transformer.ts
+var NON_BREAKING_SPACE = "\xA0";
+var FOOTNOTE_KEY_ATTR = "data-footnote-key";
+var NEEDS_SPACE_BEFORE = /^[^\s.,;:!?)}\]'"'»›]/;
+var ALLOWED_TAGS = /* @__PURE__ */ new Set([
+  "DIV",
+  "P",
+  "SPAN",
+  "SUP",
+  "SUB",
+  "EM",
+  "STRONG",
+  "I",
+  "B",
+  "SMALL",
+  "BR",
+  "SECTION",
+  "TABLE",
+  "THEAD",
+  "TBODY",
+  "TR",
+  "TD",
+  "TH"
+]);
+var DROP_ENTIRELY_TAGS = /* @__PURE__ */ new Set([
+  "SCRIPT",
+  "STYLE",
+  "IFRAME",
+  "OBJECT",
+  "EMBED",
+  "SVG",
+  "MATH",
+  "FORM",
+  "INPUT",
+  "BUTTON",
+  "TEXTAREA",
+  "SELECT",
+  "TEMPLATE",
+  "LINK",
+  "META",
+  "BASE",
+  "NOSCRIPT"
+]);
+var ALLOWED_ATTRS = /* @__PURE__ */ new Set(["class", "v", "colspan", "rowspan", "dir", "usfm"]);
+function sanitizeBibleHtmlDocument(doc) {
+  const root = doc.body ?? doc.documentElement;
+  for (const el of Array.from(root.querySelectorAll("*"))) {
+    const tag = el.tagName;
+    if (DROP_ENTIRELY_TAGS.has(tag)) {
+      el.remove();
+      continue;
+    }
+    if (!ALLOWED_TAGS.has(tag)) {
+      el.replaceWith(...Array.from(el.childNodes));
+      continue;
+    }
+    for (const attr of Array.from(el.attributes)) {
+      const name = attr.name.toLowerCase();
+      if (name.startsWith("on")) {
+        el.removeAttribute(attr.name);
+        continue;
+      }
+      if (!ALLOWED_ATTRS.has(name) && !name.startsWith("data-")) {
+        el.removeAttribute(attr.name);
+      }
+    }
+  }
+}
+function wrapVerseContent(doc) {
+  function wrapParagraphContent(doc2, paragraph, verseNum) {
+    const children = Array.from(paragraph.childNodes);
+    if (children.length === 0) return;
+    const wrapper = doc2.createElement("span");
+    wrapper.className = "yv-v";
+    wrapper.setAttribute("v", verseNum);
+    const firstChild = children[0];
+    if (firstChild) {
+      paragraph.insertBefore(wrapper, firstChild);
+    }
+    children.forEach((child) => {
+      wrapper.appendChild(child);
+    });
+  }
+  function wrapParagraphsUntilBoundary(doc2, verseNum, startParagraph, endParagraph) {
+    if (!startParagraph) return;
+    let currentParagraph = startParagraph.nextElementSibling;
+    while (currentParagraph && currentParagraph !== endParagraph) {
+      const isHeading = currentParagraph.classList.contains("yv-h") || currentParagraph.matches(
+        ".s1, .s2, .s3, .s4, .ms, .ms1, .ms2, .ms3, .ms4, .mr, .sp, .sr, .qa, .r"
+      );
+      if (isHeading) {
+        currentParagraph = currentParagraph.nextElementSibling;
+        continue;
+      }
+      if (currentParagraph.querySelector(".yv-v[v]")) break;
+      if (currentParagraph.classList.contains("p") || currentParagraph.tagName === "P") {
+        wrapParagraphContent(doc2, currentParagraph, verseNum);
+      }
+      currentParagraph = currentParagraph.nextElementSibling;
+    }
+  }
+  function handleParagraphWrapping(doc2, currentParagraph, nextParagraph, verseNum) {
+    if (!currentParagraph) return;
+    if (!nextParagraph) {
+      wrapParagraphsUntilBoundary(doc2, verseNum, currentParagraph);
+      return;
+    }
+    if (currentParagraph !== nextParagraph) {
+      wrapParagraphsUntilBoundary(doc2, verseNum, currentParagraph, nextParagraph);
+    }
+  }
+  function processVerseMarker(marker, index, markers) {
+    const verseNum = marker.getAttribute("v");
+    if (!verseNum) return;
+    const nextMarker = markers[index + 1];
+    const nodesToWrap = collectNodesBetweenMarkers(marker, nextMarker);
+    if (nodesToWrap.length === 0) return;
+    const currentParagraph = marker.closest(".p, p, div.p");
+    const nextParagraph = nextMarker?.closest(".p, p, div.p") || null;
+    const doc2 = marker.ownerDocument;
+    wrapNodesInVerse(marker, verseNum, nodesToWrap);
+    handleParagraphWrapping(doc2, currentParagraph, nextParagraph, verseNum);
+  }
+  function wrapNodesInVerse(marker, verseNum, nodes) {
+    const wrapper = marker.ownerDocument.createElement("span");
+    wrapper.className = "yv-v";
+    wrapper.setAttribute("v", verseNum);
+    const firstNode = nodes[0];
+    if (firstNode) {
+      marker.parentNode?.insertBefore(wrapper, firstNode);
+    }
+    nodes.forEach((node) => {
+      wrapper.appendChild(node);
+    });
+    marker.remove();
+  }
+  function shouldStopCollecting(node, endMarker) {
+    if (node === endMarker) return true;
+    if (endMarker && node.nodeType === 1 && node.contains(endMarker)) return true;
+    return false;
+  }
+  function shouldSkipNode(node) {
+    return node.nodeType === 1 && node.classList.contains("yv-h");
+  }
+  function collectNodesBetweenMarkers(startMarker, endMarker) {
+    const nodes = [];
+    let current = startMarker.nextSibling;
+    while (current && !shouldStopCollecting(current, endMarker)) {
+      if (shouldSkipNode(current)) {
+        current = current.nextSibling;
+        continue;
+      }
+      nodes.push(current);
+      current = current.nextSibling;
+    }
+    return nodes;
+  }
+  const verseMarkers = Array.from(doc.querySelectorAll(".yv-v[v]"));
+  verseMarkers.forEach(processVerseMarker);
+}
+function assignFootnoteKeys(doc) {
+  let introIdx = 0;
+  doc.querySelectorAll(".yv-n.f").forEach((fn) => {
+    const verseNum = fn.closest(".yv-v[v]")?.getAttribute("v");
+    fn.setAttribute(FOOTNOTE_KEY_ATTR, verseNum ?? `intro-${introIdx++}`);
+  });
+}
+function replaceFootnotesWithAnchors(doc, footnotes) {
+  for (const fn of footnotes) {
+    const key = fn.getAttribute(FOOTNOTE_KEY_ATTR);
+    if (!key) continue;
+    const prev = fn.previousSibling;
+    const next = fn.nextSibling;
+    const prevText = prev?.textContent ?? "";
+    const nextText = next?.textContent ?? "";
+    const prevNeedsSpace = prevText.length > 0 && !/\s$/.test(prevText);
+    const nextNeedsSpace = nextText.length > 0 && NEEDS_SPACE_BEFORE.test(nextText);
+    if (prevNeedsSpace && nextNeedsSpace && fn.parentNode) {
+      fn.parentNode.insertBefore(doc.createTextNode(" "), fn);
+    }
+    const anchor = doc.createElement("span");
+    anchor.setAttribute("data-verse-footnote", key);
+    anchor.setAttribute("data-verse-footnote-content", fn.innerHTML);
+    fn.replaceWith(anchor);
+  }
+}
+function addNbspToVerseLabels(doc) {
+  doc.querySelectorAll(".yv-vlbl").forEach((label) => {
+    const text = label.textContent || "";
+    if (!text.endsWith(NON_BREAKING_SPACE)) {
+      label.textContent = text + NON_BREAKING_SPACE;
+    }
+  });
+}
+function fixIrregularTables(doc) {
+  doc.querySelectorAll("table").forEach((table) => {
+    const rows = table.querySelectorAll("tr");
+    if (rows.length === 0) return;
+    let maxColumns = 0;
+    rows.forEach((row) => {
+      let count = 0;
+      row.querySelectorAll("td, th").forEach((cell) => {
+        count += parseInt(cell.getAttribute("colspan") || "1", 10);
+      });
+      maxColumns = Math.max(maxColumns, count);
+    });
+    if (maxColumns > 1) {
+      rows.forEach((row) => {
+        const cells = row.querySelectorAll("td, th");
+        if (cells.length === 1) {
+          const existing = parseInt(cells[0].getAttribute("colspan") || "1", 10);
+          if (existing < maxColumns) {
+            cells[0].setAttribute("colspan", maxColumns.toString());
+          }
+        }
+      });
+    }
+  });
+}
+function transformBibleHtml(html, options) {
+  const doc = options.parseHtml(html);
+  sanitizeBibleHtmlDocument(doc);
+  wrapVerseContent(doc);
+  assignFootnoteKeys(doc);
+  const footnotes = Array.from(doc.querySelectorAll(".yv-n.f"));
+  replaceFootnotesWithAnchors(doc, footnotes);
+  addNbspToVerseLabels(doc);
+  fixIrregularTables(doc);
+  const transformedHtml = options.serializeHtml(doc);
+  return { html: transformedHtml };
+}
+function transformBibleHtmlForBrowser(html) {
+  if (typeof globalThis.DOMParser === "undefined") {
+    throw new Error("DOMParser is required to transform Bible HTML in browser environments");
+  }
+  return transformBibleHtml(html, {
+    parseHtml: (h) => new DOMParser().parseFromString(h, "text/html"),
+    serializeHtml: (doc) => doc.body.innerHTML
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  transformBibleHtml
+});

package/dist/browser.d.cts

@@ -0,0 +1 @@
+export { T as TransformedBibleHtml, b as transformBibleHtml } from './browser-DzQ1yOHv.cjs';

package/dist/browser.d.ts

@@ -0,0 +1 @@
+export { T as TransformedBibleHtml, b as transformBibleHtml } from './browser-DzQ1yOHv.js';

package/dist/browser.js

@@ -0,0 +1,6 @@
+import {
+  transformBibleHtmlForBrowser
+} from "./chunk-2Z2S2WY3.js";
+export {
+  transformBibleHtmlForBrowser as transformBibleHtml
+};