# COS Extension Update Design

## Goal

Use COS as the release source for extension updates. When the popup opens, it checks a public `latest.json` on COS. If the COS version is newer than the installed extension version, the popup shows an update card with download actions for the ZIP and the PDF guide, plus manual reload instructions.

## Confirmed Scope

- Update prompt appears only in the extension popup.
- No star chart page banner in this change.
- The user keeps the current manual install flow: download, unzip, replace the folder, then reload in `chrome://extensions`.

## Reusable Implementation

The current repo already has most of the flow:

- `src/shared/update-check.ts` parses the manifest and compares versions.
- `src/popup/index.ts` checks for updates when the popup boots.
- `src/popup/view.ts` renders the update status and download actions.
- `src/background/index.ts` downloads the ZIP/PDF through `chrome.downloads`.
- `scripts/write-latest-manifest.mjs` generates `release/latest.json`.

This change is mostly activation and configuration, not a rewrite.

## Manifest Contract

The public COS manifest must keep these fields:

- `latestVersion`
- `minSupportedVersion`
- `publishedAt`
- `releaseNotes`
- `zipUrl`
- `guideUrl`

Rules:

- All asset URLs must be public HTTPS URLs.
- Version comparison stays numeric dotted comparison.
- Popup logic only needs `latestVersion` to decide whether to show the update card.
- `minSupportedVersion` stays in the manifest for forward compatibility.

## COS Layout

Use a fixed release layout like:

- `https://<cos-domain>/star-chart-search-enhancer/releases/<version>/latest.json`
- `https://<cos-domain>/star-chart-search-enhancer/releases/<version>/star-chart-search-enhancer-internal.zip`
- `https://<cos-domain>/star-chart-search-enhancer/releases/<version>/星图增强插件-超简单安装使用指南.pdf`

## User Flow

1. User opens the popup.
2. Popup reads the current extension version.
3. Popup fetches COS `latest.json` with `no-store`.
4. If `latestVersion` is not newer, show “当前已是最新版本”.
5. If `latestVersion` is newer, show “发现新版本” plus release notes.
6. User clicks:
   - `下载更新包` for the ZIP
   - `下载使用说明` for the PDF
7. Popup shows the manual upgrade instructions after download starts.

## Error Handling

- If the manifest is missing, invalid, or unreachable, the popup should show a non-blocking update error.
- If download fails, the popup should show a download error and keep the plugin usable.
- Update check failures must not block auth or normal plugin behavior.

## Release Process

1. Build the release package.
2. Package the internal ZIP.
3. Generate `latest.json` with the real COS base URL.
4. Upload `latest.json`, the ZIP, and the PDF to the COS folder.
5. Replace the placeholder manifest URL in `src/shared/update-config.ts`.
6. Rebuild and verify the popup update card.

## Out of Scope

- Automatic in-place extension updates.
- Auto-reload after download.
- Star chart page update prompts.
- Chrome Web Store publishing.