Mercurial
annotate mrjunejune/PWA_SETUP.md @ 279:b3b547563ec7
Add Google connector service and agent wiki
Implement the C/Seobeo Google Drive and Gmail connector with encrypted OAuth storage, Zenbu authentication, browser testing, AI tool discovery, chunked HTTP decoding, and Bazel coverage. Consolidate repository guidance into progressive wiki documentation and enforce arena-first allocation for new first-party C code.
Co-authored-by: Copilot <[email protected]>
Copilot-Session: 84c338fd-0939-4bb3-b7f3-1062eb213e5d
| author | MrJuneJune <me@mrjunejune.com> |
|---|---|
| date | Mon, 17 Aug 2026 22:22:36 -0700 |
| parents | e02e2036ef84 |
| children |
| rev | line source |
|---|---|
| 209 | 1 # PWA Setup Guide |
| 2 | |
| 3 Your site is now configured as a Progressive Web App! 🎉 | |
| 4 | |
| 5 ## What's Been Added | |
| 6 | |
| 7 1. **manifest.json** - App configuration | |
| 8 2. **sw.js** - Service worker for caching and offline support | |
| 9 3. **pwa-register.js** - Service worker registration | |
| 10 4. **offline.html** - Offline fallback page | |
| 11 5. **Updated base_head.html** - Links to manifest and PWA script | |
| 12 | |
|
241
9c2eec61a152
[assets] Generate site images as WebP with Bazel
MrJuneJune <me@mrjunejune.com>
parents:
209
diff
changeset
|
13 ## App Icons and WebP Assets |
| 209 | 14 |
|
241
9c2eec61a152
[assets] Generate site images as WebP with Bazel
MrJuneJune <me@mrjunejune.com>
parents:
209
diff
changeset
|
15 All shipped raster images are generated as WebP by Bazel. Source PNGs live |
|
9c2eec61a152
[assets] Generate site images as WebP with Bazel
MrJuneJune <me@mrjunejune.com>
parents:
209
diff
changeset
|
16 under `mrjunejune/assets/png/` and are never copied into the release bundle. |
| 209 | 17 |
| 18 ```bash | |
|
241
9c2eec61a152
[assets] Generate site images as WebP with Bazel
MrJuneJune <me@mrjunejune.com>
parents:
209
diff
changeset
|
19 bazel build //mrjunejune:generated_webp_assets |
| 209 | 20 ``` |
| 21 | |
|
241
9c2eec61a152
[assets] Generate site images as WebP with Bazel
MrJuneJune <me@mrjunejune.com>
parents:
209
diff
changeset
|
22 The complete site bundle also runs the conversion pipeline: |
| 209 | 23 |
| 24 ```bash | |
|
241
9c2eec61a152
[assets] Generate site images as WebP with Bazel
MrJuneJune <me@mrjunejune.com>
parents:
209
diff
changeset
|
25 bazel build //mrjunejune:mrjunejune_server_bundle |
| 209 | 26 ``` |
| 27 | |
| 28 ## Optional: Screenshots (for better app install experience) | |
| 29 | |
| 30 Create screenshots of your site: | |
| 31 | |
| 32 ```bash | |
| 33 # Mobile screenshot (540x720) | |
|
241
9c2eec61a152
[assets] Generate site images as WebP with Bazel
MrJuneJune <me@mrjunejune.com>
parents:
209
diff
changeset
|
34 screenshot-mobile.webp |
| 209 | 35 |
| 36 # Desktop screenshot (1280x720) | |
|
241
9c2eec61a152
[assets] Generate site images as WebP with Bazel
MrJuneJune <me@mrjunejune.com>
parents:
209
diff
changeset
|
37 screenshot-desktop.webp |
| 209 | 38 ``` |
| 39 | |
|
241
9c2eec61a152
[assets] Generate site images as WebP with Bazel
MrJuneJune <me@mrjunejune.com>
parents:
209
diff
changeset
|
40 You can use browser DevTools to capture these. Add their PNG sources to the |
|
9c2eec61a152
[assets] Generate site images as WebP with Bazel
MrJuneJune <me@mrjunejune.com>
parents:
209
diff
changeset
|
41 WebP asset list before referencing the generated `.webp` files in the manifest. |
| 209 | 42 |
| 43 ## Testing Your PWA | |
| 44 | |
| 45 1. **Serve over HTTPS** - PWAs require HTTPS (localhost works for testing) | |
| 46 2. **Open Chrome DevTools** → Application tab → Manifest | |
| 47 3. **Check Service Worker** → Application tab → Service Workers | |
| 48 4. **Lighthouse Audit** → Run PWA audit to see score | |
| 49 | |
| 50 ## Install Prompt | |
| 51 | |
| 52 When users visit your site, they'll see an "Install App" button in the bottom-right corner for 10 seconds. They can: | |
| 53 - Click it to install immediately | |
| 54 - Use browser menu: "Install MrJuneJune" or "Add to Home Screen" | |
| 55 | |
| 56 ## Features | |
| 57 | |
| 58 ✅ **Offline Support** - Caches pages, CSS, JS, fonts, images | |
| 59 ✅ **App Shortcuts** - Quick access to Blog and Notes | |
| 60 ✅ **Install Prompt** - Automatic install button | |
|
273
e02e2036ef84
add Layer 2 JRPG component system
MrJuneJune <me@mrjunejune.com>
parents:
241
diff
changeset
|
61 ✅ **Auto-updates** - New service workers activate and reload clients automatically |
| 209 | 62 ✅ **Fast Loading** - Cached resources load instantly |
| 63 | |
| 64 ## Customization | |
| 65 | |
| 66 Edit `manifest.json` to change: | |
| 67 - `theme_color` - App theme color | |
| 68 - `background_color` - Splash screen color | |
| 69 - `display` - `standalone`, `fullscreen`, `minimal-ui`, or `browser` | |
| 70 - `shortcuts` - App shortcut menu items | |
| 71 | |
| 72 Edit `sw.js` to change: | |
| 73 - `CACHE_VERSION` - Increment to force cache refresh | |
| 74 - `STATIC_CACHE` - Files to cache immediately | |
|
273
e02e2036ef84
add Layer 2 JRPG component system
MrJuneJune <me@mrjunejune.com>
parents:
241
diff
changeset
|
75 - Caching strategy: |
|
e02e2036ef84
add Layer 2 JRPG component system
MrJuneJune <me@mrjunejune.com>
parents:
241
diff
changeset
|
76 - HTML, CSS, JS, JSON, and WASM are network-first with offline cache fallback. |
|
e02e2036ef84
add Layer 2 JRPG component system
MrJuneJune <me@mrjunejune.com>
parents:
241
diff
changeset
|
77 - Fonts and images are stale-while-revalidate. |
|
e02e2036ef84
add Layer 2 JRPG component system
MrJuneJune <me@mrjunejune.com>
parents:
241
diff
changeset
|
78 - Component sandbox assets always bypass service-worker caching. |
|
e02e2036ef84
add Layer 2 JRPG component system
MrJuneJune <me@mrjunejune.com>
parents:
241
diff
changeset
|
79 |
|
e02e2036ef84
add Layer 2 JRPG component system
MrJuneJune <me@mrjunejune.com>
parents:
241
diff
changeset
|
80 Unversioned application code must not use cache-first. That can preserve stale |
|
e02e2036ef84
add Layer 2 JRPG component system
MrJuneJune <me@mrjunejune.com>
parents:
241
diff
changeset
|
81 production CSS or JavaScript indefinitely when a deployment reuses the same URL. |
| 209 | 82 |
| 83 ## Testing on Mobile | |
| 84 | |
| 85 ### Android: | |
| 86 1. Open Chrome | |
| 87 2. Visit your site | |
| 88 3. Tap menu → "Install app" or "Add to Home Screen" | |
| 89 | |
| 90 ### iOS (Safari): | |
| 91 1. Open Safari | |
| 92 2. Tap Share button | |
| 93 3. Tap "Add to Home Screen" | |
| 94 | |
| 95 Note: iOS has limited PWA support (no install prompt, limited background features) | |
| 96 | |
| 97 ## Debugging | |
| 98 | |
| 99 Check console for: | |
| 100 - `[PWA]` - Registration events | |
| 101 - `[SW]` - Service worker caching events | |
| 102 | |
| 103 Clear cache: | |
| 104 ```js | |
| 105 navigator.serviceWorker.controller.postMessage({ type: 'CLEAR_CACHE' }); | |
| 106 ``` | |
| 107 | |
| 108 ## Next Steps | |
| 109 | |
| 110 1. Generate the PNG icons (see commands above) | |
| 111 2. Test on HTTPS | |
| 112 3. Run Lighthouse audit | |
| 113 4. Deploy and test on mobile device | |
| 114 5. Consider adding: | |
| 115 - Push notifications | |
| 116 - Background sync | |
| 117 - Share target API |