openElement islands are Custom Element upgrades that follow DSD HTML. This is not full-page hydration - it does not restore the entire application state on the client.
When the browser parses HTML, DSD has already placed component content and styles into the shadow root. After the client entry loads, it calls customElements.define() and the browser upgrades existing elements into real Custom Elements. This process is more accurately called Island Upgrade.
| Need | Preferred Layer |
|---|---|
| Readable content, navigation, layout | HTML + DSD |
| Hover, focus, responsive state, simple disclosure | CSS and native HTML elements |
| Clipboard, localStorage, IntersectionObserver | Small island using browser APIs |
| Local state, event orchestration, API polling, optimistic UI | Island Upgrade |
Place local islands in app/islands. The builder scans them, generates a client entry, and injects it into the static HTML.
Reusable packages can export island metadata. openElement reads this at build time for SSR registration and client entry generation.
Today that metadata is intentionally minimal. Future package islands should be driven by a CEM-compatible manifest that declares tag, module, export, strategy, SSR renderability, DSD constraints, hydration events, diagnostics, and fallback behavior. That protocol is required before open add, automatic registration, or registry hub claims are stable.
The current implementation should be treated as framework-supported package island scanning, not a general-purpose component marketplace. If a package cannot explain its SSR and hydration behavior, openElement should render it as static host markup or a pure island instead of guessing.