star-chart-search-enhancer/docs/superpowers/plans/2026-04-15-star-chart-market-visible-page-columns-implementation.md

# Star Chart Market Visible Page Columns 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:** Add two after-search-rate columns to the Xingtu creator market list page, auto-load them for the current visible result page, and support cache-backed retryable row rendering without regressing the existing detail-page experiment.

**Architecture:** Keep the existing detail-page hook flow intact, split the content entry into route-aware controllers, and implement the market-page feature entirely inside `src/content/market/`. Market-page data loading uses a dedicated same-origin API client plus a list-sequence-aware controller so DOM sync, cache reuse, retry, and stale-result suppression stay deterministic and testable.

**Tech Stack:** TypeScript, Vitest, jsdom, tsup, Chrome Extension Manifest V3

---

## Implementation Notes

- Current workspace already contains working detail-page code, build scripts, and tests. This plan assumes incremental change, not greenfield scaffolding.
- Current workspace is still not a git repository, so each “commit” step is replaced with a verification note.
- This plan only covers stage 1: current visible result page enhancement.
- Follow TDD strictly: failing test first, then minimal code.
- Do not route the market-page feature through `src/page/hook.ts` unless runtime evidence proves content-script requests are blocked.
- Market async flows must not cache raw `HTMLElement` references across request boundaries. Cache/request layers may store only row metadata such as `authorId`, `listSeq`, and list signature.
- The market API client should expose deterministic error reasons: `timeout` for `AbortError`, `request-failed` for network/non-2xx/parse failures, and `bad-response` for structurally valid responses missing either target field.
- Every async writeback must re-check current DOM markers (`data-sces-author-id`, `data-sces-list-seq`) before rendering, instead of trusting a stale row reference captured earlier.

## Planned File Map

- Modify: `src/manifest.json`
  - Add market-page match coverage while preserving detail-page coverage.
- Modify: `src/content/index.ts`
  - Reduce to route bootstrap and controller selection.
- Create: `src/content/detail/index.ts`
  - Hold the existing detail-page controller logic currently living in `src/content/index.ts`.
- Create: `src/content/market/index.ts`
  - Orchestrate market-page DOM sync, list sessions, loading, cache reuse, and retry.
- Create: `src/content/market/api-client.ts`
  - Build request URLs, issue same-origin fetches with timeout, and map the known API response into normalized rates.
- Create: `src/content/market/batch-loader.ts`
  - Coordinate concurrency-limited loading, stale-result suppression, and row-level retry.
- Create: `src/content/market/cache-store.ts`
  - Store success cache and in-flight request dedupe entries by `authorId`.
- Create: `src/content/market/dom-sync.ts`
  - Find the target table, insert headers/cells, and bind row metadata markers.
- Create: `src/content/market/id-extractor.ts`
  - Extract `authorId` from row links and fallback attributes.
- Create: `src/content/market/list-signature.ts`
  - Produce deterministic list/session signatures from current rows and URL state.
- Create: `src/content/market/row-render.ts`
  - Render loading, success, and error states into the two injected cells.
- Create: `src/content/market/row-state.ts`
  - Define row-status types and transition helpers.
- Create: `src/shared/normalize-rate-value.ts`
  - Normalize known rate shapes such as `<0.02%` and `0.02 - 0.1%`.
- Modify: `src/shared/extract-after-search-rates.ts`
  - Reuse the extracted shared normalizer so detail-page behavior stays consistent.
- Modify: `tests/build-layout.test.ts`
  - Extend manifest/build assertions for the market route.
- Modify: `tests/content-bridge.test.ts`
  - Point detail-page tests at the extracted detail controller module.
- Create: `tests/content-entry.test.ts`
  - Cover route bootstrap behavior for detail, market, and unsupported URLs.
- Create: `tests/market-api-client.test.ts`
  - Cover request URL generation, timeout handling, and response mapping.
- Create: `tests/market-id-extractor.test.ts`
  - Cover author-id extraction from row fixtures.
- Create: `tests/market-dom-sync.test.ts`
  - Cover header/cell insertion and duplicate protection.
- Create: `tests/market-row-render.test.ts`
  - Cover row rendering transitions and retry affordance.
- Create: `tests/market-batch-loader.test.ts`
  - Cover cache reuse, in-flight dedupe, concurrency, and retry behavior.
