# Popup Update Panel Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Redesign the extension popup into a compact enterprise-style tool panel with clearer grouping, better spacing, and more readable update actions while keeping existing behavior unchanged.

**Architecture:** Keep the popup behavior in `src/popup/index.ts` and focus most UI changes in `src/popup/view.ts`. Add only the minimum structural changes needed to support grouped cards, clearer update states, and button hierarchy, then verify the existing popup tests still cover the update workflow.

**Tech Stack:** TypeScript, Chrome MV3 popup UI, Vitest, jsdom

---

## File Map

- Modify: `src/popup/view.ts`
  - Replace the current long text flow with grouped cards and clearer status blocks.
- Modify: `src/popup/index.html`
  - Add popup-level CSS for layout, spacing, typography, and button hierarchy.
- Modify: `src/popup/index.ts`
  - Keep logic unchanged unless the new view structure needs small status-render support changes.
- Modify: `tests/popup-entry.test.ts`
  - Update popup rendering expectations for the redesigned layout.

### Task 1: Lock the desired popup structure in tests

**Files:**
- Modify: `tests/popup-entry.test.ts`

- [ ] **Step 1: Write the failing layout assertions**

Update the logged-in and update-available popup tests to assert the new structure exists. Add checks for:

- a compact product header
- an account card/root section
- an update card/root section
- a primary update button and secondary guide button

Use selectors that match the intended new DOM shape, for example:

```ts
expect(
  dom.window.document.querySelector('[data-popup-account="card"]')
).not.toBeNull();
expect(
  dom.window.document.querySelector('[data-popup-update="card"]')
).not.toBeNull();
```

- [ ] **Step 2: Run the focused popup test**

Run:

```bash
npm test -- tests/popup-entry.test.ts
```

Expected: FAIL because the current popup view does not expose the new grouped structure.

### Task 2: Redesign the logged-in popup shell

**Files:**
- Modify: `src/popup/view.ts`
- Modify: `src/popup/index.html`

- [ ] **Step 1: Implement the grouped popup shell**

Change the logged-in renderer so it produces:

- a compact header
- an account card
- an update card container
- a low-emphasis footer action area

Keep the same text content, just reorganized.

- [ ] **Step 2: Add popup CSS**

Add scoped CSS in `src/popup/index.html` for:

- wider popup body
- neutral background
- white cards
- consistent spacing
- smaller title scale
- primary / secondary / tertiary button styles

Do not add animation-heavy or branding-heavy styles.

- [ ] **Step 3: Re-run popup tests**

Run:

```bash
npm test -- tests/popup-entry.test.ts
```

Expected: PASS for structure-related checks, with any remaining failures isolated to update-state details.

### Task 3: Redesign update-state rendering

**Files:**
- Modify: `src/popup/view.ts`
- Modify: `src/popup/index.ts` (only if required)

- [ ] **Step 1: Write or update state-specific assertions**

Ensure tests cover:

- `checking` state shows a compact progress line
- `latest` state hides download actions
- `available` state shows current version, latest version, notes, and action buttons
- `error` state renders a readable warning block

- [ ] **Step 2: Run the focused tests**

Run:

```bash
npm test -- tests/popup-entry.test.ts
```

Expected: FAIL on any states not yet aligned to the new view.

- [ ] **Step 3: Implement state-specific card rendering**

Refactor `renderUpdateStatus()` to keep one card shell and swap state bodies inside it. Make the available-update state visually prominent but restrained.

- [ ] **Step 4: Verify**

Run:

```bash
npm test -- tests/popup-entry.test.ts tests/update-check.test.ts
```

Expected: PASS.

### Task 4: Verify the popup still works end-to-end

**Files:**
- Modify: `src/popup/view.ts` if polish is needed
- Modify: `src/popup/index.html` if polish is needed

- [ ] **Step 1: Build the release popup**

Run:

```bash
npm run build:release
```

Expected: PASS and updated popup assets written to `dist/`.

- [ ] **Step 2: Run the full test suite**

Run:

```bash
npm test
```

Expected: PASS.

- [ ] **Step 3: Manual smoke check**

Open the unpacked extension popup from `dist/` and confirm:

- title no longer wraps into a giant stacked block
- account status is easy to scan
- update information reads clearly
- buttons are visually distinct and not cramped

- [ ] **Step 4: Commit**

```bash
git add src/popup/view.ts src/popup/index.html src/popup/index.ts tests/popup-entry.test.ts
git commit -m "feat: redesign popup update panel"
```