Skip to content
Leonidov.DEV

Islands of Interactivity: 5 Choices Behind HydraLine

Architecture
Islands of Interactivity: 5 Choices Behind HydraLine

Flutter Web gives a team one rendering model for every screen, and that is why it is good for an application. The same model makes a public page a canvas, and a canvas has nothing for a crawler to read. HydraLine adds islands of interactivity on top of real HTML, and five choices decided how.

Code: HydraLine, MIT licensed.

Dart 3.9, Flutter 3.35, three packages: hydraline, hydraline_server, hydraline_flutter. 486 unit and widget tests, 26 end-to-end tests in a real Chrome.

Choice 1: add to the app instead of replacing it

The library does not own main(), does not replace MaterialApp and does not impose a router. A route moves to document mode, or to hybrid mode with Flutter islands inside HTML, and the rest of the app keeps running.

A migration you can do one route at a time is a migration that survives a deadline. A rewrite of the frontend is a project, and a project of that size gets cancelled in month two.

Choice 2: the builder cannot see the User-Agent

The cheap way to make a Flutter site crawlable is to detect a bot and return prerendered HTML. It works, and it is cloaking: two different documents at one address, and a search engine that finds out treats it as a penalty on the whole domain.

Here the User-Agent never reaches the page builders. Bot and human receive byte-identical bodies, and a CI test compares the two responses. That is a structural promise rather than a policy someone has to remember.

Choice 3: three levels, chosen per route

L0 is static HTML with no JavaScript: details and summary, :target links, lazy images. L1 adds vanilla JavaScript and HTMX islands of about 8–14 KB for tabs, forms and search. L2 loads the Flutter engine for an island that needs it, on a trigger rather than at page load.

The levels exist because “interactive” is not one requirement. A blog post is L0, a filter form is L1, a configurator with a 3D preview is L2. Treating all three the same is what produces a two-megabyte bundle for a page of text.

Choice 4: one document tree, SSR and SSG

The same DocumentNode tree streams from a Dart server or compiles into a static dist/. A marketing site can be static and an app can be served, from one description of the page.

Two render paths from one model is the only version of this I trust. Two hand-written implementations of the same page differ within a month, and the difference shows up as a canonical tag that disagrees with the sitemap.

Choice 5: reserve the box before the island arrives

An island declares its size, and the placeholder holds exactly that space through Declarative Shadow DOM. Layout shift stays near zero, and an end-to-end test in real Chrome measures it instead of assuming it.

This is the least visible choice and the one users feel most. A page that jumps while the reader is halfway through a sentence loses the sentence, and the measurement is the only thing that keeps a promise like that honest.

What the package refuses to do

It does not measure your SEO score, does not promise rankings and does not touch page speed beyond what it renders. It also does not scan the web root for pages: the sitemap is built from the routes you register, and a page that is not registered is missing from the map.

SafeUrl rejects javascript: and data: at construction, escaping is context aware, sanitizeHtml() strips inline handlers, and runtime scripts carry integrity and crossorigin. A million-input fuzz suite backs that up, because a sanitizer with a good reputation is not a sanitizer with a test.

What it teaches

The browser has a working rendering model and a working accessibility model. A framework that replaces both has to rebuild them, and the rebuild is where a page becomes invisible to everything that is not a browser.

That is the argument in progressive enhancement, applied to a rendering engine instead of a form. The same reasoning appears in file upload form, where the native input stays the source of truth and the widget dresses it.

HydraLine is MIT and lives on pub.dev, with the three packages documented separately.