- Create: `tests/market-controller.test.ts`
  - Cover list changes, stale-result suppression, and cache-backed rehydration.
- Modify: `tests/readme.test.ts`
  - Require README coverage for the market-page feature.
- Modify: `README.md`
  - Document market-page support and manual verification.

### Task 1: Split the Content Entry Into a Route Bootstrap and a Detail Controller

**Files:**
- Modify: `src/content/index.ts`
- Create: `src/content/detail/index.ts`
- Modify: `tests/content-bridge.test.ts`
- Create: `tests/content-entry.test.ts`

- [ ] **Step 1: Write the failing route-bootstrap tests**

Add tests asserting:
- detail URLs bootstrap the detail controller
- non-detail, non-market URLs no-op cleanly
- the detail controller still injects the page hook exactly once

- [ ] **Step 2: Run the tests to verify they fail**

Run: `npm test -- tests/content-entry.test.ts tests/content-bridge.test.ts`
Expected: FAIL because route bootstrap and extracted detail controller do not exist yet

- [ ] **Step 3: Implement the minimal route bootstrap split**

Implement:
- `createDetailContentController` in `src/content/detail/index.ts`
- route matching in `src/content/index.ts`
- no-op behavior on unsupported URLs
- updated imports in the existing detail tests

- [ ] **Step 4: Run the tests to verify they pass**

Run: `npm test -- tests/content-entry.test.ts tests/content-bridge.test.ts`
Expected: PASS

- [ ] **Step 5: Record the verification note**

Record which tests passed and that detail-page behavior remained intact

### Task 2: Extend Manifest Coverage to the Market Page

**Files:**
- Modify: `src/manifest.json`
- Modify: `tests/build-layout.test.ts`

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

Extend the build-layout test to assert:
- the content script matches both detail and market URLs
- the emitted JS asset list is unchanged
- `web_accessible_resources` for the detail hook still stay present

- [ ] **Step 2: Run the test to verify it fails**

Run: `npm test -- tests/build-layout.test.ts`
Expected: FAIL because the manifest only targets the detail page

- [ ] **Step 3: Implement the minimal manifest update**

Implement:
- add `https://*.xingtu.cn/ad/creator/market*` to `content_scripts.matches`
- keep existing detail-page matches and page-hook asset coverage

- [ ] **Step 4: Run the test to verify it passes**

Run: `npm test -- tests/build-layout.test.ts`
Expected: PASS

- [ ] **Step 5: Verify the build still works**

Run: `npm run build`
Expected: PASS and `dist/manifest.json` includes the market match

- [ ] **Step 6: Record the verification note**

Record the passing build-layout test and build output

### Task 3: Add the Shared Rate Normalizer and the Market API Client

**Files:**
- Create: `src/shared/normalize-rate-value.ts`
- Modify: `src/shared/extract-after-search-rates.ts`
- Create: `src/content/market/api-client.ts`
- Create: `tests/market-api-client.test.ts`
- Modify: `tests/extract-after-search-rates.test.ts`

- [ ] **Step 1: Write the failing API-client and normalization tests**

Cover:
- normalizing `<0.02%` without changing it
- normalizing `0.02 - 0.1%` into `0.02% - 0.1%`
- mapping the known API fields into the two display fields
- returning `bad-response` when either field is missing
- returning `timeout` for aborted requests and `request-failed` for non-OK/network failures
- issuing fetch with `credentials: "include"` and a timeout signal

- [ ] **Step 2: Run the tests to verify they fail**

Run: `npm test -- tests/market-api-client.test.ts tests/extract-after-search-rates.test.ts`
Expected: FAIL because the shared normalizer and market API client do not exist yet

- [ ] **Step 3: Implement the minimal shared normalizer and API client**

Implement:
- `normalizeRateValue`
- market request URL builder for `get_author_ase_info`
- response mapper for `avg_search_after_view_rate` and `personal_avg_search_after_view_rate`
- explicit error classification for timeout vs request-failed vs bad-response
- reuse the shared normalizer from the detail extractor

- [ ] **Step 4: Run the tests to verify they pass**

Run: `npm test -- tests/market-api-client.test.ts tests/extract-after-search-rates.test.ts`
Expected: PASS

- [ ] **Step 5: Record the verification note**

Record that both the new market mapper tests and the existing detail extractor tests passed

