feat: improve package search relevance and document remaining backlog

[solrevdev]

Summary

Implements the first low-risk batch from IMPROVEMENTS.md to improve package discoverability/performance in the frontend, and adds explicit backlog tracking so another LLM can continue this branch safely.

Current Branch Status

• Branch: codex/frontend-search-improvements
• Head commit: 70157c5725c3
• Base branch: master
• Clean tracking status at handoff: codex/frontend-search-improvements...origin/codex/frontend-search-improvements

Completed Improvements (This PR)

• #1 Regex-safe highlighting (no RegExp crash on special chars)
• #5 Minified packages.json output in extractor
• #6 Weighted/ranked search scoring
• #7 shortDescription fallback in result rendering
• #8 Incremental rendering with Load more
• #9 URL query-state support (?q=) + back/forward restore
• #10 Homepage + license rendering in result cards
• #11 Click-to-filter publisher/tag
• #26 Remove dead code/import in extractor

Files Changed

• index.html
• extract_packages.py
• IMPROVEMENTS.md

Production Backup Snapshots Created

Before continuing development work, backup branches were created from remote production refs:

• backups/master from origin/master
• backups/gh-pages from origin/gh-pages

SHA verification:

• origin/master: 844252e5ea43e57950518297474b3b465f371149
• origin/backups/master: 844252e5ea43e57950518297474b3b465f371149 ✅
• origin/gh-pages: 2f853604f655a74a4d185a590864ae09ca991f78
• origin/backups/gh-pages: 2f853604f655a74a4d185a590864ae09ca991f78 ✅

Local Validation Performed

Static checks:

• python3 -m py_compile extract_packages.py
• node --check on extracted inline JS from index.html

UI behaviour validation:

• Local server run on port 8000 (python3 -m http.server 8000)
• Requested pages:
  • http://127.0.0.1:8000/ -> 200
  • http://127.0.0.1:8000/?q=chrome -> 200
• Executed deterministic JS harness (/tmp/step5_ui_check.js) with result STEP5_UI_VALIDATION=PASS, covering:
  • ranking expectations (exact ID > weaker matches)
  • regex-safe highlight cases ((test, a.b, foo+bar)
  • URL query state + popstate restore
  • license badge + homepage link + description fallback
  • click filtering via filterBy
  • incremental rendering via Load more

Workflow / Safety Notes

• No merge was performed.
• master and gh-pages were not modified.
• Build workflow push trigger is scoped to main/master; feature branch push does not auto-trigger it.
• Commit includes [skip ci] as an extra guard.

Handoff State For Next LLM

Backlog status and recommended order are maintained in:

• IMPROVEMENTS.md -> Branch Progress Update (2026-02-26)

Next recommended low-risk batch:

1. #3 Replace placeholder repo URL in footer
2. #4 Fix duplicate/malformed README summary block
3. #22 Resolve README license filename mismatch
4. #2, #20, #19, #21 workflow reliability fixes

How To Continue Safely

1. Keep working on codex/frontend-search-improvements.
2. Make small conventional commits per batch.
3. Update the Branch Progress section in IMPROVEMENTS.md after each batch.
4. Re-run local validation before each push.

Important Merge Caveat ([skip ci])

This branch contains a commit message with [skip ci].

When merging to master, ensure the final pushed commit message to the base branch does not include [skip ci], otherwise GitHub Actions may skip the Build and Deploy workflow and GitHub Pages may not rebuild automatically.

Safe options:

1. Use Merge commit or Squash and merge with a merge message that does not contain [skip ci].
2. If CI is skipped or uncertain, manually run Build and Deploy via workflow_dispatch.
3. If needed, run the manual Trigger Pages Deploy workflow.

Codex Environment Note (Playwright)

playwright-cli works for this project, but in the Codex app it may require elevated execution for:

• local server bind/connect (http://127.0.0.1:8000), and
• Playwright cache/session writes under user library/cache paths.

If non-elevated Playwright fails with permissions/network errors in Codex, rerun the same Playwright command with escalation.
This is an environment/sandbox behavior, not a requirement to switch to gh-pages or run Jekyll.