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.