### Task 4: Add Author-ID Extraction and List-Signature Utilities

**Files:**
- Create: `src/content/market/id-extractor.ts`
- Create: `src/content/market/list-signature.ts`
- Create: `tests/market-id-extractor.test.ts`

- [ ] **Step 1: Write the failing extractor tests**

Cover:
- extracting `authorId` from a row detail link
- extracting from fallback row attributes when available
- returning an explicit missing-id result when no stable source exists
- producing a deterministic list signature from author IDs plus relevant URL state

- [ ] **Step 2: Run the test to verify it fails**

Run: `npm test -- tests/market-id-extractor.test.ts`
Expected: FAIL because the market row extraction utilities do not exist yet

- [ ] **Step 3: Implement the minimal extractor utilities**

Implement:
- detail-link parsing via `getStarIdFromUrl`
- fallback attribute parsing
- explicit `missing-author-id` results
- deterministic list-signature generation

- [ ] **Step 4: Run the test to verify it passes**

Run: `npm test -- tests/market-id-extractor.test.ts tests/get-star-id.test.ts`
Expected: PASS

- [ ] **Step 5: Record the verification note**

Record the passing extractor and shared ID tests

### Task 5: Insert the Two Columns and Render Row States

**Files:**
- Create: `src/content/market/dom-sync.ts`
- Create: `src/content/market/row-render.ts`
- Create: `src/content/market/row-state.ts`
- Create: `tests/market-dom-sync.test.ts`
- Create: `tests/market-row-render.test.ts`

- [ ] **Step 1: Write the failing DOM and rendering tests**

Cover:
- inserting two headers before the `操作` column
- inserting two cells before the action cell for each row
- tagging injected cells with stable `data-*` markers
- avoiding duplicate insertion on repeated sync
- rendering `加载中...`, success values, and `加载失败`
- exposing retryable error rows without creating per-cell state divergence
- avoiding any design that requires batch/cache layers to hold row elements after the sync pass ends

- [ ] **Step 2: Run the tests to verify they fail**

Run: `npm test -- tests/market-dom-sync.test.ts tests/market-row-render.test.ts`
Expected: FAIL because the market DOM modules do not exist yet

- [ ] **Step 3: Implement the minimal DOM sync and row rendering**

Implement:
- table/header lookup
- injected header/cell creation
- row-state types
- row rendering with shared row-level status
- ephemeral DOM references only inside the sync/render step

- [ ] **Step 4: Run the tests to verify they pass**

Run: `npm test -- tests/market-dom-sync.test.ts tests/market-row-render.test.ts`
Expected: PASS

- [ ] **Step 5: Record the verification note**

Record the passing DOM and row-render test output

### Task 6: Add Cache, In-Flight Dedupe, Concurrency Control, and Row Retry

**Files:**
- Create: `src/content/market/batch-loader.ts`
- Create: `src/content/market/cache-store.ts`
- Create: `tests/market-batch-loader.test.ts`
- Modify: `src/content/market/api-client.ts`
- Modify: `src/content/market/row-state.ts`

- [ ] **Step 1: Write the failing batch-loader tests**

Cover:
- current page rows auto-enter loading state
- same `authorId` reuses success cache
- same `authorId` in-flight requests are deduplicated
- concurrency cap is honored
- failed rows transition to `加载失败`
- clicking one failed cell retries the whole row
- loader outputs can be dropped safely when the consumer reports a newer `listSeq`

- [ ] **Step 2: Run the test to verify it fails**

Run: `npm test -- tests/market-batch-loader.test.ts`
Expected: FAIL because cache/dedupe/loader behavior does not exist yet

- [ ] **Step 3: Implement the minimal cache and loader pipeline**

Implement:
- in-memory cache entries keyed by `authorId`
- in-flight request reuse
- concurrency-limited scheduling
- row retry behavior
- timeout and request-failed transitions
- result delivery based on row metadata and callbacks, not long-lived DOM node ownership

- [ ] **Step 4: Run the test to verify it passes**

Run: `npm test -- tests/market-batch-loader.test.ts tests/market-api-client.test.ts`
Expected: PASS

- [ ] **Step 5: Record the verification note**

Record the passing loader and API-client tests

### Task 7: Build the Market Controller and Activate It on the Market Route

