From a21f496de2a5323fe1403e5ec272d8e794b613bf Mon Sep 17 00:00:00 2001 From: Nathan Schneider Date: Thu, 22 Oct 2026 13:35:57 -0600 Subject: [PATCH] README: PWA deploy lessons (stale COPY layer, icon cache-busting, maskable safe zone, Firefox crossorigin, theme bars) --- README.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/README.md b/README.md index e2f75ae..caf9c8c 100644 --- a/README.md +++ b/README.md @@ -336,3 +336,23 @@ equal the number of members who have logged in to the sandbox. `mcp/server.py`, `mcp/image_server.py` md5s match the live volume; overlay image `registry.inference.coop/co-op/librechat-custom:20261019-fc9b11e` is deployed (container asset md5s match this repo). + +## PWA lessons (2026-10-22 — icon/band debugging) + +- **Builder COPY layers can be stale**: after editing any asset, build with + `--no-cache` and VERIFY the served file's md5 against the repo before + reporting success. (The 20261022-df55d7f build shipped a stale maskable icon + this way — the repo was right, the image wasn't.) +- **PWA icon URLs must carry a per-build `?v=`**: they are served with + `max-age=172800`, and remove/re-add of the PWA does not clear the phone's + HTTP cache — launchers keep rendering the previous build's icon bytes. + patch_index.py injects the query into every manifest icon src per build. +- **Maskable icons**: logo must sit inside the safe zone — ~66% of the canvas + on a solid brand background. Full-bleed logos get cropped ("zoomed in"). +- **Firefox Android**: `crossorigin="use-credentials"` on the manifest link + breaks icon resolution (blank launcher icon) — patch_index.py strips it. +- **Theme bars**: the manifest `theme_color` is one static value; Chromium's + nav bar and all Firefox bars use it even when the meta says otherwise. The + durable fix is `viewport-fit=cover` + standalone-mode safe-area padding + (custom.css) so the bands show the theme-correct page background; custom2.js + additionally syncs one meta `theme-color` to the app's resolved theme.