fix(pwa): give maskable icons a real background and safe zone

The manifest pointed `purpose: "maskable"` at the same full-bleed,
transparent PNGs it used for `purpose: "any"`. Those are different
contracts: Android applies its own mask (circle, squircle, teardrop)
and only guarantees the central circle of 80% diameter survives.

Two consequences, both measured against the committed 512px icon:

  - 4.3% of the logo's opaque pixels sit outside the safe zone, so the
    swoosh tips get clipped. Content reached 0.527 of the icon width
    from centre against a 0.400 budget.
  - Every pixel outside the glyph is transparent, so the launcher draws
    the logo straight onto the wallpaper instead of a solid tile.

Generate a dedicated maskable family instead. The artwork is trimmed to
its opaque bounds (which also re-centres it — it sits 82px from the left
of favicon.svg's viewBox and 50px from the right), scaled so its farthest
opaque pixel lands inside the safe circle, then flattened onto the
manifest's own background_color so icon and splash screen agree.

Scaling by farthest-pixel radius rather than by the bounding box matters:
the glyph is irregular, so its bounding-box corners are empty and the
box rule would shrink it more than the mask requires.

The `any`, favicon and Windows-tile families keep their transparency —
that is correct for those, and only the maskable pair is flattened.

Tests assert the two properties on the actual pixels, not just the
manifest wiring; all five fail if the manifest is pointed back at the
android-chrome files.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: ralyodio

public/icons/icon-maskable-192x192.png

@@ -46,7 +46,7 @@
       "purpose": "any"
     },
     {
-      "src": "/icons/android-chrome-192x192.png",
+      "src": "/icons/icon-maskable-192x192.png",
       "sizes": "192x192",
       "type": "image/png",
       "purpose": "maskable"
@@ -68,7 +68,7 @@
       "purpose": "any"
     },
     {
-      "src": "/icons/android-chrome-512x512.png",
+      "src": "/icons/icon-maskable-512x512.png",
       "sizes": "512x512",
       "type": "image/png",
       "purpose": "maskable"

public/icons/icon-maskable-512x512.png

@@ -63,6 +63,86 @@ const ICON_SIZES = [
 const SVG_PATH = './public/favicon.svg';
 const ICONS_DIR = './public/icons';
 
+// Maskable icons are a separate family from the ones above, not a re-label of
+// them. Android applies a platform mask (circle, squircle, teardrop...) and
+// guarantees only the central circle of 80% diameter survives, so a maskable
+// icon needs two things the `any` icons must NOT have: an opaque background,
+// and the artwork pulled inside that safe circle. The manifest used to point
+// both purposes at the same full-bleed transparent file, which meant Android
+// cropped 4.3% of the logo and showed the mask through the transparent pixels.
+const MASKABLE_SIZES = [192, 512];
+
+// The spec's safe circle has radius 0.40 of the icon width. Targeting 0.39
+// leaves a hair of slack: scaling to exactly 0.40 lands antialiased edge
+// pixels a fraction over the line once the artwork is downscaled to integer
+// dimensions, which the generated-icon test then flags.
+const SAFE_ZONE_RATIO = 0.39;
+
+// Matches manifest.json's `background_color`, so the installed icon and the
+// splash screen it launches into share a background.
+const MASKABLE_BACKGROUND = { r: 255, g: 255, b: 255, alpha: 1 };
+
+/**
+ * Distance from the centre of `buffer` to its farthest non-transparent pixel.
+ *
+ * Scaling by this rather than by the bounding box matters because the artwork
+ * is an irregular glyph: its bounding-box corners are empty, so the box-based
+ * rule would shrink it further than the mask actually requires.
+ */
+async function contentRadius(buffer) {
+  const { data, info } = await sharp(buffer).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+  const { width, height, channels } = info;
+  const cx = width / 2;
+  const cy = height / 2;
+  let maxRadius = 0;
+
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      if (data[(y * width + x) * channels + 3] < 16) continue;
+      const radius = Math.hypot(x + 0.5 - cx, y + 0.5 - cy);
+      if (radius > maxRadius) maxRadius = radius;
+    }
+  }
+
+  return maxRadius;
+}
+
+/**
+ * Render one maskable icon: trim the artwork to its opaque bounds, scale it so
+ * nothing escapes the safe circle, centre it, and flatten onto a solid colour.
+ *
+ * Trimming also re-centres the glyph — it sits off-centre in favicon.svg's
+ * viewBox (82px of padding on the left, 50px on the right), which a plain
+ * resize preserves and the mask then crops unevenly.
+ */
+async function generateMaskableIcon(svgBuffer, size) {
+  // Render at 2x so the trim finds precise edges before anything is downscaled.
+  const rendered = await sharp(svgBuffer, { density: 600 })
+    .resize(size * 2, size * 2, { fit: 'contain', background: { r: 0, g: 0, b: 0, alpha: 0 } })
+    .png()
+    .toBuffer();
+
+  const trimmed = await sharp(rendered).trim({ threshold: 1 }).png().toBuffer();
+  const { width, height } = await sharp(trimmed).metadata();
+  const scale = (SAFE_ZONE_RATIO * size) / (await contentRadius(trimmed));
+  const artWidth = Math.max(1, Math.round(width * scale));
+  const artHeight = Math.max(1, Math.round(height * scale));
+
+  const art = await sharp(trimmed).resize(artWidth, artHeight, { fit: 'fill' }).png().toBuffer();
+
+  return sharp({
+    create: { width: size, height: size, channels: 4, background: MASKABLE_BACKGROUND }
+  })
+    .composite([{
+      input: art,
+      left: Math.round((size - artWidth) / 2),
+      top: Math.round((size - artHeight) / 2)
+    }])
+    .flatten({ background: MASKABLE_BACKGROUND })
+    .png({ quality: 95, compressionLevel: 9 })
+    .toBuffer();
+}
+
 async function generateIcons() {
   try {
     console.log('🎨 Generating PNG icons from SVG...');
@@ -81,14 +161,10 @@ async function generateIcons() {
       const w = width ?? size;
       const h = height ?? size;
 
-      // `background` only paints the letterbox `fit: 'contain'` adds, and
-      // favicon.svg is square, so for every square icon here it paints nothing.
-      // The old `needsSolidBackground` branch that set an opaque background for
-      // PWA icons was therefore a no-op — the committed icons have always had
-      // transparent pixels. Giving the manifest's maskable 192/512 icons a
-      // genuinely opaque background needs `.flatten()` plus safe-zone padding,
-      // which changes how the installed icon looks; that's a deliberate design
-      // change rather than something to fold into the generator silently.
+      // These stay transparent on purpose. `background` only paints the
+      // letterbox `fit: 'contain'` adds, and favicon.svg is square, so it
+      // paints nothing here — which is right for `purpose: "any"`, favicons
+      // and Windows tiles. Only the maskable family below is flattened.
       await sharp(svgBuffer)
         .resize(w, h, {
           fit: 'contain',
@@ -103,10 +179,17 @@ async function generateIcons() {
       console.log(`✅ Generated ${name} (${w}x${h})`);
     }
 
+    for (const size of MASKABLE_SIZES) {
+      const name = `icon-maskable-${size}x${size}.png`;
+      const buffer = await generateMaskableIcon(svgBuffer, size);
+      await fs.writeFile(path.join(ICONS_DIR, name), buffer);
+      console.log(`✅ Generated ${name} (${size}x${size}, opaque, safe-zone padded)`);
+    }
+
     // favicon-16x16 / favicon-32x32 are part of ICON_SIZES above now; the old
     // extra pass wrote them to static/favicon-{16,32}.png, a path nothing reads.
     console.log('\n🎉 Icon generation complete!');
-    console.log(`📁 Generated ${ICON_SIZES.length} PNG icons in ${ICONS_DIR}/`);
+    console.log(`📁 Generated ${ICON_SIZES.length + MASKABLE_SIZES.length} PNG icons in ${ICONS_DIR}/`);
 
   } catch (error) {
     console.error('❌ Error generating icons:', error);

public/manifest.json

@@ -11,6 +11,7 @@
 import { describe, it, expect } from 'vitest';
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import sharp from 'sharp';
 
 const ROOT = resolve(process.cwd());
 const readText = (p) => readFileSync(resolve(ROOT, p), 'utf8');
@@ -127,7 +128,15 @@ describe('PWA installability', () => {
       expect(installer).not.toMatch(/\.\/static\//);
     });
 
-    const generated = [...generator.matchAll(/name:\s*'([^']+)'/g)].map((m) => m[1]);
+    // ICON_SIZES entries carry a literal `name:`; the maskable family is built
+    // from MASKABLE_SIZES with a templated filename, so collect both.
+    const maskableSizes = [
+      ...(generator.match(/MASKABLE_SIZES\s*=\s*\[([^\]]*)\]/)?.[1] ?? '').matchAll(/\d+/g)
+    ].map((m) => `icon-maskable-${m[0]}x${m[0]}.png`);
+    const generated = [
+      ...[...generator.matchAll(/name:\s*'([^']+)'/g)].map((m) => m[1]),
+      ...maskableSizes
+    ];
 
     it('regenerates every icon the manifest points at', () => {
       for (const icon of manifest.icons) {
@@ -154,4 +163,74 @@ describe('PWA installability', () => {
       }
     });
   });
+
+  // Android masks these to a circle/squircle/teardrop of its choosing and only
+  // guarantees the central circle of 80% diameter survives. Both properties
+  // below were violated when the manifest aimed `purpose: "maskable"` at the
+  // same full-bleed transparent PNGs it used for `purpose: "any"`.
+  describe('maskable icons', () => {
+    const manifest = JSON.parse(readText('public/manifest.json'));
+    const maskable = manifest.icons.filter((icon) =>
+      String(icon.purpose ?? '').split(/\s+/).includes('maskable')
+    );
+
+    it('does not reuse an `any` icon for `maskable`', () => {
+      const anySources = new Set(
+        manifest.icons
+          .filter((icon) => !String(icon.purpose ?? '').split(/\s+/).includes('maskable'))
+          .map((icon) => icon.src)
+      );
+
+      expect(maskable.length).toBeGreaterThan(0);
+      for (const icon of maskable) {
+        expect(anySources.has(icon.src)).toBe(false);
+      }
+    });
+
+    it.each(maskable.map((icon) => icon.src))('%s is fully opaque', async (src) => {
+      const { data, info } = await sharp(resolve(ROOT, 'public', src.replace(/^\//, '')))
+        .ensureAlpha()
+        .raw()
+        .toBuffer({ resolveWithObject: true });
+
+      let minAlpha = 255;
+      for (let i = 3; i < data.length; i += info.channels) {
+        if (data[i] < minAlpha) minAlpha = data[i];
+      }
+
+      // A transparent maskable icon lets the platform mask show through, so the
+      // launcher draws the logo over bare wallpaper instead of a solid tile.
+      expect(minAlpha).toBe(255);
+    });
+
+    it.each(maskable.map((icon) => icon.src))('%s keeps its artwork inside the safe zone', async (src) => {
+      const { data, info } = await sharp(resolve(ROOT, 'public', src.replace(/^\//, '')))
+        .ensureAlpha()
+        .raw()
+        .toBuffer({ resolveWithObject: true });
+      const { width, height, channels } = info;
+
+      // Corner pixel is background by construction; anything differing from it
+      // is artwork that the mask could clip.
+      const bg = [data[0], data[1], data[2]];
+      const cx = width / 2;
+      const cy = height / 2;
+      const safeRadius = 0.4 * width;
+      let maxRadius = 0;
+
+      for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+          const i = (y * width + x) * channels;
+          const delta =
+            Math.abs(data[i] - bg[0]) + Math.abs(data[i + 1] - bg[1]) + Math.abs(data[i + 2] - bg[2]);
+          if (delta < 24) continue;
+          const radius = Math.hypot(x + 0.5 - cx, y + 0.5 - cy);
+          if (radius > maxRadius) maxRadius = radius;
+        }
+      }
+
+      expect(maxRadius).toBeGreaterThan(0);
+      expect(maxRadius).toBeLessThanOrEqual(safeRadius);
+    });
+  });
 });