ytc/blurweb

Fork 0

Files

ytc1012 86c47ba772 添加：文本选择模式下，点击恢复功能

2025-12-10 18:36:51 +08:00

6.2 KiB

Raw Permalink Blame History

CLAUDE.md

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

Project Overview

BlurText is a Chrome/Edge browser extension (Manifest V3) for protecting privacy during screen sharing and recording by blurring sensitive text on web pages. The extension is written in vanilla JavaScript with no framework dependencies.

Key Characteristics:

Chinese language UI (all text, comments, and documentation in Chinese)
Manifest V3 standard with Chrome Extension APIs
CSS filter: blur() for visual obfuscation
Chrome Storage API for local configuration persistence

Architecture

Core Components

Extension Structure:

manifest.json - Extension configuration (Manifest V3)
popup.html + popup.js - Browser action UI and control logic
content.js - Content script injected into all web pages (core functionality)
content.css - Injected styles for blur effects and UI overlays

Communication Flow

User clicks extension icon
  → popup.js loads and displays UI
  → User toggles blur mode or changes settings
  → popup.js sends chrome.tabs.sendMessage() to content.js
  → content.js applies blur mode or updates settings
  → content.js stores state in blurredElements Set

Message Types (popup.js → content.js):

toggleBlurMode - Enable/disable blur mode with mode and intensity
clearAll - Remove all blur effects
updateIntensity - Change blur strength on existing blurred elements
switchMode - Change between element and selection modes

Message Types (content.js → popup.js):

blurModeDisabled - Notify when user presses ESC to exit

Two Blur Modes

1. Element Mode (blurMode = 'element')

Default mode with crosshair cursor
Click any DOM element to toggle blur
Hover shows dashed outline highlight
Stores references to blurred elements in blurredElements Set
Does NOT modify DOM structure (only adds/removes CSS classes)

2. Selection Mode (blurMode = 'selection')

Select text with mouse drag
Floating button appears below selection
Wraps selected text in <span class="blurtext-blurred blurtext-selection-wrapped">
Uses Range.surroundContents() - can fail on complex HTML structures
Error handling shows user-friendly message on failure

State Management

Global State (content.js):

let isBlurMode = false;           // Whether blur mode is active
let blurMode = 'element';          // 'element' or 'selection'
let blurIntensity = 10;            // 5-20px blur strength
let blurredElements = new Set();   // References to blurred elements
let hintElement = null;            // Top notification bar
let blurButton = null;             // Floating blur button (selection mode)

Persistence:

Only blurIntensity is stored in chrome.storage.local
Blurred elements are NOT persisted across page refreshes (noted as future feature)

CSS Architecture

Key CSS Classes:

.blurtext-blurred - Applied to blurred elements, uses --blur-intensity CSS variable
.blurtext-mode - Added to <body> in element mode for crosshair cursor
.blurtext-highlight - Dashed outline on hover in element mode
.blurtext-hint - Top notification bar with gradient background
.blurtext-blur-button - Floating button in selection mode
.blurtext-selection-wrapped - Marks spans created by selection mode

Important: All styles use !important to override page styles

Development Commands

This extension has no build process. Load directly as unpacked extension:

Open chrome://extensions/ or edge://extensions/
Enable "Developer mode"
Click "Load unpacked extension"
Select this directory

Testing:

Make code changes
Go to chrome://extensions/ and click the refresh icon on BlurText
Reload any tabs where you want to test changes
Click extension icon to open popup and test functionality

Common Development Patterns

Adding New Message Handlers

In content.js:

chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
  if (request.action === 'yourNewAction') {
    // Handle the action
    console.log('[BlurText] Your action:', request);
  }
});

In popup.js:

chrome.tabs.query({ active: true, currentWindow: true }, (tabs) => {
  chrome.tabs.sendMessage(tabs[0].id, {
    action: 'yourNewAction',
    someData: value
  });
});

Modifying Blur Behavior

All blur effects are controlled by the .blurtext-blurred class in content.css:

.blurtext-blurred {
  filter: blur(var(--blur-intensity, 10px)) !important;
  /* ... other styles ... */
}

The intensity is set via inline style in content.js:

element.style.setProperty('--blur-intensity', `${blurIntensity}px`);

Event Listener Management

Pattern used for mode switching:

Remove all event listeners when changing modes
Add new listeners based on current mode
Clean up UI elements (highlights, buttons) from previous mode

See updateModeUI() in content.js for reference implementation.

Key Constraints & Design Decisions

No persistence across refreshes - Blurred elements are not saved (future feature per CHANGELOG.md)
Local-only processing - No network requests, no external dependencies
Visual-only protection - Blur is CSS effect only, does not modify actual page data
Selection mode limitations - Range.surroundContents() fails on complex nested HTML (error is caught and user is notified)
Popup auto-closes - Normal browser behavior after user interacts with page

File Purpose Reference

icon-generator.html - Standalone tool for generating extension icons (not part of runtime)
test.html - Local test page for development
icons/ - PNG icons in sizes 16, 32, 48, 128 (required by manifest)

Language & Localization

All user-facing strings are in Chinese. When adding features:

Console logs use English with [BlurText] prefix
UI text, hints, and notifications use Chinese
Code comments are in Chinese
Follow existing patterns in popup.html and content.js

6.2 KiB Raw Permalink Blame History