[web-ext]: add-audio-mode-and-revamp-popup-and-options by DarhkVoyd · Pull Request #79 · enrych/toppings

DarhkVoyd · 2026-05-14T16:20:24Z

What does this PR do?

This PR introduces Audio Mode for the YouTube watch page, then revamps the popup and options page on top of a new shared component library and theme system.

Audio Mode: a player button + B shortcut that hides the video and plays audio-only, with three screen modes (Black, Visualizer, Custom Image). Includes a full custom UI overlay with title, channel, play/pause, progress bar, volume, mode switcher, per-video pin, and explicit close button. Persists across SPA navigation. Per-video pins stored in chrome.storage.local. Visualizer sensitivity is configurable. Auto-disables during ads.
Options page revamp: hybrid sidebar layout with anchored section navigation, confirm modals, toast notifications, file picker with thumbnail preview, custom dropdown, and a visualizer-sensitivity slider.
Popup revamp: replaces the old welcome screen with a real dashboard — master toggle, at-a-glance stats, feature list, "What's New", and footer actions. Deep-links into specific options routes via chrome.storage.local.
Theme system: semantic CSS variable tokens (System / Dark / Light), live system follow via prefers-color-scheme.
Shared component library moved from options/ to src/shared/ so popup, options, and any future surface share primitives, form, feedback (Popup → ActionPopup → ConfirmPopup), layout, hooks, and utils.
Features registry (src/shared/features.ts) is a single source of truth for feature metadata + "What's New" feed; popup renders from it.
Maintainer docs (web-ext/CLAUDE.md) document the new layout, theming, features-registry contract, and storage split.

Why is this change necessary?

The original popup was a static welcome screen; the options page was a single monolithic file with hardcoded colors and limited components, and the watch page had no audio-only mode for users who want to listen without the visuals (office use, multitasking, NSFW visuals, etc.).

Putting popup + options on a shared, themable foundation also unblocks future surfaces — every primitive (Popup → ActionPopup → ConfirmPopup, Toast + useToast(), ConfirmProvider + useConfirm(), Select, Slider, FilePicker, etc.) is now reusable, and adding a feature requires only an entry in src/shared/features.ts for it to appear in the popup.

How was this change implemented?

Audio Mode (web-ext/src/content_scripts/components/AudioMode/)
- CSS overlay inside #movie_player at z-[9000+], with a class on the player that hides YouTube's chrome (.ytp-chrome-bottom, gradients, end-screen cards) via web-ext/src/content_scripts/index.css while active.
- Audio routing: createMediaElementSource(video) reroutes audio through Web Audio. Keep source → destination connected at all times so audio plays in every screen mode; the analyser is an optional side-branch attached only when the visualizer runs.
- Visualizer uses a peak-of-low-spectrum loudness signal with a sqrt perceptual curve and a configurable sensitivity multiplier.
- User intent (userWantsAudioMode) persists across SPA navigations; per-video pins override.
- chrome.storage.sync for preferences, chrome.storage.local for per-video pins and uploaded background images (which exceed sync's 8KB per-item cap).
Theme tokens (web-ext/src/shared/theme.css)
- Semantic CSS variables (--color-bg, --color-surface, --color-fg, --color-accent, plus tonal pairs for success/info/warning/danger).
- Tailwind config in web-ext/scripts/build.js exposes them as semantic utilities (tw-bg-surface, tw-text-fg, etc.).
- useTheme() resolves the user's preference and writes data-theme on <html>; re-applies on OS preference changes when "system" is selected.
Shared library (web-ext/src/shared/)
- Moved from options/components/ and reorganized into primitives/, form/, feedback/, layout/, hooks/, utils/.
- Form components compose a single Field wrapper for consistent label/description/error layout.
- Feedback components form a composition chain: Popup (portal + focus trap + backdrop) → ActionPopup (title + body + footer actions) → ConfirmPopup (configures actions for the confirm pattern) → useConfirm() for an imperative await confirm({…}) API.
Options page (web-ext/src/options/)
- Sidebar with iconified routes, collapsible to a 60px icon-only mode (state persisted in chrome.storage.local).
- Right-rail SectionNav uses IntersectionObserver to highlight the section in view; sticky positioning required removing overflow-x-hidden from <main> (any non-visible overflow ancestor silently becomes the sticky's scroll container).
- Migration: getStorage() deep-merges DEFAULT_STORE into existing chrome.storage.sync data so installs get new keys (audio mode, theme, visualizer sensitivity) without manual migration.
Popup (web-ext/src/popup/)
- New 360×520 dashboard built entirely from shared components.
- Deep-links into options routes by writing options_pending_route to chrome.storage.local; options/App.tsx reads and consumes it on mount.
Features registry (web-ext/src/shared/features.ts)
- FEATURES and WHATS_NEW arrays with a maintainer-rules header. Popup renders from this; future surfaces (search, onboarding) can too.

Screenshots / Visual Changes

NA (please grab while testing — the diff is large enough that screenshots would be helpful in the PR description before merging).

Related Issues

NA

Additional Considerations

Storage migration is automatic. The deep-merge in getStorage() (web-ext/src/background/store.ts) means existing users won't lose their settings or hit "undefined" errors when the new keys (ui.theme, audioMode.*, audioMode.visualizerSensitivity) appear. The strategy is recursive merge of defaults into stored data with stored values taking precedence.
Web Audio caveat: createMediaElementSource(video) permanently reroutes the video's audio through AudioContext. Once attached, audio plays only if source → destination is connected. We keep that connection at all times and treat the analyser as an optional branch — switching out of visualizer mode no longer kills audio (this was an early bug that the new structure prevents).
Tailwind config change in web-ext/scripts/build.js: added darkMode: ["class", '[data-theme="dark"]'] and a theme.extend.colors block that maps semantic names to the CSS variables. No effect on production behavior, but reviewers should be aware.
Maintainer contract: web-ext/CLAUDE.md and the header of web-ext/src/shared/features.ts both document that any new user-facing feature should be added to FEATURES (and WHATS_NEW) so the popup picks it up automatically.
Old files removed: options/components/{Card,Input,Keybinding,Navbar,Switch,Tooltip}.tsx and popup/components/Navbar.tsx are deleted in favor of the shared library; the previous options/store.tsx, options/hooks/, options/utils/ moved to shared/.

🤖 Generated with Claude Code

+      if (currentCustomImageUrl) {
+        // Wrap in double quotes; CSS.escape() is for identifiers (class
+        // names/selectors) and would mangle the URL's : ; / + = characters.
+        const escapedUrl = currentCustomImageUrl.replace(/"/g, '\\"');


clean up wait wait feat: Segments — multi-segment playback sequencer (#102) Replaces the single loop-segment system with a fully extensible Segments engine. Users can define multiple time-range markers on any video and configure exactly how they play back. Core capabilities - Multiple segments per video, each shown as a colored pentagon marker pair on the YouTube progress bar - Per-segment loop count (0 = infinite) and playback rate override - Per-iteration rate overrides: [1.0, 1.5] plays 1× first, 1.5× second - Advanced Sequence editor: compose steps with any custom segment order; duplicates allowed — [seg3, seg3, seg1] plays seg3 twice then seg1 - Segment merge: hold adjacent markers within 1.5% for 500 ms → merge with pulse animation Save tiers - Last-used: auto-updated volatile slot, never requires explicit save - Default slot: one-click quick save - Named configs: unlimited, each with an optional keyboard shortcut for instant activation (e.g. Ctrl+1) Keyboard shortcuts - Z — load last-used config / toggle off (replaces toggleLoopSegment) - Shift+Z — always start a fresh slate (full video, infinite loop) - Q / E — set start / end of the active segment (one containing playhead) - Shift+Q / Shift+E — nudge with acceleration (unchanged) - Named config combos — user-assignable per saved config New modules (SOLID boundaries) - utils/segments/types.ts — data types only - utils/segments/factories.ts — pure config factory functions - utils/segments/engine.ts — playback state machine, no DOM - utils/segments/markers.tsx — DOM marker controller, N colored pairs - utils/storage/segmentStore.ts — IndexedDB CRUD + transparent migration - components/SegmentButton.tsx — control bar button - components/SegmentPanel.tsx — below-video panel (simple + advanced) - components/Segments.tsx — coordinator; public API for watch.tsx Migration Existing SavedLoopSegment records are transparently converted to a single-segment SegmentConfig on first access. IndexedDB bumped to v4 with a new `segment_data` object store. Backward compat All existing preference keys (toggleLoopSegment, setLoopSegmentBegin, setLoopSegmentEnd, nudgeLoopSegment.*) are preserved unchanged. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> segment fixes marker update changes updates

remove

+import {
+  setSidebarVisible,
+  setCommentsVisible,
+  setEndCardsVisible,
+  resetSidebar,
+  resetComments,
+  resetEndCards,
+} from "../../primitives/watch";


+      "Show or hide the right-side recommendations",
+      !sidebarEl || sidebarEl.style.display !== "none",
+      async (next) => {
+        const { setSidebarVisible, resetSidebar } = await import(


@@ -0,0 +1,249 @@
+import React, { useEffect, useState } from "react";
+import { Link } from "react-router-dom";


Colocate docs UI under app/docs, consolidate site config into constants/site.ts, flatten route data files, and remove the old website/lib layer. update

@@ -0,0 +1,27 @@
+import type { Metadata } from "next";
+import DocsPageHeader from "./components/DocsPageHeader";


… utils

…a files - Move hooks/ into core/ (useSyncStore, useLocalStorage, useCapabilityCache, useScope, useTheme) - Inline useVideoPreference into AudioMode.tsx (single caller, 3 lines) - Merge data/contract.ts + data/extension.ts into data/core.ts - Move data/extension.ts constants into core/ then into data/core.ts - Delete data/player.ts; export PlayerLayout/PlayerVisuals from data/profiles.ts - Fix stale ./contract import in data/store.ts - Rename useChromeStorageLocal → useLocalStorage, useStoreUpdater → useSyncStore

…E_IDB, consistent hooks - Centralise all chrome.storage.local keys into CHROME_STORAGE_LOCAL in data/core.ts - Add BROWSER_STORAGE_IDB to data/core.ts; drop scattered store name exports from indexedDb.ts - Rename useChromeLocal → useChromeStorageLocal, useSyncStore → useChromeStorageSync - Dissolve context/ directory; move StoreContext into core/storeContext.tsx - Fix popup/App.tsx to use getAllProfiles/getActiveProfile from core/profileStore instead of raw local reads - Replace all raw "toppings:*" string literals with CHROME_STORAGE_LOCAL constants

- CHROME_STORAGE_LOCAL → CHROME_STORAGE_LOCAL_KEY - BROWSER_STORAGE_IDB → BROWSER_STORAGE_IDB_STORE

The guard checked three conditions, two of which were unreachable: the recursion only descended into non-null plain objects, so `defaults` could never be nullish or a primitive. Recursing unconditionally lets the guard handle primitives and arrays itself, removing the duplicated type checks in the loop. Also iterate `defaults` keys instead of `stored` keys. Previously any key in storage passed through untouched, and `syncStorageWithDefaults` writes the merge back, so settings removed from DEFAULT_STORE would live in chrome.storage.sync forever. Safe here: DEFAULT_STORE is a static shape and every storage.sync.set in the repo writes that shape. Extracts isPlainObject as an exported guard and adds bun tests covering fallback, array replacement, unknown-key dropping, and type mismatches.

Root AGENTS.md now holds only what applies repo-wide and delegates project-specific rules to AGENTS/<scope>.md, so an agent reads the hub plus the one scope it touches. Previously the root carried a three-line repo layout and two sections that both said "read this file". The comment policy is the substance of this change and lives in the root so every agent reads it: code explains what and how through names and execution order, so a comment only earns its place when it answers why — a decision, constraint, or external cause the code cannot state. Applies on-touch rather than as a sweep mandate. AGENTS/web-ext.md is the first scoped file: commands, the four webpack entries, the React vs dom-chef split, the three storage layers and how mergeDefaults treats DEFAULT_STORE as schema, the MV3-to-MV2 manifest transform, and the background-dispatched navigation model.

…tions Strips comments that restate the code — section banners, JSDoc repeating the signature, and narration of the next line — from the twelve densest files. What survives is the why: YouTube DOM constraints, ordering requirements, magic-value encodings, and the reasons behind deliberate deviations. Three comments were deleted as actively wrong rather than merely redundant: - Segments.tsx claimed markers must not be rebuilt in the panel change handler while the call passes skipMarkerRebuild = false, which rebuilds them. - engine.ts documented getSegmentAt tie-breaking as nearest end time; the code compares distance to the segment midpoint. - markers.tsx carried two geometry blocks that contradicted each other, one of which also contradicted the transform it sat above. Comments dropped from key bindings ("// Z — ...") because those bindings are user-configurable and the labels are already wrong for anyone who rebound them. No behaviour change: bun run build passes at every step.

Second and final pass, covering profiles, audio mode, primitives, options routes, form components and the small utils. Same rule as the first pass: a comment stays only when it answers why — an external constraint, an ordering requirement, a magic-value encoding, or the reason a deliberate deviation exists. Notable keeps, rewritten rather than removed: the CSS.escape hazard in the audio-mode custom background, the createMediaElementSource routing constraint in the visualizer, the forced reflow in pageToast, the stuck tooltip on DOM-mutating clicks, and the search index's coupling to rendered UI text. Also drops a comment in watch.tsx claiming getAllProfiles returns only custom profiles. It returns presets plus custom, which means cycleProfilesShortcut prepends BUILT_IN_PRESETS to a list that already contains them and every preset appears twice in the cycle. The bug is left in place to be fixed on its own; only the comment hiding it is gone. web-ext comment density is now 330 of 13,256 lines (2.5%), down from 1,306 of 14,314 (9.1%). SegmentPanel.tsx, background/context.ts and utils/indexedDb.ts are untouched — they carry uncommitted work. bun run build passes; bun test utils/object.test.ts passes.

The cycle was built as [null, ...BUILT_IN_PRESETS, ...getAllProfiles()], but getAllProfiles already returns the presets followed by the custom profiles. Each preset therefore appeared twice, so the shortcut ran Default, Audio, Focus, Audio, Focus, then the user's own profiles, and two presses in a row could land on the same profile. Switches to getCustomProfiles, which returns only the user's profiles and leaves the explicit [none, presets, custom] ordering intact. Other getAllProfiles callers are unaffected: the popup, the gear menu and the native settings overlay render the returned list directly, and the options Profiles page partitions it on isPreset.

+import { withStore } from "../../../utils/indexedDb";
+import { BROWSER_STORAGE_IDB_STORE } from "../../../data/core";
+import type { VideoSegmentData, SegmentConfig, SegmentAutoLoadPin } from "./types";
+import { createFreshConfig } from "./factories";


+import { useToast } from "../../../components/feedback/ToastProvider";
+import { useCapabilityCache } from "../../../core/useCapabilityCache";
+import { setExtensionIcon } from "../../../utils/browser";
+import { ThemePreference } from "../../../core/useTheme";


+import {
+  BUILT_IN_PRESETS,
+  type Profile,
+  type ProfilePrimitiveConfig,
+  type ThumbnailMode,
+} from "../../../data/profiles";


github-advanced-security Bot found potential problems May 14, 2026

View reviewed changes

Comment thread web-ext/app/content_scripts/components/AudioMode/index.ts Fixed

github-advanced-security Bot found potential problems May 14, 2026

View reviewed changes

Comment thread web-ext/src/popup/App.tsx Fixed

github-code-quality Bot found potential problems May 14, 2026

View reviewed changes

Comment thread web-ext/src/options/routes/General.tsx Fixed

Comment thread web-ext/src/popup/App.tsx Fixed

DarhkVoyd force-pushed the claude/exciting-keller-a18866 branch from f2054cb to dfa60f6 Compare May 14, 2026 21:37

github-advanced-security Bot found potential problems May 14, 2026

View reviewed changes

Comment thread .github/workflows/consistency.yml Fixed

github-code-quality Bot found potential problems May 17, 2026

View reviewed changes

Comment thread scripts/bump-version.ts Fixed

github-code-quality Bot found potential problems May 17, 2026

View reviewed changes

Comment thread scripts/lib/releases-file.ts Fixed

github-advanced-security Bot found potential problems May 17, 2026

View reviewed changes

Comment thread web-ext/src/shared/utils/youtubeTab.ts Fixed

github-code-quality Bot found potential problems May 17, 2026

View reviewed changes

Comment thread scripts/lib/releases-file.ts Fixed

DarhkVoyd force-pushed the claude/exciting-keller-a18866 branch from d039cdb to b3e383c Compare May 17, 2026 21:32

github-advanced-security Bot found potential problems May 18, 2026

View reviewed changes

github-code-quality Bot found potential problems May 18, 2026

View reviewed changes

Comment thread web-ext/app/options/routes/General.tsx Fixed

DarhkVoyd force-pushed the claude/exciting-keller-a18866 branch from 0074568 to 3aa7a07 Compare June 21, 2026 11:48

DarhkVoyd force-pushed the claude/exciting-keller-a18866 branch from 3aa7a07 to 1774554 Compare June 21, 2026 11:49

webext + website

9e63c09

remove

DarhkVoyd force-pushed the claude/exciting-keller-a18866 branch from 1774554 to 9e63c09 Compare June 21, 2026 11:50

github-code-quality Bot found potential problems Jun 21, 2026

View reviewed changes

Restructure the website for App Router colocation and simpler data.

111c312

Colocate docs UI under app/docs, consolidate site config into constants/site.ts, flatten route data files, and remove the old website/lib layer. update

DarhkVoyd force-pushed the claude/exciting-keller-a18866 branch from cea95b3 to 111c312 Compare June 23, 2026 06:15

github-code-quality Bot found potential problems Jun 23, 2026

View reviewed changes

Comment thread website/app/docs/layout.tsx

@@ -0,0 +1,27 @@

import type { Metadata } from "next";

import DocsPageHeader from "./components/DocsPageHeader";

DarhkVoyd added 9 commits June 28, 2026 15:44

Restructure web-ext: co-locate feature stores, introduce core/, clean…

6b904b1

… utils

refactor

9b047ca

refactor: add _KEY/_STORE suffixes to storage constants for clarity

3d9dd18

- CHROME_STORAGE_LOCAL → CHROME_STORAGE_LOCAL_KEY - BROWSER_STORAGE_IDB → BROWSER_STORAGE_IDB_STORE

DarhkVoyd added 2 commits July 25, 2026 23:01

chagnes

fad64e5

github-code-quality Bot found potential problems Aug 16, 2026

View reviewed changes

Navigation Menu

Uh oh!

[web-ext]: add-audio-mode-and-revamp-popup-and-options - #79

[web-ext]: add-audio-mode-and-revamp-popup-and-options#79
DarhkVoyd wants to merge 14 commits into
mainfrom
claude/exciting-keller-a18866

DarhkVoyd commented May 14, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -0,0 +1,249 @@
		import React, { useEffect, useState } from "react";
		import { Link } from "react-router-dom";

		@@ -0,0 +1,27 @@
		import type { Metadata } from "next";
		import DocsPageHeader from "./components/DocsPageHeader";

Uh oh!

Conversation

DarhkVoyd commented May 14, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants