Firefox Android PWA does not show Hermes WebUI icon, just a big letter "W"

[dctr]

I noticed when I install the Hermes WebUI PWA on Android (using Firefox), it does not give me a nice icon, just a bit letter "W".

Analyse my locally checked out hermes-webui repository.
Write me a full bug report with your issue analysis and proposed solution that I can post on the hermes-webui GitHub issue tracker. It should contain all required context, and be instructional enough so that an AI coding agent can implement a full bug fix from it.

---

Title

Firefox Android PWA installed from a /session/... URL gets a generated “W” app icon because manifest.json resolves to /session/manifest.json and returns HTML

Summary

When installing Hermes WebUI as a PWA from Firefox on Android, the installed home-screen app can show a generated icon — in my case a large “W” — instead of the Hermes favicon/app icon.

This appears to happen when the user installs the PWA while currently on a session route such as:

https://webui.example.com/session/<session_id>

The source confirms that static/index.html declares the manifest as a relative URL before the page injects its dynamic <base> tag:

<link rel="manifest" href="manifest.json" crossorigin="use-credentials">
...
<script>
  ... document.write('<base href="'+location.origin+p+'">') ...
</script>

As a result, at least Firefox Android appears able to resolve the manifest relative to the current session URL:

/session/manifest.json

But the backend route handler treats all /session/* paths as app-shell routes and returns index.html, not manifest JSON. Firefox then fails to parse the manifest and falls back to a generated shortcut icon.

Environment

Observed on:

• Hermes WebUI local install: ~/.hermes/hermes-webui
• WebUI version served: v0.51.59
• Browser: Firefox on Android
• Install mode: Firefox Android “Install” / “Add to Home screen”
• Reverse proxy: Caddy in front of local WebUI, though the bug appears to be in WebUI routing/HTML and should reproduce without Caddy

Actual behaviour

If the PWA is installed from a session URL, the installed Android home-screen icon is not the Hermes app icon. Firefox Android creates a fallback/generated icon. In my case it displayed a large “W”, presumably derived from “webui”.

Expected behaviour

Installing Hermes WebUI as a PWA from any valid app route, including /session/<id>, should use the Hermes app icons declared in manifest.json, e.g.:

{
  "src": "static/favicon-512.png",
  "sizes": "512x512",
  "type": "image/png",
  "purpose": "any maskable"
}

Reproduction steps

1. Open Hermes WebUI in Firefox Android.

2. Navigate to an existing session, e.g.:

   https://webui.example.com/session/b7194f404c53
   

3. Use Firefox Android’s install/add-to-home-screen action.

4. Observe the installed app icon on the Android home screen.

Result: generated “W” icon rather than Hermes icon.

Control case:

1. Open the root URL:

   https://webui.example.com/
   

2. Install from there.

Likely result: Firefox can fetch /manifest.json, so the proper icon should be available.

Source analysis

1. Manifest link appears before <base>

In static/index.html, the manifest and favicon links are declared before the dynamic base-href script:

<link rel="icon" type="image/svg+xml" href="static/favicon.svg">
<link rel="icon" type="image/png" sizes="32x32" href="static/favicon-32.png">
<link rel="shortcut icon" href="static/favicon.ico">
<link rel="manifest" href="manifest.json" crossorigin="use-credentials">
...
<!-- base href enables subpath mount support; all static paths must stay relative (no leading slash) -->
<script>
  (function(){
    var path=location.pathname,marker='/session/',i=path.indexOf(marker),p;
    i>=0?p=(path.slice(0,i+1)||'/'):p=(path.endsWith('/')?path:(path.replace(/\/[^\/]*$/,'/')||'/'));
    document.write('<base href="'+location.origin+p+'">');
  })()
</script>

This means the browser may process or resolve:

<link rel="manifest" href="manifest.json">

against the document URL before the later <base> is inserted.

If the current page is:

/session/b7194f404c53

then the manifest URL can become:

/session/manifest.json

2. /session/manifest.json returns the app shell, not the manifest

In api/routes.py, handle_get() handles /session/* before /manifest.json:

if parsed.path.startswith("/session/static/"):
    stripped = parsed._replace(path=parsed.path[len("/session"):])
    return _serve_static(handler, stripped)

if parsed.path in ("/", "/index.html") or parsed.path.startswith("/session/"):
    try:
        ...
        html = _INDEX_HTML_PATH.read_text(encoding="utf-8").replace("__WEBUI_VERSION__", version_token)
        return t(
            handler,
            inject_extension_tags(html),
            content_type="text/html; charset=utf-8",
        )
    except Exception as exc:
        return _serve_shell_unavailable(handler, exc)

if parsed.path in ("/manifest.json", "/manifest.webmanifest"):
    ...
    handler.send_header("Content-Type", "application/manifest+json; charset=utf-8")
    ...

So:

GET /manifest.json

returns the manifest correctly, but:

GET /session/manifest.json

matches parsed.path.startswith("/session/") first and returns index.html.

I verified this locally:

GET /session/manifest.json
→ 200 OK
→ Content-Type: text/html; charset=utf-8
→ Body starts with <!doctype html>

This is invalid for a Web App Manifest request.

3. The declared icon files themselves are valid

static/manifest.json contains the expected icons:

{
  "name": "Hermes",
  "short_name": "Hermes",
  "description": "Hermes AI Agent Web UI",
  "start_url": "./",
  "display": "standalone",
  "background_color": "#0D0D1A",
  "theme_color": "#0D0D1A",
  "orientation": "portrait-primary",
  "icons": [
    {
      "src": "static/favicon.svg",
      "sizes": "any",
      "type": "image/svg+xml",
      "purpose": "any maskable"
    },
    {
      "src": "static/favicon-32.png",
      "sizes": "32x32",
      "type": "image/png"
    },
    {
      "src": "static/favicon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "static/favicon-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any maskable"
    }
  ]
}

The PNG files exist and are served correctly:

static/favicon-32.png   → 32x32 PNG
static/favicon-192.png  → 192x192 PNG
static/favicon-512.png  → 512x512 PNG

The issue is not missing icon assets. It is incorrect manifest URL resolution / route handling.

Proposed fix

There are two reasonable layers of fix. I recommend doing both: one client-side prevention and one server-side hardening.

Fix A — make manifest and icon URLs robust

Move the dynamic <base> insertion before any relative manifest/icon/static links or make the manifest link immune to session-relative resolution.

Because Hermes WebUI supports subpath mounting, avoid simply changing this to an absolute root path:

<link rel="manifest" href="/manifest.json">

That would break installs under subpath deployments such as:

https://example.com/hermes/

Instead, prefer moving the existing dynamic base-href script before the manifest/favicon links:

<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Hermes</title>

<!-- base href enables subpath mount support; all static paths must stay relative (no leading slash) -->
<script>
  (function(){
    var path=location.pathname,marker='/session/',i=path.indexOf(marker),p;
    i>=0?p=(path.slice(0,i+1)||'/'):p=(path.endsWith('/')?path:(path.replace(/\/[^\/]*$/,'/')||'/'));
    document.write('<base href="'+location.origin+p+'">');
  })()
</script>

<link rel="icon" type="image/svg+xml" href="static/favicon.svg">
<link rel="icon" type="image/png" sizes="32x32" href="static/favicon-32.png">
<link rel="shortcut icon" href="static/favicon.ico">
<link rel="manifest" href="manifest.json" crossorigin="use-credentials">
...

With this ordering, a page at:

/session/b7194f404c53

should have a base href of:

https://webui.example.com/

so the manifest resolves to:

https://webui.example.com/manifest.json

For subpath deployments, the base logic should continue to resolve relative to the subpath.

Fix B — harden route handling for session-prefixed PWA assets

Add explicit aliases before the generic /session/* shell route for session-prefixed PWA resources:

if parsed.path in ("/session/manifest.json", "/session/manifest.webmanifest"):
    stripped = parsed._replace(path=parsed.path[len("/session"):])
    return handle_get(handler, stripped)

if parsed.path == "/session/sw.js":
    stripped = parsed._replace(path=parsed.path[len("/session"):])
    return handle_get(handler, stripped)

Or refactor to avoid recursion and call shared helpers for manifest and service-worker serving.

The important part: /session/manifest.json must not return index.html.

This is a defensive compatibility fix for browsers that resolve the manifest before or independently of the dynamic <base> tag. It also makes the failure mode self-correcting if another relative PWA path escapes through the same route shape.

Optional Fix C — make manifest icon src entries explicitly relative to the manifest

The manifest currently uses:

"src": "static/favicon-512.png"

That should resolve relative to the manifest URL, so it is fine if the manifest is fetched from /manifest.json.

If supporting /session/manifest.json as an alias, ensure either:

1. the alias returns the same manifest but browser resolves icon URLs relative to /session/manifest.json, which would become /session/static/favicon-512.png; this currently works because /session/static/* is mapped to /static/*, or
2. rewrite manifest icon src values to ./static/... consistently, or
3. serve /session/manifest.json with a manifest whose icon URLs are correct for that path.

Given /session/static/* already works, option 1 is probably sufficient.

Suggested tests

Add regression tests covering both the static HTML ordering and the live route behaviour.

1. index.html ordering test

Assert that the dynamic base script appears before the manifest link:

def test_base_href_script_precedes_manifest_link():
    src = Path("static/index.html").read_text(encoding="utf-8")
    base_idx = src.index("document.write('<base href=")
    manifest_idx = src.index('<link rel="manifest"')
    assert base_idx < manifest_idx

This prevents reintroducing the same ordering bug.

2. /manifest.json still serves manifest JSON

Existing tests may already cover this, but ensure:

def test_manifest_json_served_as_manifest_json(test_server):
    r = requests.get(test_server.url + "/manifest.json")
    assert r.status_code == 200
    assert "application/manifest+json" in r.headers["Content-Type"]
    assert r.json()["icons"]

3. /session/manifest.json must not serve HTML

This is the key regression test:

def test_session_manifest_json_does_not_return_app_shell(test_server):
    r = requests.get(test_server.url + "/session/manifest.json")
    assert r.status_code == 200
    assert "application/manifest+json" in r.headers["Content-Type"]
    data = r.json()
    assert data["name"] == "Hermes"
    assert any(icon.get("sizes") == "512x512" for icon in data["icons"])
    assert not r.text.lstrip().startswith("<!doctype html>")

If the chosen fix is “base ordering only” and not route hardening, this test would fail. I recommend route hardening as well because it catches real-world browser behaviour and prevents the same generated-icon failure.

4. Session-prefixed icons still work

Since manifest icon URLs may resolve through /session/static/..., preserve this behaviour:

def test_session_static_favicon_512_serves_png(test_server):
    r = requests.get(test_server.url + "/session/static/favicon-512.png")
    assert r.status_code == 200
    assert r.headers["Content-Type"].startswith("image/png")
    assert r.content.startswith(b"\x89PNG\r\n\x1a\n")

5. Optional service worker alias test

If adding /session/sw.js hardening:

def test_session_sw_js_serves_javascript(test_server):
    r = requests.get(test_server.url + "/session/sw.js")
    assert r.status_code == 200
    assert "application/javascript" in r.headers["Content-Type"]
    assert "self.addEventListener" in r.text

Acceptance criteria

• Installing from / still works.
• Installing from /session/<id> uses the Hermes icon, not a generated “W”.
• GET /manifest.json returns manifest JSON.
• GET /session/manifest.json returns manifest JSON, not HTML.
• GET /session/static/favicon-512.png returns the PNG icon.
• Subpath deployments continue to work; do not hardcode root-relative /manifest.json unless subpath support is handled separately.
• Existing PWA/service-worker cache-busting behaviour is preserved.

[nesquena-hermes]

Summary

This is a thorough report and the analysis matches what's actually in the tree. I read static/index.html:7-17 and api/routes.py:3003-3079 on origin/master and can confirm both halves:

1. Ordering bug in static/index.html. Lines 7-10 declare four URL-bearing links (svg favicon, png favicon, ico shortcut, manifest) and line 17 inserts the dynamic <base> via document.write. Because the manifest <link> is parsed before the <base> element exists, browsers that perform early manifest resolution (Firefox Android among them) compute the manifest URL against the document URL. On /session/<sid> that becomes /session/manifest.json.

<link rel="manifest" href="manifest.json" crossorigin="use-credentials">
...
<script>(function(){var path=location.pathname,marker='/session/',i=path.indexOf(marker),p;
  i>=0?p=(path.slice(0,i+1)||'/'):p=(path.endsWith('/')?path:(path.replace(/\/[^\/]*$/,'/')||'/'));
  document.write('<base href="'+location.origin+p+'">');})()
</script>

2. Route fallthrough in api/routes.py. The session shell route at api/routes.py:3013 catches /session/... paths and returns index.html, before the manifest route at :3066:

if parsed.path in ("/", "/index.html") or parsed.path.startswith("/session/"):
    # ... returns index.html ...

if parsed.path in ("/manifest.json", "/manifest.webmanifest"):
    # ... only reachable if path doesn't start with /session/

So GET /session/manifest.json → 200 text/html is exactly what the report describes.

Why the favicon links escape this on master

The <link rel="icon" href="static/favicon.svg"> declarations also pre-date the <base> script, but static/favicon.svg resolves to /session/static/favicon.svg on a session page, which does work because api/routes.py:3006-3011 explicitly strips the /session prefix for /session/static/* requests:

if parsed.path.startswith("/session/static/"):
    stripped = parsed._replace(path=parsed.path[len("/session"):])
    return _serve_static(handler, stripped)

The manifest doesn't get this rescue because its URL is manifest.json (no static/ prefix), so it falls into the session-shell branch instead.

Recommendation

Both fixes you propose are reasonable, and I agree with doing both rather than picking one. Defense-in-depth matters here because the failure mode silently produces a wrong icon — there's no console error a user would notice.

A minor refinement to Fix B: rather than recursing through handle_get, factor the manifest-serving block into a helper (e.g. _serve_manifest(handler)) and call it from both routes. The current handler is already long; recursion would work but is harder to reason about. Roughly:

def _serve_manifest(handler) -> bool:
    static_root = Path(__file__).parent.parent / "static"
    manifest_path = (static_root / "manifest.json").resolve()
    if manifest_path.exists():
        data = manifest_path.read_bytes()
        handler.send_response(200)
        handler.send_header("Content-Type", "application/manifest+json; charset=utf-8")
        handler.send_header("Cache-Control", "no-store")
        handler.send_header("Content-Length", str(len(data)))
        handler.end_headers()
        handler.wfile.write(data)
        return True
    return j(handler, {"error": "not found"}, status=404)

Then have both if parsed.path in ("/manifest.json", "/manifest.webmanifest") and a new if parsed.path in ("/session/manifest.json", "/session/manifest.webmanifest") call it. Same for /sw.js vs /session/sw.js. Existing service-worker handler is at api/routes.py:3080.

Test placement

The PWA test file tests/test_pwa_manifest_sw.py already exists and pins manifest content-type and route presence (e.g. line 141-145). Add the session-prefixed regression tests there to keep all PWA route tests in one file. The test_base_href_script_precedes_manifest_link HTML-ordering test is well-targeted and would catch a future re-introduction of the ordering bug.

One small caveat

You correctly note that browsers may re-resolve relative URLs when a <base> element appears later. Per the HTML5 spec the first <base> with href in document order is authoritative, but the timing of resolution (vs. fetching) varies. Moving the <base> script above the manifest link makes the behavior deterministic across browsers, which is the right fix. The route-hardening half is still worth doing because it also protects against bookmark/share-sheet flows that might directly hit /session/manifest.json.

Good report — file:line citations and proposed acceptance criteria are exactly the shape that makes this implementable from the issue alone.

[nesquena-hermes]

@dctr thanks for the detailed analysis — the manifest-resolves-to-/session/manifest.json mechanism is exactly right, and the static/index.html snippet confirms the load order is broken on Firefox Android (the dynamic <base> injection happens after manifest discovery).

Direction for a contributor pickup

Two fix shapes; either works, pick the one that's easier to land:

Option A — make the manifest URL absolute at HTML-emit time. In whatever route serves index.html (likely server.py or a Flask blueprint), rewrite <link rel="manifest" href="manifest.json"> to <link rel="manifest" href="/manifest.json"> at response time (or hard-code the absolute path in static/index.html). This bypasses the <base> race entirely. Simplest fix, ~1 LOC of HTML.

Option B — add a /session/<sid>/manifest.json route that returns the same manifest JSON the root route returns. Catches Firefox Android and any other client that resolves before <base>. Slightly more code but defense-in-depth.

I'd go with Option A. The manifest URL has no reason to be relative — it's always served from the root.

Verification

• Firefox Android: install PWA from /session/<sid>, confirm home-screen icon shows Hermes favicon (not a generated "W").
• Chrome Android: same check, should still work (it does today because Chrome resolves manifest after <base> injection).
• Desktop PWA (Chrome/Edge): no regression, manifest still loads.

Labeling bug + mobile, Milestone 2 (Power user features). Probably a ≤10 LOC fix.