fix!: auto-apply context:// for @Stylesheet values (#24235)

@Stylesheet currently produces broken <link> elements when the Vaadin
servlet is mapped at a non-root path (vaadin.urlMapping=/ui/* etc.): the
browser resolves the bare relative href against <base> (which
points to the servlet mapping path), so a file at
META-INF/resources/styles.css is fetched as /ui/styles.css and 404s.
Users had to know to write @Stylesheet("context://styles.css")
explicitly to step out of the servlet path.

Frame the right behavior into the framework instead:

- New FrontendDependencyUrlResolver.resolveToContextRoot extracts the
prefix-handling rules into one place: http(s)://, //, context://,
base:// pass through unchanged; "/" is treated as an absolute server
path; "./" leads strip to a context-root-relative value; everything else
gets a context:// prefix prepended. Path traversals are rejected.
- UIInternals.addComponentDependencies normalizes @Stylesheet values
through the resolver before storing them on the dependency list, so
component-level @Stylesheet now renders correctly under any servlet
mapping. The same normalization keys ActiveStyleSheetTracker so spelling
variants of the same file (foo.css, ./foo.css,
  context://foo.css) deduplicate to a single <link>.
- AppShellRegistry.resolveStyleSheetHref delegates to the same resolver,
replacing the inline rule set. The trailing BootstrapUriResolver call
continues to expand context:// using the servlet-relative path produced
by getContextRootRelativePath, so AppShell-level resolution stays
consistent with the UIDL path.

Test fixtures updated for the canonical context://-prefixed URLs in the
dependency list. UidlWriterTest also registers inline test resources at
the leading-slash path (/inline.css) to match the servlet container
lookup that resolveResource produces for a context:// value.

Fixes #22888

Author: Artur-

flow-server/src/main/java/com/vaadin/flow/component/internal/UIInternals.java

@@ -86,6 +86,7 @@
 import com.vaadin.flow.router.internal.BeforeEnterHandler;
 import com.vaadin.flow.router.internal.BeforeLeaveHandler;
 import com.vaadin.flow.server.Command;
+import com.vaadin.flow.server.FrontendDependencyUrlResolver;
 import com.vaadin.flow.server.VaadinService;
 import com.vaadin.flow.server.VaadinSession;
 import com.vaadin.flow.server.communication.PushConnection;
@@ -1092,14 +1093,24 @@ public void addComponentDependencies(
             triggerChunkLoading(componentClass);
         }
 
-        dependencies.getStyleSheets().forEach(styleSheet -> page
-                .addStyleSheet(styleSheet.value(), styleSheet.loadMode()));
+        dependencies.getStyleSheets().forEach(styleSheet -> {
+            String resolved = FrontendDependencyUrlResolver
+                    .resolveToContextRoot(styleSheet.value());
+            if (resolved != null) {
+                page.addStyleSheet(resolved, styleSheet.loadMode());
+            }
+        });
 
         VaadinService service = session.getService();
         if (!service.getDeploymentConfiguration().isProductionMode()) {
-            dependencies.getStyleSheets()
-                    .forEach(styleSheet -> ActiveStyleSheetTracker.get(service)
-                            .trackAddForComponent(styleSheet.value()));
+            dependencies.getStyleSheets().forEach(styleSheet -> {
+                String resolved = FrontendDependencyUrlResolver
+                        .resolveToContextRoot(styleSheet.value());
+                if (resolved != null) {
+                    ActiveStyleSheetTracker.get(service)
+                            .trackAddForComponent(resolved);
+                }
+            });
         }
 
         warnForUnavailableBundledDependencies(componentClass, dependencies);

flow-server/src/main/java/com/vaadin/flow/server/AppShellRegistry.java

@@ -280,48 +280,22 @@ public class Application implements AppShellConfigurator {
 
     private static String resolveStyleSheetHref(String href,
             VaadinRequest request) {
-        if (href == null || href.isBlank()) {
+        String normalized = FrontendDependencyUrlResolver
+                .resolveToContextRoot(href);
+        if (normalized == null) {
             return null;
         }
-        if (HandlerHelper
-                .isPathUnsafe(href.startsWith("/") ? href : "/" + href)) {
-            log.warn(
-                    "@StyleSheet href containing traversals ('../') are not allowed, ignored: {}",
-                    href);
-            return null;
-        }
-        href = href.trim();
-        // Accept absolute http(s) URLs unchanged
-        String lower = href.toLowerCase();
-        if (lower.startsWith("http://") || lower.startsWith("https://")) {
-            return href;
-        }
-        // Treat ./ as relative path to static resources location
-        if (href.startsWith("./")) {
-            href = href.substring(2);
-        }
-        // Accept bare paths beginning with '/' as-is
-        if (href.startsWith("/")) {
-            return href;
-        }
-
-        String contextProtocol = ApplicationConstants.CONTEXT_PROTOCOL_PREFIX;
-        if (!lower.startsWith(contextProtocol)) {
-            // Prepend context protocol so URL is resolved against the
-            // context root by the bootstrap URI resolver below.
-            href = contextProtocol + href;
-        }
         // Use the servlet-relative path (e.g. "./", "../") rather than the
         // absolute context path. The emitted href is then resolved by the
         // browser against <base>, which Vaadin sets from the actual request
-        // URL (honoring X-Forwarded-* headers). This works correctly behind
-        // reverse proxies that rewrite or strip the context path in the
-        // public URL.
+        // URL (honoring X-Forwarded-* headers). This matches how the
+        // bootstrap CONTEXT_ROOT_URL is computed for the UIDL path and works
+        // correctly behind reverse proxies that rewrite the public path.
         String servletPathToContextRoot = request.getService()
                 .getContextRootRelativePath(request);
         BootstrapHandler.BootstrapUriResolver resolver = new BootstrapHandler.BootstrapUriResolver(
                 servletPathToContextRoot, null);
-        return resolver.resolveVaadinUri(href);
+        return resolver.resolveVaadinUri(normalized);
     }
 
     /**

flow-server/src/main/java/com/vaadin/flow/server/FrontendDependencyUrlResolver.java

@@ -0,0 +1,95 @@
+/*
+ * Copyright 2000-2026 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.vaadin.flow.server;
+
+import java.io.Serializable;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import com.vaadin.flow.shared.ApplicationConstants;
+
+/**
+ * Resolves the {@code value()} of
+ * {@link com.vaadin.flow.component.dependency.StyleSheet} annotation values to
+ * a canonical form that
+ * {@link com.vaadin.flow.server.BootstrapHandler.BootstrapUriResolver} can
+ * expand at render time. The same rules are used whether the annotation is on
+ * an {@link com.vaadin.flow.component.page.AppShellConfigurator} or on an
+ * ordinary {@link com.vaadin.flow.component.Component}.
+ * <p>
+ * For internal framework use only.
+ */
+public final class FrontendDependencyUrlResolver implements Serializable {
+
+    private static final Logger LOGGER = LoggerFactory
+            .getLogger(FrontendDependencyUrlResolver.class);
+
+    private FrontendDependencyUrlResolver() {
+    }
+
+    /**
+     * Normalizes a frontend-dependency URL value to a form that the bootstrap
+     * URI resolver can expand.
+     * <p>
+     * Rules, in order:
+     * <ol>
+     * <li>{@code null} or blank values return {@code null}.</li>
+     * <li>Values containing path traversals ({@code ..}) are rejected with a
+     * warning and {@code null} is returned.</li>
+     * <li>{@code http://}, {@code https://}, {@code //}, {@code context://} and
+     * {@code base://} prefixes are returned unchanged.</li>
+     * <li>A leading {@code ./} is stripped.</li>
+     * <li>If the value (after the previous step) starts with {@code /}, it is
+     * returned unchanged.</li>
+     * <li>Otherwise, {@code context://} is prepended so the value resolves
+     * against the servlet context root.</li>
+     * </ol>
+     *
+     * @param rawValue
+     *            the raw annotation value
+     * @return the normalized value, or {@code null} if rejected
+     */
+    public static String resolveToContextRoot(String rawValue) {
+        if (rawValue == null || rawValue.isBlank()) {
+            return null;
+        }
+        String value = rawValue.trim();
+        String pathForCheck = value.startsWith("/") ? value : "/" + value;
+        if (HandlerHelper.isPathUnsafe(pathForCheck)) {
+            LOGGER.warn(
+                    "Frontend dependency value containing traversals ('../') is not allowed, ignored: {}",
+                    value);
+            return null;
+        }
+        String lower = value.toLowerCase();
+        if (lower.startsWith("http://") || lower.startsWith("https://")
+                || lower.startsWith("//")
+                || lower.startsWith(
+                        ApplicationConstants.CONTEXT_PROTOCOL_PREFIX)
+                || lower.startsWith(
+                        ApplicationConstants.BASE_PROTOCOL_PREFIX)) {
+            return value;
+        }
+        if (value.startsWith("./")) {
+            value = value.substring(2);
+        }
+        if (value.startsWith("/")) {
+            return value;
+        }
+        return ApplicationConstants.CONTEXT_PROTOCOL_PREFIX + value;
+    }
+}

flow-server/src/test/java/com/vaadin/flow/component/ComponentTest.java

@@ -1322,7 +1322,7 @@ public void usesComponent() {
                 ui.getInternals().getDependencyList().getPendingSendToClient());
         assertEquals(1, pendingDependencies.size());
 
-        assertDependency(Dependency.Type.STYLESHEET, "css.css",
+        assertDependency(Dependency.Type.STYLESHEET, "context://css.css",
                 pendingDependencies);
     }
 
@@ -1337,7 +1337,7 @@ public void usesChain() {
                 internals.getDependencyList().getPendingSendToClient());
         assertEquals(1, pendingDependencies.size());
 
-        assertDependency(Dependency.Type.STYLESHEET, "css.css",
+        assertDependency(Dependency.Type.STYLESHEET, "context://css.css",
                 pendingDependencies);
     }
 
@@ -1351,9 +1351,9 @@ public void circularDependencies() {
                 dependencyList.getPendingSendToClient());
         assertEquals(2, pendingDependencies.size());
 
-        assertDependency(Dependency.Type.STYLESHEET, "css1.css",
+        assertDependency(Dependency.Type.STYLESHEET, "context://css1.css",
                 pendingDependencies);
-        assertDependency(Dependency.Type.STYLESHEET, "css2.css",
+        assertDependency(Dependency.Type.STYLESHEET, "context://css2.css",
                 pendingDependencies);
 
         internals = new MockUI().getInternals();
@@ -1362,9 +1362,9 @@ public void circularDependencies() {
         pendingDependencies = getDependenciesMap(
                 dependencyList.getPendingSendToClient());
         assertEquals(2, pendingDependencies.size());
-        assertDependency(Dependency.Type.STYLESHEET, "css1.css",
+        assertDependency(Dependency.Type.STYLESHEET, "context://css1.css",
                 pendingDependencies);
-        assertDependency(Dependency.Type.STYLESHEET, "css2.css",
+        assertDependency(Dependency.Type.STYLESHEET, "context://css2.css",
                 pendingDependencies);
 
     }
@@ -1386,7 +1386,7 @@ public void noJsDependenciesAreAdded() {
         Map<String, Dependency> pendingDependencies = getDependenciesMap(
                 dependencyList.getPendingSendToClient());
         assertEquals(1, pendingDependencies.size());
-        assertDependency(Dependency.Type.STYLESHEET, "css.css",
+        assertDependency(Dependency.Type.STYLESHEET, "context://css.css",
                 pendingDependencies);
     }
 

flow-server/src/test/java/com/vaadin/flow/server/FrontendDependencyUrlResolverTest.java

@@ -0,0 +1,85 @@
+/*
+ * Copyright 2000-2026 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.vaadin.flow.server;
+
+import org.junit.Assert;
+import org.junit.Test;
+
+public class FrontendDependencyUrlResolverTest {
+
+    @Test
+    public void resolveToContextRoot_nullOrBlank_returnsNull() {
+        Assert.assertNull(
+                FrontendDependencyUrlResolver.resolveToContextRoot(null));
+        Assert.assertNull(
+                FrontendDependencyUrlResolver.resolveToContextRoot(""));
+        Assert.assertNull(
+                FrontendDependencyUrlResolver.resolveToContextRoot("   "));
+    }
+
+    @Test
+    public void resolveToContextRoot_pathTraversal_returnsNull() {
+        Assert.assertNull(FrontendDependencyUrlResolver
+                .resolveToContextRoot("../foo.css"));
+        Assert.assertNull(FrontendDependencyUrlResolver
+                .resolveToContextRoot("foo/../bar.css"));
+    }
+
+    @Test
+    public void resolveToContextRoot_externalUrls_unchanged() {
+        Assert.assertEquals("http://cdn/x.css", FrontendDependencyUrlResolver
+                .resolveToContextRoot("http://cdn/x.css"));
+        Assert.assertEquals("https://cdn/x.css", FrontendDependencyUrlResolver
+                .resolveToContextRoot("https://cdn/x.css"));
+        Assert.assertEquals("//cdn/x.css", FrontendDependencyUrlResolver
+                .resolveToContextRoot("//cdn/x.css"));
+    }
+
+    @Test
+    public void resolveToContextRoot_explicitProtocols_unchanged() {
+        Assert.assertEquals("context://foo.css", FrontendDependencyUrlResolver
+                .resolveToContextRoot("context://foo.css"));
+        Assert.assertEquals("base://foo.css", FrontendDependencyUrlResolver
+                .resolveToContextRoot("base://foo.css"));
+    }
+
+    @Test
+    public void resolveToContextRoot_absoluteServerPath_unchanged() {
+        Assert.assertEquals("/assets/foo.css", FrontendDependencyUrlResolver
+                .resolveToContextRoot("/assets/foo.css"));
+    }
+
+    @Test
+    public void resolveToContextRoot_dotSlashRelative_strippedAndPrefixed() {
+        Assert.assertEquals("context://foo.css", FrontendDependencyUrlResolver
+                .resolveToContextRoot("./foo.css"));
+    }
+
+    @Test
+    public void resolveToContextRoot_bareRelative_prefixedWithContext() {
+        Assert.assertEquals("context://foo.css",
+                FrontendDependencyUrlResolver.resolveToContextRoot("foo.css"));
+        Assert.assertEquals("context://styles/foo.css",
+                FrontendDependencyUrlResolver
+                        .resolveToContextRoot("styles/foo.css"));
+    }
+
+    @Test
+    public void resolveToContextRoot_trimsWhitespace() {
+        Assert.assertEquals("context://foo.css", FrontendDependencyUrlResolver
+                .resolveToContextRoot("  foo.css  "));
+    }
+}