feat(core): auto-transform Bible HTML in getPassage

[cameronapak]

Summary

Auto-transforms Bible HTML inside getPassage so consumers never need to call transformBibleHtml manually. Uses native DOMParser in the browser and dynamic import('jsdom') on the server. Added data-yv-transformed idempotency marker so double-transforms are a no-op.

Runtime DOM choice: optional peer is jsdom (not linkedom). No workerd-specific path or CI smoke — server consumers that need auto-transform install jsdom, or pass transform: false to skip.

Verse.Html retains its transformBibleHtml call as defense-in-depth — the idempotency marker makes it a no-op for HTML that already went through getPassage.

Node floor: jsdom@28.1.0 (devDep / peer ^24 || ^28) declares ^20.19.0 || ^22.12.0 || >=24.0.0, which covers the repo engines.node >=22.13 floor (Decision 3).

Context: Why transformBibleHtml Exists — And Where It May Not Be Needed

Test plan

• Verify getPassage with format: 'html' returns transformed content (data-yv-transformed present)
• Verify getPassage with format: 'text' returns raw content (no transformation)
• Verify double-transform produces identical output (idempotency)
• Verify footnotes are extracted into data-verse-footnote attributes
• Verify Verse.Html still sanitizes raw HTML passed directly (XSS protection)

Greptile Summary

The PR makes getPassage automatically sanitize and structurally transform HTML while retaining explicit opt-out and runtime-specific DOM behavior.

• Adds browser-native and optional server-side jsdom adapters.
• Makes transformation idempotent across nested markers and multi-root fragments.
• Forwards the transformation option through usePassage.
• Updates UI integration, styling, tests, package metadata, and build configuration.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains, and the previously reported marker, dependency-error, type-version, sibling-root, and hook-forwarding issues are fixed or invalid at the current head.

Important Files Changed

Filename	Overview
packages/core/src/bible-html-transformer.ts	Adds sanitized, multi-root-aware idempotency handling and marks every transformed top-level element.
packages/core/src/bible.ts	Automatically transforms HTML passages using browser DOMParser or optional server-side jsdom, with an explicit opt-out.
packages/hooks/src/usePassage.ts	Exposes, forwards, and correctly keys fetching on the passage transformation option.
packages/core/src/bible-html-transformer-server.ts	Replaces the server transformer’s linkedom adapter with jsdom.
packages/core/package.json	Aligns jsdom runtime and type versions, declares it as an optional peer, and prevents browser resolution.
packages/ui/src/components/verse.tsx	Retains client-side transformation as an idempotent rendering safety layer.

Sequence Diagram

sequenceDiagram
  participant Consumer
  participant Hook as usePassage
  participant Core as BibleClient.getPassage
  participant API as YouVersion API
  participant DOM as DOMParser or jsdom
  Consumer->>Hook: Request passage with transform option
  Hook->>Core: Forward request and transform option
  Core->>API: Fetch passage
  API-->>Core: Passage content
  alt HTML and transform enabled
    Core->>DOM: Parse content
    DOM-->>Core: Document
    Core->>Core: Sanitize and structurally transform
  end
  Core-->>Hook: Passage
  Hook-->>Consumer: Passage state

Loading

_{Reviews (18): Last reviewed commit: "Merge branch 'main' into transform-bible..." | Re-trigger Greptile}

Context used (3)

• Knowledge Base — Core Package (@youversion/platform-core)
• Knowledge Base — packages/hooks — React hooks for the YouVersion Platform
• Knowledge Base — packages/ui

[changeset-bot]

🦋 Changeset detected

Latest commit: 1948fac

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@youversion/platform-core	Minor
@youversion/platform-react-hooks	Minor
@youversion/platform-react-ui	Minor
vite-react	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[davidfedor]

Big picture: I love the idea of being helpful, without requiring the developer to have to make another call. My comments and questions are around whether this is the best way to do that. (Maybe it is! I'm not sure yet.)
I notice this would be blurring the lines between Core being merely an API helper-layer, but now it would be doing some of the prep-work of the UI (visualization layer). So at the least having that be optional seems wise.
I'm wondering if that parameter should default to do the transformation, or not... or whether we need to force the dev to make a choice (to attempt to force them to make an informed choice).

[davidfedor]

(FYI I've asked for thoughts from Bryson H; not sure if he's got cycles to contribute or not)

[arinthros]

@davidfedor @cameronapak this looks good to me, I just don't see an "approve" button in my UI. Approved by me!

[cameronapak]

Some added context on this ticket is: Why transformBibleHtml Exists — And Where It May Not Be Needed

If we can get this merged in, then I can write better docs for helping people use our HTML and styles without them having to manually transformBibleHtml on their end

[cameronapak]

Adding some clarity. David sent me a DM on Teams the other day saying this:

Cam, at your leisure, can you rebase Auto-transform the Bible HTML from getPassage so the consumer doesn't have extra steps by cameronapa… (or merge, whichever) and have greptile re-review it? I finally had time to look at it again and consider things and I think it's a step in the right direction.
(From a strategic point of view I'd like to make it easier for agents to create pages using YVP, and supporting non-React web paths is a component of that.)

[jhampton]

@davidfedor - the Idempotency guarantee you mentioned was already implemented and Greptile shows 5/5 - is there another place I'm not seeing?