fix: enable hydration for Lit elements used as raw HTML tags

[piotrekwitkowski]

Fixes #6

Problem

Hydration support is injected via before-hydration, which only fires for pages with client:* directives. Pages using Lit elements as raw HTML tags (<my-element>) get SSR'd with DSD but never hydrated, causing duplicate shadow DOM content.

On top of that, globalThis.litElementHydrateSupport is a one-shot callback — LitElement checks for it once during class initialization. injectScript('page') creates a separate module entry point, and Vite may evaluate lit before the callback is set, so it's too late.

Approach

Three pieces working together:

1. hydration-support-global.js — injected as head-inline

Synchronous <script> that sets globalThis.litElementHydrateSupport before any module loads. Patches createRenderRoot (reuse DSD shadow roots, set _$AG flag), connectedCallback (respect defer-hydration), and attributeChangedCallback (resume on attribute removal).

2. hydration-support.js — loaded via Vite plugin

Patches LitElement.prototype.update() to choose between hydrate() and replaceChildren() + render(). The decision:

• Shadow root contains children with defer-hydration → replace
• Any non-reflected property has a non-default value → replace
• Otherwise → hydrate

Also removes defer-hydration from document-level elements via queueMicrotask, and stores __childPart + resets renderOptions.renderBefore to prevent duplicate content on re-renders.

3. Vite transform plugin

Prepends the hydration-support.js import into Astro <script> modules (matched by type=script in the virtual module ID). This ensures the hydration patches and the user's component import end up in the same Vite chunk, sharing one LitElement prototype. Skips server-side transforms via options.ssr.

At build time, we check whether @lit-labs/ssr-client already handles deferred hydration natively. If it does, all of the above is skipped and we fall back to the original before-hydration import.

Testing

• All 10 existing tests pass
• 28 Playwright tests (POC): static, dynamic, nested (3+ levels), re-render after property change, @State() interaction, hydration flag verification
• 28 real component pages on a docs site: 27 pass, 1 pre-existing MDX bug (unrelated)
• Dev mode: no duplicates, interaction works
• Production build: single JS chunk, 1 LitElement instance

[piotrekwitkowski]

Update from testing in production (cumulus-ui docs site, 83 pages, 80+ Lit components):

Static components (button, container, header, link, badge, etc.) hydrate perfectly — SSR output matches client render, hydrate() adopts the DSD content, zero flicker.

Dynamic components (side-navigation, breadcrumb-group, table — those with attribute:false properties set via inline scripts) still produce duplicate shadow DOM content after hydration. The replaceSSRContent path clears and re-renders the parent, but nested child components that were already upgraded produce duplicate .root divs.

The Vite plugin approach (auto-prepending hydration-support.js into Astro script chunks) works correctly. The SSR guard (skipping transform during SSR build) works. The _$AG flag fix works. The remaining issue is specifically in how replaceSSRContent interacts with already-upgraded nested Lit elements.

[jlukic]

Thanks I'll take a look sometime next week.

[piotrekwitkowski]

Hi @jlukic would you have a moment?

[jlukic]

Sorry again but haven't had time yet to review, will do next week.

Wanted to point to this as it might be related depending on what version of Astro you are using. withastro/astro#15904 (comment)

Can you confirm your exact versions