# 10 - SPA Runtime Branding Shim
> Why the static `ARRFLIX` patch wasn't enough, what the shim does,
> and how to extend it when Jellyfin starts overwriting more state on upgrade.
Last verified: 2026-05-08 against Jellyfin 10.10.3 web bundle.
---
## TL;DR
`/web/index.html` already says `ARRFLIX` and embeds our logo as the
favicon (data URL). The browser tab still showed "Jellyfin" + the Jellyfin teal
triangle because **Jellyfin's SPA overwrites `document.title` at runtime** as it
hydrates. Two compounding effects:
1. **SPA runtime overwrite (primary cause).** Bundle code does
`document.title = d.Ay.translateHtml(document.title ...)` and per-route updates
via `LibraryMenu.setTitle` / `Page.setTitle`. Whatever the static `` is,
the SPA will replace it on first hydrate and again on every navigation.
2. **Service worker churn (secondary).** `serviceworker.js` registers and calls
`self.clients.claim()`. The shipped SW does NOT actually cache `index.html`
(it's a notification-only worker), but its presence still pins old clients
to whatever they had at first paint. Killing the SW once forces a clean reload.
Fix: a tiny self-contained shim in `<head>`, INLINE, BEFORE the bundle scripts.
It enforces the title and favicon both on hydrate and on every later DOM mutation.
---
## What the shim does
Lives in `web-overrides/index.html` between `<!-- ARRFLIX-SHIM-BEGIN -->` /
`-END` markers. Insertion is idempotent via `bin/inject-shim.py` (re-running the
script REPLACES the existing block instead of stacking duplicates).
Behaviour:
| Step | When | What |
|------|------|------|
| 1 | Page parse | `<script>` runs first thing inside `<head>`, before bundle. |
| 2 | DOM ready | `lockTitle()` strips/replaces "Jellyfin"; `lockFavicon()` re-pins icon hrefs to the data URL already in the page. |
| 3 | Mutation | A `MutationObserver` on `document.head` re-runs both lockers when the SPA tries to change `<title>` text or any `<link rel*="icon">` href. |
| 4 | Interval | A 1s `setInterval` is the safety net for late-binding navigations / route changes that bypass the head observer. |
| 5 | Once | `serviceWorker.getRegistrations()` finds anything pointing at `serviceworker.js` and calls `r.unregister()` so old clients reload fresh. `caches.keys()` is also flushed. |
The shim does NOT re-encode the logo. It reads the existing `data:image/png;base64,...`
href from the `<link rel="shortcut icon">` already in the page. So there's exactly
one copy of the logo data URL in the file.
---
## Files in play
```
/tmp/ARRFLIX/
bin/inject-shim.py # idempotent injector; the source of truth for shim content
web-overrides/index.html # bind-mounted to /jellyfin/jellyfin-web/index.html in the container
docs/10-spa-runtime-shim.md # this file
```
Server bind-mount (compose):
```yaml
volumes:
- /opt/docker/jellyfin/web-overrides/index.html:/jellyfin/jellyfin-web/index.html:ro
```
The container reads the bind-mounted file fresh on each request - no `docker
restart` needed when you re-deploy index.html.
---
## Deploying changes
```bash
# 1. Edit bin/inject-shim.py (NOT index.html directly - the script is the source of truth)
# 2. Re-run injector locally
python3 /tmp/ARRFLIX/bin/inject-shim.py
# 3. Copy to nullstone
scp /tmp/ARRFLIX/web-overrides/index.html user@192.168.0.100:/opt/docker/jellyfin/web-overrides/index.html
# 4. Verify
curl -ks https://arrflix.s8n.ru/web/index.html | grep -oE "ARRFLIX-SHIM-(BEGIN|END)"
curl -ks https://arrflix.s8n.ru/web/index.html | grep -oE "<title>[^<]*"
```
No container recreate is needed; the file is read on every HTTP request.
---
## First-deploy: forcing existing clients to reload
The shim's `r.unregister()` block runs unconditionally. The first time a user with
an old SW + old `index.html` cached visits the site after this deploy:
1. They get the new `index.html` (bind-mount serves it).
2. The shim runs, unregisters the SW, flushes `caches`.
3. The current page still shows the old behaviour (because the SW already
intercepted this navigation). They need ONE hard reload (Ctrl+Shift+R or
Cmd+Shift+R) to get a fully clean session.
4. Subsequent visits are clean.
If you want to STOP unregistering the SW after the wide deploy (e.g. to let
Jellyfin reinstate notification-click handling), edit the script section in
`bin/inject-shim.py`:
```js
if ('serviceWorker' in navigator) {
// disabled after 2026-05-08 wide rollout
// navigator.serviceWorker.getRegistrations().then(...);
}
```
Then re-run the injector and redeploy. There is no harm in leaving it on - the
shipped Jellyfin SW only handles `notificationclick`, which we don't use on a
private invite-only service.
---
## Caveats
- **Owner's first browser session** must hard-reload once after deploy to evict
the previously-registered service worker. Subsequent reloads, and all
first-time visitors, get the clean experience.
- **CustomCss** (logo replacement on the in-app drawer) is owned by a sibling
agent / `/Branding/Configuration`. The shim does NOT touch CustomCss. If the
in-app drawer logo regresses, that's the CSS branch, not this one.
- **The shim must remain self-contained.** No external `src=`. If it ever needs
more code, add it to the IIFE in `bin/inject-shim.py` and re-run.
- **First-paint flash.** Because the SPA still loads its own bundle, you may
briefly see "Jellyfin" in the tab title before the observer kicks in. Sub-100ms
on a fast connection - acceptable. For the colour flash (dark blue / grey
before Cineplex CSS arrives), see "Pre-bundle critical-path styles" below.
---
## Pre-bundle critical-path styles
A second inline block — a `