a2acalling 0.6.75 → 0.6.76

package/docs/plans/2026-03-06-a2a-101-dmg-installer-polish.md

@@ -0,0 +1,229 @@
+# A2A-101: DMG Installer Polish Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Transform the default Tauri DMG into a professional installer with a branded background image, drag-to-Applications UX, proper volume icon, and complete icon set.
+
+**Architecture:** Uses Tauri v2's built-in DMG bundler configuration (`tauri.conf.json` → `bundle.macOS.dmg`) plus ImageMagick-generated background images and icons. No third-party DMG tools needed — everything is config-driven.
+
+**Tech Stack:** ImageMagick (image generation), JSON (tauri.conf.json), shell scripting, PNG/ICNS formats.
+
+---
+
+## Task 1: Generate DMG Background Images
+
+**Files:**
+- Create: `native/macos/src-tauri/dmg-background.png` (600x400)
+- Create: `native/macos/src-tauri/dmg-background@2x.png` (1200x800)
+
+**Step 1: Generate the 1x background (600x400)**
+
+Use ImageMagick to create a dark-themed background with the app name, drag arrow, and "Applications" label. The design matches the dashboard dark theme (`#0B0E14` base, `#151B28` panel, `#3B82F6` accent).
+
+```bash
+cd native/macos/src-tauri
+
+magick -size 600x400 \
+  xc:'#0B0E14' \
+  -fill '#151B28' -draw 'roundrectangle 20,20 580,380 16,16' \
+  -font 'Helvetica' -pointsize 28 -fill '#e2e8f0' \
+  -gravity North -annotate +0+45 'A2A Callbook' \
+  -pointsize 14 -fill '#94a3b8' \
+  -gravity North -annotate +0+82 'Drag to Applications to install' \
+  -fill '#3B82F6' -pointsize 48 \
+  -gravity Center -annotate +0+20 '→' \
+  -pointsize 12 -fill '#94a3b8' \
+  -gravity SouthWest -annotate +95+95 '.app' \
+  -gravity SouthEast -annotate +75+95 'Applications' \
+  dmg-background.png
+```
+
+**Step 2: Generate the 2x retina background (1200x800)**
+
+Same design at double resolution:
+
+```bash
+magick -size 1200x800 \
+  xc:'#0B0E14' \
+  -fill '#151B28' -draw 'roundrectangle 40,40 1160,760 32,32' \
+  -font 'Helvetica' -pointsize 56 -fill '#e2e8f0' \
+  -gravity North -annotate +0+90 'A2A Callbook' \
+  -pointsize 28 -fill '#94a3b8' \
+  -gravity North -annotate +0+164 'Drag to Applications to install' \
+  -fill '#3B82F6' -pointsize 96 \
+  -gravity Center -annotate +0+40 '→' \
+  -pointsize 24 -fill '#94a3b8' \
+  -gravity SouthWest -annotate +190+190 '.app' \
+  -gravity SouthEast -annotate +150+190 'Applications' \
+  dmg-background@2x.png
+```
+
+**Step 3: Verify images**
+
+```bash
+identify dmg-background.png dmg-background@2x.png
+```
+
+Expected: `600x400` and `1200x800` PNG files.
+
+**Step 4: Commit**
+
+```bash
+git add native/macos/src-tauri/dmg-background.png native/macos/src-tauri/dmg-background@2x.png
+git commit -m "feat(a2a-101): add DMG background images"
+```
+
+---
+
+## Task 2: Generate Missing Icon Sizes
+
+**Files:**
+- Create: `native/macos/src-tauri/icons/256x256.png`
+- Create: `native/macos/src-tauri/icons/512x512.png`
+- Create: `native/macos/src-tauri/icons/512x512@2x.png` (1024x1024)
+
+**Step 1: Generate from the highest-res existing icon**
+
+The existing `128x128@2x.png` (256x256) is the largest. Scale up for larger sizes (or use as base):
+
+```bash
+cd native/macos/src-tauri/icons
+
+# 256x256 from 128x128@2x (which is already 256x256 — just copy)
+cp 128x128@2x.png 256x256.png
+
+# 512x512 — scale up from 256x256
+magick 256x256.png -resize 512x512 -filter Lanczos 512x512.png
+
+# 512x512@2x (1024x1024) — scale up
+magick 256x256.png -resize 1024x1024 -filter Lanczos 512x512@2x.png
+```
+
+**Step 2: Verify all icon sizes exist**
+
+```bash
+identify icons/*.png
+```
+
+Expected: 32x32, 128x128, 256x256 (128x128@2x), 256x256, 512x512, 512x512@2x (1024x1024).
+
+**Step 3: Commit**
+
+```bash
+git add native/macos/src-tauri/icons/256x256.png native/macos/src-tauri/icons/512x512.png native/macos/src-tauri/icons/512x512@2x.png
+git commit -m "feat(a2a-101): add missing icon sizes for crisp rendering"
+```
+
+---
+
+## Task 3: Generate Volume Icon
+
+**Files:**
+- Create: `native/macos/src-tauri/volume-icon.icns`
+
+**Step 1: Create volume icon from existing app icon**
+
+The `.icns` format on Linux can be created using `png2icns` (from `icnsutils` package) or by building a raw ICNS with ImageMagick. If `png2icns` is not available, create a high-quality PNG that the Tauri bundler can use.
+
+```bash
+# Check if png2icns is available
+which png2icns 2>/dev/null
+
+# If available:
+cd native/macos/src-tauri
+png2icns volume-icon.icns icons/256x256.png icons/128x128.png icons/32x32.png
+
+# If not available, copy the existing icon.icns as the volume icon:
+cp icons/icon.icns volume-icon.icns
+```
+
+**Step 2: Commit**
+
+```bash
+git add native/macos/src-tauri/volume-icon.icns
+git commit -m "feat(a2a-101): add volume icon for DMG"
+```
+
+---
+
+## Task 4: Configure DMG in tauri.conf.json
+
+**Files:**
+- Modify: `native/macos/src-tauri/tauri.conf.json`
+
+**Step 1: Add DMG configuration and update icon list**
+
+Read the file first. Add a `dmg` section inside `bundle.macOS`:
+
+```json
+"dmg": {
+  "background": "dmg-background.png",
+  "windowSize": { "width": 600, "height": 400 },
+  "windowPosition": { "x": 200, "y": 200 },
+  "appPosition": { "x": 160, "y": 240 },
+  "applicationFolderPosition": { "x": 440, "y": 240 }
+}
+```
+
+Also update the `icon` array to include the new sizes:
+
+```json
+"icon": [
+  "icons/32x32.png",
+  "icons/128x128.png",
+  "icons/128x128@2x.png",
+  "icons/256x256.png",
+  "icons/512x512.png",
+  "icons/512x512@2x.png"
+]
+```
+
+**Step 2: Validate JSON syntax**
+
+```bash
+node -e "JSON.parse(require('fs').readFileSync('native/macos/src-tauri/tauri.conf.json', 'utf8')); console.log('Valid JSON')"
+```
+
+**Step 3: Run `npm test` to verify no regressions**
+
+```bash
+npm test
+```
+
+**Step 4: Commit**
+
+```bash
+git add native/macos/src-tauri/tauri.conf.json
+git commit -m "feat(a2a-101): configure DMG background, window size, and icon positions"
+```
+
+---
+
+## Task 5: Update CONVENTIONS.md
+
+**Files:**
+- Modify: `CONVENTIONS.md`
+
+**Step 1: Add DMG polish section**
+
+Add after the "Native App Sidecar Lifecycle" section:
+
+```markdown
+## DMG Installer Polish (A2A-101)
+
+The macOS DMG installer uses Tauri's built-in DMG bundler with custom configuration:
+- Background images: `dmg-background.png` (600x400) and `@2x` retina variant (1200x800) in `native/macos/src-tauri/`
+- DMG config in `tauri.conf.json` under `bundle.macOS.dmg`: window size, app/Applications positions
+- Icon set: all standard sizes (32, 128, 256, 512, 512@2x) in `native/macos/src-tauri/icons/`
+- Do NOT use third-party DMG tools — Tauri's bundler handles everything
+- Background design uses dashboard dark theme colors (#0B0E14, #151B28, #3B82F6)
+```
+
+**Step 2: Run `npm test`**
+
+**Step 3: Commit**
+
+```bash
+git add CONVENTIONS.md
+git commit -m "docs(a2a-101): add DMG installer polish conventions"
+```