**Files:**
- Create: `src/content/market/index.ts`
- Modify: `src/content/index.ts`
- Create: `tests/market-controller.test.ts`
- Modify: `tests/content-entry.test.ts`

- [ ] **Step 1: Write the failing controller tests**

Cover:
- initial market page auto-load for all current rows
- pagination/filter/search/sort DOM changes trigger a fresh sync
- stale async results do not overwrite a newer list
- cached rows rehydrate immediately when they reappear
- the content entry now selects the market controller on market URLs
- writeback only succeeds when fresh DOM markers still match the returning `authorId` and `listSeq`

- [ ] **Step 2: Run the test to verify it fails**

Run: `npm test -- tests/market-controller.test.ts tests/content-entry.test.ts`
Expected: FAIL because the market controller and route activation do not exist yet

- [ ] **Step 3: Implement the minimal market controller**

Implement:
- table observation
- `listSeq` or equivalent sync-session tracking
- fresh sync on list changes
- stale result suppression before DOM writeback
- re-scan current DOM on each sync instead of holding old row node references
- market route activation in `src/content/index.ts`

- [ ] **Step 4: Run the test to verify it passes**

Run: `npm test -- tests/market-controller.test.ts tests/content-entry.test.ts`
Expected: PASS

- [ ] **Step 5: Run the focused market suite**

Run: `npm test -- tests/market-api-client.test.ts tests/market-id-extractor.test.ts tests/market-dom-sync.test.ts tests/market-row-render.test.ts tests/market-batch-loader.test.ts tests/market-controller.test.ts`
Expected: PASS

- [ ] **Step 6: Record the verification note**

Record that the market suite and route-entry tests passed

### Task 8: Update README and Run Final Verification

**Files:**
- Modify: `README.md`
- Modify: `tests/readme.test.ts`

- [ ] **Step 1: Write the failing README expectation**

Extend README tests to assert documentation now includes:
- market page enhancement scope
- the two inserted column names
- loading/failure/retry behavior
- how to manually verify on `creator/market`
- the fact that detail-page behavior still exists

- [ ] **Step 2: Run the test to verify it fails**

Run: `npm test -- tests/readme.test.ts`
Expected: FAIL because README does not document market-page behavior yet

- [ ] **Step 3: Update README minimally**

Add:
- market page support notes
- manual verification steps for both detail and market pages
- current stage-1 limitations

- [ ] **Step 4: Run the test to verify it passes**

Run: `npm test -- tests/readme.test.ts`
Expected: PASS

- [ ] **Step 5: Run the full verification suite**

Run: `npm test`
Expected: all tests PASS

- [ ] **Step 6: Run a fresh production build**

Run: `npm run build`
Expected: build exits 0 and `dist/` contains the updated extension assets

- [ ] **Step 7: Record the verification note**

Record the passing full test run and build output

---

## Runtime DOM Note

After testing against the real logged-in `creator/market` page, the market result area was confirmed to be a column-major sticky grid instead of a row-major HTML table:

- outer list root: `.base-author-list`
- header root: `.section-wrapper.sticky-header.hide-scrollbar`
- body root: `.section-wrapper.hide-scrollbar`
- left author area: sticky `content-section` with one `content-column`
- middle metrics: `.middle-columns`
- right sticky area: `content-section` containing multiple `.content-column`s, with the last column being `操作`

This means DOM sync cannot treat each result as a `<tr>` or assume the injected cells live under the same row container. The implementation now reconstructs each logical row by cell index across columns and stamps row metadata onto:

- the author-side row anchor cell
- the injected `单视频看后搜率` cell
- the injected `个人视频看后搜率` cell

## Verification Note

Verified in this workspace after the column-major DOM fix:

- `npm test -- tests/market-dom-sync.test.ts tests/market-controller.test.ts`
- `npm test`
- `npm run build`

All commands exited successfully.

## Runtime Stability Note

After manual browser verification on the real `creator/market` page, an additional runtime issue was identified: refreshing the market page could leave the result area blank or stuck loading.

The market controller was then hardened with three runtime constraints:

- do not start observing the full market DOM while `document.readyState === "loading"`
- do not override `history.pushState` or `history.replaceState` on the market page
- coalesce repeated `MutationObserver` callbacks into one scheduled sync cycle instead of launching unbounded concurrent sync passes during page boot

These constraints are now covered by `tests/market-controller.test.ts` together with the existing market-page behavior checks.