Skip to content

Hackathon 25.3: Page.addStyleSheet has two problems when sheets are swapped at runtime #25566

Closed

Description

@manolo

Description

An application that chooses its theme at runtime adds and removes stylesheets through Page. Two things go wrong.

The order is not stable. Two sheets added with page.addStyleSheet, then one of them replaced: the surviving sheet sometimes ends up after the new one and sometimes before. Nothing in the API orders them.

Removing a sheet and adding the same URL back in one round trip loses it. registration.remove() followed by page.addStyleSheet(sameUrl) in the same server visit leaves the page with no sheet at all. The two operations reach the browser together and the add is treated as a duplicate of a sheet that is still there. Nothing is logged.

Why it matters

The first one produces colours that are right in one theme and wrong in the other, depending on which sheet happened to land last, which is a bug nobody can reproduce on demand.

The second one is worse: switching between two themes that share a sheet leaves the application unstyled, and the only clue is that it comes back after a reload.

Expected

For the order: a documented order, or a way to say where a sheet goes.

For the re-add: treat a removal and an addition of the same URL in one round trip as a replacement, or log that the addition was dropped.

Workaround

Win on specificity instead of order: html:root beats the plain html both themes use. And never touch what does not change: keep the shared sheet loaded and swap only the other one.

Reproduce

The re-add half is in 38-dark-mode.zip, route /swap. mvn spring-boot:run, then http://localhost:8138/swap and press the buttons in order, listing link[rel=stylesheet] after each one:

After Sheets on the page
load lumo.css aura.css
remove() and addStyleSheet(same URL) in one round trip aura.css
remove() alone aura.css
addStyleSheet(same URL) in its own round trip lumo.css aura.css

Row two is the bug: the sheet is gone and the add that was meant to bring it back did nothing. Row four is the same call, one round trip later, working. Nothing is logged in either case.

sheet.remove();
sheet = page.addStyleSheet(Lumo.STYLESHEET);   // dropped as a duplicate

The order half is not reduced. It is real in an application that swaps two sheets, and it depends on which sheet happens to land last, so there is nothing here that reproduces it on demand. Treat it as the observation that the API says nothing about order.

Getting the project

38-dark-mode.zip, 4 KB, sources only. Unzip it and:

mvn spring-boot:run

Found on 25.3.0-beta1.

Activity

  1. totally-not-ai commented on Sep 9, 2026

    @totally-not-ai
    Contributor

    Looked into this. The re-add half is a real bug with a definite root cause on the client, and there is a fix for it in #25594. The order half is partly a symptom of the same bug and partly a genuine API gap — I left that one for a decision rather than guessing.

    1. remove() + addStyleSheet(sameUrl) in one round trip loses the sheet — real bug

    The server does its part correctly. Registration.remove() goes to UIInternals.removeStyleSheet(id), which queues the id in pendingStyleSheetRemovals and drops the URL from the DependencyList (urlCache, urlToLoadedDependency, sentToClient). The page.addStyleSheet(url) that follows therefore finds no existing dependency for that URL, mints a fresh id, and ends up in getPendingSendToClient(). So the UIDL that goes out carries both halves:

    { "EAGER": [ { "type": "STYLESHEET", "url": ".../lumo.css", "id": "<new-id>" } ],
      "stylesheetRemovals": [ "<old-id>" ] }

    The client is where the add is lost. MessageHandler loads the message's dependencies first, and processes stylesheetRemovals later, inside processMessage, which is itself deferred until the eager dependencies have loaded:

    • flow-client/src/main/frontend/internal/client/communication/MessageHandler.ts — #handleDependencies(valueMap), then runWhenEagerDependenciesLoaded(() => #processMessage(...)), and #processStylesheetRemovals sits inside #processMessage.
    • flow-client/src/main/java/com/vaadin/client/communication/MessageHandler.java — same order.

    So the add reaches ResourceLoader.loadStylesheet, which dedupes by URL: isLoaded(url) is still true, because the <link> that is about to be removed is still on the page and still in the loader's loaded-resources set. The loader notifies the listener and creates no element. Only then does the removal run and delete that <link>, and clearLoadedResourceById drops the URL from the loaded set. Net result: no sheet on the page, nothing logged. One round trip later the very same call works (row four of the table) precisely because that last step has meanwhile freed the URL.

    Worth noting the same mechanism can bite the CSS hotswapper: StyleSheetHotswapper applies its removals and its adds in one pass, so a URL that is both removed and re-added in one pass disappears the same way.

    Fix

    Apply a message's stylesheetRemovals before loading the dependencies that same message carries, in both clients. Then the add is a real add — a fresh <link data-id="<new-id>"> — which is exactly the "treat a removal and an addition of the same URL in one round trip as a replacement" behaviour asked for, and the Registration returned by the second addStyleSheet refers to the element that is actually on the page. No API change, no new UIDL key, and removal-only and add-only round trips are unaffected (a removal-only message has no eager dependency to wait for, so the timing is the same as today).

    #25594 has that change plus a unit test that wires the real ResourceLoader/DependencyLoader and fails without it (it reproduces the "page ends up with neither" outcome), a matching GWT case, and an IT on the existing StyleRemovalView/StyleRemovalIT.

    2. The order

    Two separate things here.

    The instability described looks like this same bug. Adds are deterministic today: DependencyList keeps a LinkedHashMap, UidlWriter preserves that order per load mode, and the client inserts each <link> before the <!--Stylesheet end--> comment in <head>, in arrival order. So a sheet added later lands after one added earlier, and a re-added URL moves to the end. The "sometimes before, sometimes after" is what you get when the re-add sometimes takes effect (new sheet appended last) and sometimes is silently dropped (survivor keeps its original position) — i.e. bug 1. With bug 1 fixed, a swap is deterministic: the re-added sheet is always last.

    What is genuinely missing is the promise and the control, and that needs a product/API decision rather than a patch from me:

    1. Document the existing behaviour on Page.addStyleSheet — sheets are inserted in the order they are added, and re-adding a URL moves it to the end. Cheapest option; costs nothing but commits Flow to the current order.
    2. Add a way to say where a sheet goes, e.g. an overload taking a position/anchor. Real API, wants a proper design (and probably the same for addJavaScript).
    3. Leave it, on the grounds that specificity is the right tool for theme layering, as the workaround in the issue notes.

    My recommendation is 1 now and 2 only if there is demand, but that is a call for someone else.

    One small related wart I did not touch: UIInternals.getPendingStyleSheetRemovals() copies a LinkedHashSet into a HashSet, so removal ids reach the client in arbitrary order. It cannot reorder the surviving sheets (removing an element does not move its siblings), so it is not the cause of anything here, but the ordering is lost for no reason.

    /cc @manolo

  2. vaadin-bot commented on Sep 14, 2026

    @vaadin-bot
    Collaborator

    This ticket/PR has been released with Vaadin 25.3.0-beta3.

  3. vaadin-bot commented on Sep 29, 2026

    @vaadin-bot
    Collaborator

    This ticket/PR has been released with Vaadin 25.4.0-alpha1.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions