twpkinfo-adblocker/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Tampermonkey/Greasemonkey userscript designed to clean up the TWPKInfo website (https://twpkinfo.com) by removing advertisements, navigation bars, and other UI elements while preserving the Pokemon Go map functionality and map controls.

Architecture

Core Components

Single File Structure: twpkinfo-ad-blocker-sniper.user.js contains all functionality:

• CSS Injection System: Applies cleanup styles via addCleanupCSS() to hide unwanted elements
• Element Removal Engine: Multiple cleanup strategies in cleanupBottomBar() and cleanupTopNavigation()
• Dynamic Monitoring: MutationObserver in startCleanupMonitor() watches for new elements
• Map Optimization: resizeMapToViewport() ensures Leaflet map fills the viewport
• Tooltip System: Custom tooltip implementation for map controls via applyToolbarTooltips()

Key Functions

• addCleanupCSS(): Injects CSS rules for element hiding
• cleanupBottomBar(): Removes bottom navigation/ad elements using multiple detection strategies
• cleanupTopNavigation(): Removes top navigation elements
• startCleanupMonitor(): Sets up mutation observer for dynamic content
• applyToolbarTooltips(): Adds tooltips to map controls
• resizeMapToViewport(): Ensures map fills full viewport

Development Commands

Testing the Userscript

# Install in browser via Tampermonkey/Greasemonkey
# Navigate to https://twpkinfo.com to test functionality

Code Analysis

# Check userscript syntax
node -c twpkinfo-ad-blocker-sniper.user.js

# Search for specific functionality
grep -n "cleanup" twpkinfo-ad-blocker-sniper.user.js
grep -n "tooltip" twpkinfo-ad-blocker-sniper.user.js

Key Considerations

Element Detection Strategies

The script uses multiple approaches to identify unwanted elements:

1. Position-based: Elements with position: fixed at bottom
2. Size-based: Large width elements at viewport bottom
3. CSS class-based: Elements with bottom-related class names
4. Content-based: Elements containing specific text patterns
5. DOM structure: Last child elements of body

Map Preservation

Critical elements that must be preserved:

• #map element and .leaflet-container
• Leaflet map controls (zoom, location, etc.)
• Pokemon-related elements ([class*="pokemon"])
• Map attribution (.leaflet-control-attribution)

Tooltip System

Custom implementation using CSS pseudo-elements and data attributes:

• Uses data-twpk-tooltip for content
• data-twpk-tooltip-side for positioning
• Automatic side detection based on viewport boundaries

Common Development Tasks

Adding New Element Selectors

When TWPKInfo adds new ad/navigation elements, update the CSS selectors in addCleanupCSS():

// Add new selectors to the CSS rules
.new-ad-class,
.new-navigation-element {
    display: none !important;
}

Modifying Detection Logic

To improve element detection, update the strategies in cleanupBottomBar() or cleanupTopNavigation():

• Add new position/size criteria
• Include additional class name patterns
• Update content matching patterns

Adding New Tooltips

Add tooltip mappings in applyToolbarTooltips():

const directTooltips = [
    ['#new_button', '新按鈕說明'],
    // ... existing tooltips
];