star-chart-search-enhancer/docs/superpowers/plans/2026-05-25-popup-update-panel.md

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:

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:

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:

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:

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:

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:

npm run build:release

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

• Step 2: Run the full test suite

Run:

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

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"