---

name: pwa-optimizer description: Build and audit production-grade PWA implementations for Next.js/Vite with reliable update flows (including iOS installed-PWA freshness), service worker lifecycle control, and quality scoring.

PWA Optimizer

Webアプリを「インストールできる」だけでなく、「継続運用で古くならない」PWAにするためのスキル。

Trigger

• 「PWA対応」「ホーム画面に追加」「Webアプリをアプリ化」
• 「PWAが古いまま更新されない」「iPhoneのPWAで新機能が出ない」
• 「service worker更新」「PWA品質監査」

Core Policy

• 利用者に PWA削除→再インストール を前提にしない。
• 機能/UI更新は通常、再インストール不要で反映される設計にする。
• 例外として iOS の manifest メタデータ更新（アイコン名/start_url など）は再インストールが必要になる場合がある。

Workflow

1. 対象プロジェクトの構造を判定（src/app / app / Vite）。
2. pwa-audit.sh で現状監査（support level + quality score）。
3. 必須要件（manifest / icon / service worker）を不足分実装。
4. 更新フロー（SW登録・起動時更新チェック・更新適用導線）を実装。
5. 再監査して supportLevel=full かつ品質目標を満たすまで修正。

Required Implementation

1) Manifest

• Next.js: app/manifest.ts または src/app/manifest.ts
• Vite/その他: public/manifest.json
• name, short_name, start_url, display: "standalone", icons(192/512) を含める

2) Icons

• public/icons/icon-192x192.png
• public/icons/icon-512x512.png
• public/apple-touch-icon.png（iOS推奨）

3) Service Worker Lifecycle

• public/sw.js（または同等）を配置
• クライアントで navigator.serviceWorker.register(...) を実装
• registration.update() を起動時に呼ぶ
• 更新検知時にユーザーへ適用導線を出す（updatefound / waiting）
• skipWaiting + controllerchange で確実に反映
• updateViaCache: "none" を使い sw.js 更新の取りこぼしを減らす

Reference Snippets

SW登録のクライアント実装とsw.jsのリファレンスコードは references/sw-registration.md を参照。

Quality Rubric

supportLevel:

• full: manifest + SW file + SW registration
• partial: manifestのみ または SWはあるがregistrationなし
• none: 上記を満たさない

qualityScore (0-100):

• hasManifest: 10
• hasServiceWorkerFile: 10
• hasServiceWorkerRegistration: 20
• hasStartupUpdateCheck: 15
• hasUpdateViaCacheNone: 10
• hasSkipWaiting: 10
• hasControllerChangeReload: 10
• hasUpdatePromptHook: 15

grade:

• A: 85+
• B: 70-84
• C: 50-69
• D: 0-49

Output Contract

このスキル使用時は必ず以下を返す:

1. supportLevel, qualityScore, grade
2. チェック項目ごとの pass/fail
3. 重大な欠落に対する具体修正（ファイルパス付き）
4. iOS既存PWAの stale リスク有無

Scripts

• 監査: ./pwa-audit.sh <project-path>
• 初期導入: ./pwa-init.sh <project-path> [--app-name "App Name"] [--theme-color "#000000"]
• 一括監査: ./pwa-batch-audit.sh

⚠️ よくある落とし穴

• iOS PWA で更新が反映されない: iOS の既存インストール済み PWA で機能更新が反映されない場合、まず SW の更新フロー実装（registration.update() + skipWaiting + controllerchange）を疑う。manifest メタデータ（アイコン名・start_url）の変更は再インストールが必要になる場合がある
• updateViaCache 未設定で sw.js が更新されない: navigator.serviceWorker.register('/sw.js') のデフォルトでは SW ファイルがブラウザキャッシュから返されることがある。{ updateViaCache: 'none' } を必ず指定する
• HTTPS 環境でないと SW が登録できない: Service Worker は HTTPS 必須（localhost/127.0.0.1 は例外）。HTTP 環境で「SW registration failed」になったらまず URL スキームを確認する
• iOS で beforeinstallprompt を前提にしてしまう: iOS は beforeinstallprompt イベントに非対応。インストール促進UIを iOS 向けに実装する場合はカスタムのバナーやモーダルが必要
• manifest の background_color / theme_color がデフォルトのまま: Next.js のデフォルト #ffffff や #000000 のまま放置すると、スプラッシュ画面やステータスバーがアプリの実際のテーマと乖離する。アプリの bg-cream 等に合わせる