feat(review): add review.visual.themes config for dark-mode capture

[JSONbored]

Summary

• Adds review.visual.themes: string[] to the manifest schema (focus-manifest.ts), validated against light | dark, following the same list-parsing idiom as review.visual.routes.paths (dedupe, cap, warn-and-drop invalid entries).
• captureShot (shot.ts) accepts an optional theme and calls page.emulateMediaFeatures([{ name: "prefers-color-scheme", value: theme }]) before navigation. handleShot's on-demand render mode also reads/validates a &theme= query param end to end.
• buildCapture resolves the configured theme list (default → single untagged capture, byte-identical to today) and produces one CaptureRoute per (route, theme) pair, reusing the existing per-viewport capture/diff logic inside an outer theme loop. Cache-key fingerprints and on-demand shot URLs include the theme so light/dark never collide.
• unified-comment-bridge.ts's "Visual preview" table shows the theme in the viewport label when set (e.g. desktop (dark)), unchanged when absent.
• Docs: .gittensory.yml.example and config/examples/gittensory.full.yml both document the new themes: block (kept byte-identical per config-templates.test.ts).

Part of #3607. Closes #3678.

Scope

• src/signals/focus-manifest.ts — VisualTheme type, parseVisualThemes, schema wiring, JSON round-trip.
• src/review/visual/shot.ts — ShotTheme, emulateMediaFeatures call, handleShot's &theme= param.
• src/review/visual/capture.ts — theme loop in buildCapture, theme-aware cache keys + on-demand URLs.
• src/review/unified-comment-bridge.ts — theme label in the Visual preview table.
• .gittensory.yml.example, config/examples/gittensory.full.yml — matching documentation.
• Tests: focus-manifest.test.ts, signals-coverage.test.ts, visual-config-wiring.test.ts, visual-capture.test.ts, visual-collapsible.test.ts, visual-shot.test.ts.

Validation

• npx tsc --noEmit clean.
• Full local suite: 495 files, 9979 passed / 7 skipped, 0 failed (npx vitest run).
• git diff --check clean (no whitespace conflict markers).
• npm audit --audit-level=moderate — 0 vulnerabilities.
• Real browser verification (Docker browserless/chromium + puppeteer-core): confirmed emulateMediaFeatures with light produces byte-identical output to no emulation, and dark produces a genuinely different render — not just a different tag on the same image.
• No API/schema, wrangler binding, or DB migration changes in this PR — ui:openapi/cf-typegen/migrations not applicable.

Safety

• Default (no review.visual.themes configured) is byte-identical to pre-feat(review): add review.visual.themes config for dark-mode capture #3678 behavior: a single untagged capture, no emulateMediaFeatures call, no &theme= in on-demand URLs. Verified by dedicated tests in each touched file.
• No secrets, wallets, hotkeys, trust scores, or reward values touched.
• Stays within wantedPaths; does not touch site/, CNAME, or **/lovable/**.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.34%. Comparing base (ddf68c3) to head (8266ff4).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3680   +/-   ##
=======================================
  Coverage   93.34%   93.34%           
=======================================
  Files         315      315           
  Lines       32107    32129   +22     
  Branches    11769    11780   +11     
=======================================
+ Hits        29969    29991   +22     
  Misses       1507     1507           
  Partials      631      631           

Files with missing lines	Coverage Δ
src/review/unified-comment-bridge.ts	99.35% <100.00%> (+<0.01%)	⬆️
src/review/visual/capture.ts	87.00% <100.00%> (+0.40%)	⬆️
src/review/visual/shot.ts	83.72% <100.00%> (+0.58%)	⬆️
src/signals/focus-manifest.ts	99.05% <100.00%> (+0.01%)	⬆️

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-06 02:55:37 UTC}

12 files · 1 AI reviewer · no blockers · readiness 82/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR adds an opt-in `review.visual.themes` config that drives a theme-tagged capture matrix (per route × theme) through capture.ts, shot.ts, focus-manifest.ts, and the unified comment table. The default-path byte-identity claim holds up: `themes` defaults to `[undefined]`, `capturePage`/`captureShot`/cache-fingerprint/on-demand-URL logic all gate the theme insertion behind a truthy check, and the diff/collapsible label only appends `(theme)` when `route.theme` is set. Validation (enum-restricted parse with dedupe/warn-and-drop) mirrors the existing `routes.paths` idiom, and tests cover both the untagged default and the themed matrix end to end, including cache-key/fingerprint non-collision.

Nits — 6 non-blocking

• src/review/visual/capture.ts: enabling both themes multiplies capture work 2x (4 viewports x 2 themes = 8 renders per route); worth a one-line comment near the `themes` loop noting this is bounded by the 2-value enum so it can't runaway, similar to the existing MAX_ROUTES rationale.
• src/signals/focus-manifest.ts parseVisualThemes: the cast `entry.trim().toLowerCase() as VisualTheme` happens before the enum check — harmless since the `includes` guard catches bad values, but consider validating before casting for clarity.
• codecov/patch is at 97.72% vs the 99% target; worth checking which changed branch is uncovered (likely an edge case in the on-demand `&theme=` parsing or the diff-fingerprint theme suffix) before merge, even though CI status itself isn't a code defect.
• Consider naming the `feat(review): add review.visual.themes config for dark-mode capture #3678`/`feat(review): wire up existing pixel-diff into a 'Diff' column (self-host) #3674` issue-reference literals in unified-comment-bridge.ts as a shared constant or just a doc comment convention, per the external brief's magic-number note — purely cosmetic.
• src/review/visual/capture.ts: the `themes` loop iterates routes inside themes (theme outer, path inner) — confirm this ordering doesn't change route array ordering assumptions relied on elsewhere (e.g. `MAX_ROUTES` slicing happens before this loop per the diff, so should be fine, but worth a quick double-check).
• PR author also opened the linked issue — Link an issue that was opened by a different contributor, or provide a rationale for why this self-authored issue represents genuine discovery work.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#3678
Related work	⚠️ 3 scoped overlaps	Top overlaps are listed below; lower-confidence bulk is hidden.
Change scope	❌ 8/20	High review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 55 registered-repo PR(s), 47 merged, 456 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 55 PR(s), 456 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: Python, TypeScript, JavaScript, Ruby, Go, Kotlin, MDX, Shell
• Official Gittensor activity: 55 PR(s), 456 issue(s).
• Related work: Items reference the same linked issue feat(review): add review.visual.themes config for dark-mode capture #3678. (issue #3678)
• Related work: Open PR work references issue feat(review): add review.visual.themes config for dark-mode capture #3678. (issue #3678)
• Related work: Titles/paths share 8 meaningful terms. (issue #2189, issue #2184)
• Additional title-only matches omitted; title-only overlap does not block.

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.
• Review top overlaps.
• Add a concise scope and risk note.
• No action.
• Check active issues and PRs before submitting.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review