App icons: full-bleed tiles, three purposes, and an apple-touch-icon

[nuriapenya]

What?

Installing the PWA on an iPhone gave a black circle on a white rounded square. Platforms mask the home-screen tile themselves and fill any transparency first, and iOS fills with white, so pre-rounded artwork installs with white corners showing.

• The bundled icons are full-bleed, opaque and square. Nothing left for iOS to fill.
• Three purposes instead of one: any, maskable (the tile at 80%, so Android's adaptive masks crop into margin rather than into the mark), monochrome (Android 13+ themed icons).
• wp-admin now emits an apple-touch-icon. Core hooks wp_site_icon() to wp_head and login_head but not admin_head, which is why four bundled PNGs never reached an iPhone.

A Site Icon still wins, and still goes out as any only. maskable and monochrome describe how a piece of artwork is composed, and we only know that about ours.

No iOS startup images here: they match on an exact device media query, so the current iPhone and iPad range is 36 files and ~2 MB. Worth first checking whether iOS already draws an acceptable launch screen from the manifest's background_color.

Screenshots

Before	After

The label differs because the test site is named differently, not because of this change. The app takes its name from the site, as it did before.

Testing instructions

Setup

git fetch origin && git checkout pwa/platform-app-icons
npm install && npm run build
npm run env:start          # http://localhost:8890

Activate OpenStation, then check Settings → General has no Site Icon. A Site
Icon takes priority over the bundled files, so with one set you are testing the
wrong path.

In a desktop browser, no phone needed

1. Open the OpenStation screen, then DevTools → Application → Manifest.
2. Icons should list nine entries: five any (128/180/192/256/512), two
   maskable, two monochrome. None should fail to load.
3. Chrome draws a maskable preview there. The mark should sit inside the
   safe area rather than being cropped.
4. View source on the same page. The head should carry
   <link rel="apple-touch-icon" sizes="180x180" href=".../assets/pwa/icon-180.png">.
   On trunk there is no such tag at all.

On a phone, which is where the bug actually shows

A phone cannot reach localhost, so point wp-env at your machine's LAN address
first. Create .wp-env.override.json (gitignored):

{
	"config": {
		"WP_HOME": "http://YOUR-LAN-IP:8890",
		"WP_SITEURL": "http://YOUR-LAN-IP:8890"
	}
}

Run npm run env:start again. Skip this and the manifest hands the phone
localhost URLs and the install quietly fails.

1. On the same wifi, open http://YOUR-LAN-IP:8890/wp-admin/ on the phone.
2. Navigate to the OpenStation screen, not the Dashboard. The PWA meta tags
   only render on a shell request.
3. iPhone: Share → Add to Home Screen. Android: take Chrome's install prompt.
4. The tile should be black to its corners, with no white showing.

Delete any previous tile before re-adding. iOS caches home-screen icons hard
and will keep showing you the old one.

Then the Site Icon path

Set a Site Icon under Settings → General and reload. The manifest should switch
to the Site Icon URLs, all purpose: any with no maskable or monochrome, and
the apple-touch-icon should follow it.