Skip to content
metapblPublic

About

사이트의 배너·광고, 우클릭·복사 막기를 걷어내는 브라우저 확장 (Chrome · Firefox · Tor, Manifest V3)

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Unclasp

개인용 브라우저 확장(MV3). 사이트가 강요하는 제약을 걷어내고 페이지 통제권을 사용자에게 돌려줍니다. Chrome, 토르 브라우저, Firefox(ESR·Developer Edition·Nightly)에서 동작합니다. 현재 버전 v1.23.0.

i. 소개

1. 기능

  • 배너·광고 컨테이너 숨기기. 내장 기본 선택자와 직접 지정한 요소를 함께 씁니다
  • 사이트별로 기본 선택자를 끄거나(기본규칙 끔) 일부만 예외 처리. 예외는 옵션 페이지에서도, 진단 모드에서 요소를 직접 지목해서도 추가합니다
  • 텍스트 규칙: 요소 안의 글자로 배너를 찾아 숨김. 포함·완전 일치·정규식으로 찾고, 제외 단어를 함께 등록하면 그 글자가 들어 있는 요소는 빼둡니다. 사이트별로만 등록하며 옵션 페이지의 입력칸에서 추가합니다
  • 빈 컨테이너 접기: 숨긴 요소만 들어 있던 껍데기를 접어 빈 공간을 없앱니다
  • 우클릭 방지 해제 / 복사 방지 해제
  • 백스페이스 뒤로가기 (Shift+Backspace 앞으로)
  • 진단 모드: 숨기는 대신 테두리로 표시합니다. 어느 규칙이 걸렸는지 출처별 색과 배지로 알려주고, 팝업에 색 범례와 출처별 건수가 나옵니다. 탭 단위 임시 상태입니다
  • 요소 선택기: 진단 모드일 때만 씁니다. 일치 개수 라벨, 부모·자식 이동, 겹친 요소 순환, 예외 모드, Ctrl+Z 되돌리기
  • 설정 백업: 전체 설정을 JSON 파일로 저장하고 그 파일로 되돌립니다

배너 숨기기, 우클릭, 복사, 백스페이스 네 가지는 전역 기본값을 두고 사이트별로 덮어씁니다. 사이트 설정이 없으면 전역 기본값을 따릅니다.

2. 설치

이 저장소의 Releases 페이지에서 설치파일을 받아 넣습니다. 소스를 받거나 빌드할 필요는 없습니다. 스토어에 올리지 않았고 서명도 받지 않습니다.

A. Chrome

  1. Releases 에서 unclasp-<버전>-chrome.zip 을 받아 계속 둘 폴더에 풉니다. Chrome 은 zip 을 바로 설치하지 못합니다.
  2. chrome://extensions → 개발자 모드 → 압축해제된 확장 프로그램을 로드 → 푼 폴더를 선택합니다.

그 폴더를 지우면 확장이 동작하지 않습니다. 업데이트할 때는 새 zip 을 같은 폴더에 덮어 풀고 chrome://extensions 에서 새로 고침을 누르십시오. 다른 폴더에서 로드하면 Chrome 이 다른 확장으로 보아 설정이 따라오지 않습니다.

B. 토르 브라우저·Firefox

토르 브라우저와 Firefox ESR·Developer Edition·Nightly 128 이상에 같은 xpi 를 같은 방법으로 설치합니다. 업데이트도 같은 방법입니다.

  1. Releases 에서 unclasp-<버전>.xpi 를 받습니다.
  2. about:config 에서 xpinstall.signatures.required 를 false 로 바꿉니다.
  3. about:addons 의 톱니 단추 → "파일에서 부가 기능 설치" 로 xpi 를 고릅니다.
  4. 확장 상세 화면에서 "사생활 보호 창에서 실행" 을 허용합니다. 토르는 항상 사생활 보호 창이라 허용하지 않으면 동작하지 않습니다.

서명 검사 해제는 그 브라우저의 모든 부가기능에 적용됩니다. 출처를 모르는 xpi 는 설치하지 마십시오.

Firefox 정식판과 베타판은 서명 없이 영구 설치할 수 없습니다. about:debugging 임시 로드만 되고, 브라우저를 다시 시작하면 확장과 설정이 사라집니다.

C. 소스에서 직접 만들기

코드를 고쳐 쓰려면 저장소 최상위 폴더에서 PowerShell 7 로 실행합니다. dist/ 에 zip 과 xpi 가 생깁니다. Chrome 은 src 폴더를 바로 로드해도 됩니다.

pwsh scripts/build.ps1

D. 옛 Unclutter 에서 옮기기

v1.22.0 에서 이름이 Unclutter 에서 Unclasp 으로 바뀌었습니다. 설정 파일 형식은 같습니다.

  • Chrome: 새 zip 을 쓰던 폴더에 덮어 풀고 chrome://extensions 에서 새로 고침을 누릅니다. 설정이 그대로 남습니다.
  • 토르 브라우저·Firefox: 확장 ID 가 바뀌어 다른 확장으로 설치됩니다. 설정은 백업 파일로 옮깁니다.
    1. 옛 Unclutter 의 옵션 페이지에서 "파일로 저장" 을 누릅니다.
    2. about:addons 에서 옛 Unclutter 를 제거합니다.
    3. 위 B 의 방법으로 Unclasp xpi 를 설치하고 "사생활 보호 창에서 실행" 을 허용합니다.
    4. Unclasp 의 옵션 페이지에서 "파일에서 복구" 로 1 의 파일을 고릅니다.

ii. 쓰는 법

1. 팝업

확장 아이콘을 누르면 전역 기본값과 현재 사이트 설정을 함께 조작합니다. 사이트 쪽 스위치에 ● 이 붙으면 전역 기본값을 덮어쓴 상태이고, 전역 기본값과 같은 값으로 되돌리면 ● 이 사라져 "기본값 따름" 으로 돌아갑니다.

숨겨진 요소의 개수와 선택자별 적용 상태도 팝업에서 봅니다. 개수는 최상위 프레임 기준이고 숨김 동작 자체는 모든 프레임에서 됩니다. 진단 모드를 켜면 색 범례와 출처별 건수가 함께 표시됩니다. 열린 팝업은 이 탭의 진단 상태 변경과 단축키 결과를 바로 반영합니다. 다른 탭에서 요소를 고른 뒤에는 팝업을 다시 열어야 값이 맞습니다. 팝업 건수와 화면의 배지 개수는 기준이 달라 어긋날 수 있습니다(v-1).

2. 진단 모드

무엇이 왜 사라졌는지 확인할 때 켭니다. 숨기는 대신 테두리로 표시하고, 요소 왼쪽 위에 어떤 규칙에 걸렸는지 배지를 붙입니다. 색은 팝업 범례와 같습니다.

  • 파란 점선 : 직접 지정한 선택자(내 규칙). 팝업이나 옵션 페이지에서 지울 수 있습니다
  • 빨간 점선 : 내장 기본 선택자
  • 초록 실선 : 기본 선택자에 일치하지만 숨지 않는 요소. 예외(ex)나 구조 가드로 살아남았거나 기본규칙 끔(nb) 상태입니다
  • 주황 점선 : 텍스트 규칙. 낱말을 품은 요소 중 가장 안쪽에 붙습니다. 제외 단어가 있는 규칙이면 배지 끝에 − "제외단어" 가 함께 나옵니다
  • 회색 점선 : 접힘 예정. 숨긴 요소만 남아 빈 껍데기가 될 컨테이너입니다

한 요소가 여러 규칙에 걸리면 조치하기 쉬운 쪽을 먼저 보여줍니다. 순서는 텍스트 규칙, 내 규칙, 기본 규칙, 예외 유지, 접힘 예정입니다. 표시는 한 페이지에 400개까지 붙고, 상한에 걸리면 출처별로 자리를 고르게 나누므로 배너가 수백 개인 페이지에서도 내 규칙과 예외가 밀려나지 않습니다(v-1).

요소 선택기로 고른 요소는 진단 모드가 켜져 있는 동안 숨지 않고 파란 점선으로 남습니다. 접기도 진단 모드에서는 실행하지 않고 표시만 하므로, 회색 점선이 붙은 요소는 진단 모드를 끄는 순간 접힙니다. 진단 모드는 탭 단위 임시 상태여서 탭을 닫거나 새 페이지를 열면 꺼집니다.

3. 요소 선택기 (골라 숨기기)

진단 모드에서 팝업의 "골라 숨기기" 스위치를 켜거나 Alt+Shift+C 로 시작합니다. 클릭할 때마다 선택자가 누적됩니다. 선택기가 켜진 채 팝업을 다시 열면 스위치가 켜져 있고, 끄면 선택기가 끝납니다.

화면 아래 어두운 막대에 줄이 둘 나옵니다. 위쪽 상태줄은 지금 모드와 방금 한 일을, 아래쪽 안내줄은 조작키를 보여줍니다. 막대 왼쪽 선은 숨김 모드에서 파랑, 예외 모드에서 초록입니다. 안내줄은 모드를 바꿀 때만 바뀌므로 등록 결과가 길어져도 조작키가 사라지지 않습니다.

  • 마우스 이동 : 대상 지정. 요소 옆 라벨에 선택자와 일치 개수가 표시됩니다
  • 파란 라벨 : 일치 1개. 그 요소만 숨습니다
  • 주황 라벨 : 일치 여러 개. 범위가 넓으니 ↑ 로 좁히거나 그대로 쓸지 판단하십시오
  • 예외 모드의 초록 라벨 : 기본 규칙에 걸린 요소입니다. 괄호 안은 그 예외가 덮는 요소 수와 그중 기본 규칙에 걸린 수입니다
  • 예외 모드의 주황 라벨 : 기본 규칙에 걸린 조상이 없어 예외로 뺄 것이 없습니다
  • ↑ 또는 w : 부모 요소로 이동 / ↓ 또는 s : 자식 요소로 이동
  • Tab : 같은 좌표에 겹친 요소 순환. 고정된 오버레이 뒤의 요소를 고를 때 씁니다. Tab·↑·↓ 로 고르면 조준이 고정되고, 그 위를 덮은 요소가 흐려지며 클릭이 통과하므로 그 자리를 클릭하면 고른 요소가 등록됩니다. 마우스를 크게(24px 넘게) 움직이거나 다른 요소를 고르거나 선택을 끝내면 덮개는 원래대로 돌아갑니다
  • iframe 광고 : 선택 중에는 iframe 위를 가리키면 iframe 자체가 조준되고, 클릭해도 iframe 안의 링크는 동작하지 않습니다. 선택 중에는 iframe 안을 스크롤할 수 없습니다
  • e : 숨김 모드와 예외 모드를 번갈아 바꿉니다. 상태줄이 "예외 모드" 로 바뀌면 적용된 것이고, 선택기를 닫았다 다시 열면 숨김 모드로 시작합니다
  • 클릭 또는 Enter : 선택 확정, 현재 사이트 항목에 저장
  • Ctrl+Z : 직전 추가 취소 / ESC : 선택 종료

선택기를 켠 채 페이지를 스크롤하면 테두리와 라벨이 조준한 요소를 따라갑니다. 다만 화면이 움직이면 같은 좌표에 겹친 요소가 달라지므로 Tab 순환은 처음부터 다시 시작합니다.

이 조작키는 페이지 안에서 처리되므로 브라우저의 단축키 설정 화면(ii-5)에는 나오지 않습니다. w, s, e 는 사이트 자체 단축키와 겹칠 수 있으니 이동은 화살표로 대신할 수 있습니다. 예외 모드 전환은 e 뿐입니다.

4. 옵션 페이지에서 추가하기

옵션 페이지의 사이트, 내가 숨긴 항목, 기본 규칙 예외, 텍스트 규칙 네 카드는 모두 카드 안의 입력칸으로 추가합니다. "추가" 를 누르거나 Enter 를 치면 그 자리에서 저장되고 결과가 화면 아래에 뜹니다. 호스트 칸은 네 폼이 같은 제안 목록을 쓰므로 이미 등록된 사이트가 제안되고, https://example.com/ 처럼 주소를 넣어도 호스트만 남습니다.

왼쪽 사이트 목록에서 사이트를 고르면 카드들이 그 사이트 것만 보이고 추가 칸의 호스트가 채워집니다. "모든 사이트" 에서는 사이트 표와 숨긴 항목·예외·텍스트 규칙 카드에 사이트별 줄이 보이지 않으므로, 사이트가 많아도 페이지가 길어지지 않습니다. 위쪽 찾기칸에 호스트·선택자·낱말 일부를 넣으면 맞는 사이트와 규칙이 펼쳐지고, 비우면 다시 숨습니다. 색 점은 그 사이트에 숨긴 항목(파랑)·예외(초록)·텍스트 규칙(주황)이 있다는 뜻이고, 빈 고리는 기능을 ON·OFF 로 정했거나 기본규칙을 끈 사이트입니다.

텍스트 규칙 카드에는 사이트 호스트, 탐색 범위, 일치 방식, 낱말, 제외 단어를 넣습니다. 범위를 비우면 div 가 됩니다. 낱말은 두 글자 이상이어야 합니다.

일치 방식은 셋이고 모두 대소문자를 가리지 않습니다. 포함은 낱말이 요소의 글자 안에 들어 있으면 잡습니다. 완전 일치는 앞뒤 공백을 빼고 연속 공백을 하나로 본 글자 전체가 낱말과 같을 때만 잡습니다. 정규식은 글자에 패턴이 맞으면 잡습니다.

정규식은 100자까지 받습니다. (a+)+ 처럼 반복 안에 다시 반복이 있는 패턴은 페이지를 멈추게 할 수 있어 받지 않습니다. 복구 파일에 든 이런 규칙은 버리고, 복구 확인창에 "위험 패턴 N개 버림" 으로 알려 드립니다.

제외 단어는 비워 두어도 되고, 쉼표로 여러 개 적으면 그 글자가 하나라도 들어 있는 요소는 낱말이 있어도 숨기지 않습니다. "광고" 를 잡되 "광고문의" 는 빼는 것이 대표적인 쓰임이고, 낱말을 품지 않는 맥락어도 됩니다. 이를테면 낱말 "이벤트" 에 제외 단어 "당첨자" 를 걸면 당첨자 발표 문단은 남습니다. 제외 단어도 두 글자 이상이어야 하고, 규칙 하나에 다섯 개까지, 낱말과 같은 글자는 받지 않습니다. 완전 일치에는 제외 단어를 쓸 수 없습니다.

같은 범위·낱말 조합을 다시 추가하면 새 규칙이 생기는 대신 일치 방식과 제외 단어만 바뀝니다. 제외 단어를 없애려면 같은 범위·낱말로 제외 단어 칸을 비워 추가하십시오. 추가하면 호스트와 범위는 칸에 남으므로 같은 사이트에 낱말을 여러 개 넣을 때 다시 타이핑하지 않아도 됩니다.

목록의 "규칙 삭제 ✕" 는 제외 단어만이 아니라 그 규칙 전체를 지웁니다. 누르면 지울 규칙을 적은 확인창이 먼저 뜨고, 지우면 무엇이 사라졌는지 화면 아래에 알려 드립니다. 숨긴 항목과 예외 목록의 ✕, 사이트 표의 ✕, 팝업의 내가 숨긴 항목 ✕ 도 같습니다.

5. 단축키

A. 기본 제안값

chrome://extensions/shortcuts 에서 확인·변경합니다. Firefox·토르는 about:addons 의 톱니 단추 → "확장 기능 단축키 관리" 입니다.

  • Alt+Shift+O : 팝업 열기
  • Alt+Shift+C : 골라 숨기기 켜기/끄기 (켤 때 진단 모드가 꺼져 있으면 함께 켜고, 끌 때 진단은 그대로)
  • Alt+Shift+X : 진단 모드 켜기/끄기
  • Alt+Shift+Z : 이 사이트의 배너 숨기기 켜기/끄기

결과는 확장 아이콘의 배지로 1.5초간 표시됩니다. 진단을 켜면 DX, 골라 숨기기는 SEL, 배너를 숨기면 AD, 끄거나 다시 보이면 회색 OFF 이고 실패하면 빨간 × 가 뜹니다. http/https 가 아닌 페이지(chrome://, 웹스토어, 파일 목록 등)에서는 항상 실패합니다. 배너 토글은 전역 기본값이 아니라 현재 사이트 항목에 씁니다. 팝업이 열린 채 단축키를 눌러도 팝업은 닫히지 않고 스위치가 바뀝니다. 골라 숨기기를 켤 때만 페이지를 조준할 수 있게 닫힙니다.

새로 추가된 단축키는 기본값이 자동으로 배정되지 않으므로 위 화면에서 직접 지정해야 합니다. 제거 후 재설치하면 배정되지만 로컬 데이터가 지워지므로 옵션 페이지의 "파일로 저장" 으로 먼저 백업하십시오.

v1.19.0 에서 팝업 열기는 Alt+Shift+A 에서 O 로, 골라 숨기기(당시 이름 요소 선택)는 Alt+Shift+S 에서 C 로 바뀌었습니다. A 는 크롬이 비활성 대화상자 초점에 쓰고, S 는 Firefox·토르의 메뉴 막대 "기록" 과 겹쳤습니다. 개발 중 잠시 쓴 P 는 Firefox 메뉴 막대 "프로필" 과 겹칩니다. 크롬에서는 이미 설치한 확장에 예전 키가 남을 수 있으므로 위 화면에서 직접 바꾸십시오. Firefox·토르는 v1.21.0 부터 확장을 설치하거나 업데이트할 때 네 단축키를 위 기본값으로 되돌립니다. 위 화면에서 바꾼 키도 다음 업데이트 때 기본값으로 돌아갑니다.

B. Windows 주의

Alt+Shift 는 키보드 입력 언어 전환 조합입니다. 단축키를 누른 뒤 한글/영문이 뒤바뀌면 Windows 고급 키보드 설정에서 입력 언어 전환 키를 없음으로 바꾸거나 Alt+Y / Alt+U / Alt+K 처럼 Alt 단독 조합으로 옮기십시오. Alt+D, Alt+E, Alt+F, Alt+Home, Alt+←, Alt+→ 는 크롬이 쓰고 있어 피해야 합니다.

C. 페이지 단축키와 겹칠 때

Firefox·토르에서는 페이지가 같은 글자의 accesskey 를 쓰면 페이지가 먼저 받습니다. 위키백과는 O·C·X·Z 를 모두 쓰므로 단축키가 확장으로 오지 않습니다. 그런 페이지에서는 툴바 아이콘으로 팝업을 여십시오. 팝업이 열린 동안에는 단축키도 동작합니다. Chrome 은 확장이 먼저 받습니다.

iii. 과탐이 생겼을 때

클래스 이름으로는 광고를 가릴 수 없으므로, 기본 규칙은 느슨하게 두고 불편한 사이트에서 직접 조정하는 방식입니다.

1. 확인 순서

  1. 진단 모드를 켜서 무엇에 걸렸는지 봅니다. 테두리 색과 배지가 출처를 알려줍니다.
  2. 파란 점선이었다면 팝업의 선택자 목록이나 옵션 페이지에서 지웁니다.
  3. 주황 점선이었다면 그 규칙에 제외 단어를 더하거나, 완전 일치로 바꾸거나, scope 를 좁히거나, 규칙을 지웁니다. 포함 방식은 "광고문의" 가 "광고" 에 걸리므로, 같은 범위·낱말로 제외 단어만 넣어 다시 추가하는 것이 가장 짧은 방법입니다.
  4. 빨간 점선이었다면 아래 예외나 기본규칙 끔으로 처리합니다.

2. 예외와 기본규칙 끔

기본 규칙에 걸린 것이고 한두 개라면 그 요소를 예외로 뺍니다. 방법은 두 가지입니다.

  • 진단 모드에서 요소 선택기를 열고 e 를 눌러 예외 모드로 바꾼 뒤 빨간 점선 요소를 클릭합니다. 클릭한 요소가 아니라 기본 규칙에 실제로 걸린 조상을 찾아 저장하므로 안쪽 요소를 눌러도 됩니다. 걸린 조상이 없으면 라벨이 그 사실을 알려주고 아무것도 저장하지 않습니다. 너무 많은 요소를 함께 잡는 선택자도 쓰지 않습니다
  • 옵션 페이지의 "기본 규칙 예외" 칸에 선택자를 직접 적습니다

예외로 처리하면 진단 모드에서 초록 실선으로 바뀌므로 적용됐는지 바로 확인할 수 있습니다. 예외는 기본 규칙에만 적용되므로, 예외로 살려둔 요소를 나중에 팝업에서 다시 명시적으로 숨길 수 있습니다.

예외가 세 개를 넘으면 그렇게 알려줍니다. 사이트 목록의 "기본규칙" 칸을 "끔" 으로 바꾸고 실제 광고만 요소 선택기로 직접 등록하는 편이 낫습니다. news.naver.com 이 그 경우였고, 확인된 7건 중 6건이 과탐이어서 기본 규칙을 끄고 .gnb_banner 하나만 등록하는 쪽이 훨씬 간단했습니다.

iv. 설정 데이터

1. 스키마

chrome.storage.local 에 사이트 설정을 호스트별 항목으로 나눠 저장합니다. v1.17.0 까지는 chrome.storage.sync 에 두었고, 새 버전을 처음 실행할 때 local 이 비어 있으면 sync 의 설정을 그대로 복사합니다. sync 쪽은 지우지 않으므로 옛 버전으로 되돌려도 설정이 남아 있습니다. 복사가 실패하면 옵션 페이지 용량 줄에 오류가 보이고 브라우저를 다시 시작할 때 다시 시도합니다. v1.7 이하가 쓰던 sites 한 항목에 모든 사이트를 넣는 옛 형식은 v1.18.0 부터 읽지도 지우지도 않습니다. 백업 파일의 sites 묶음은 지금 형식이므로 그대로 복구됩니다.

{
  "global": { "banner": true, "rightclick": false, "copy": false, "back": true },
  "s:example.com": {
    "rightclick": true,
    "selectors": ["#promo", ".ad-wrap"],
    "texts": [
      { "scope": "div", "word": "광고", "not": ["광고문의"] },
      { "scope": "div", "word": "특가", "m": "eq" }
    ]
  },
  "s:news.naver.com": { "nb": true, "selectors": [".gnb_banner"] },
  "schema": 2
}

해석 규칙은 site?.feature ?? global[feature] 입니다. 사이트 항목의 필드는 이렇습니다.

  • banner / rightclick / copy / back : 전역 기본값을 덮어쓰는 3-state 오버라이드
  • selectors : 직접 지정한 CSS 선택자 목록
  • texts : 텍스트 규칙 목록. { scope, word } 에 일치 방식 m 은 "eq"(완전 일치)나 "re"(정규식)이고 포함이면 키가 없습니다. 제외 단어가 있으면 not 배열이 붙습니다. 제외 단어가 없는 규칙에는 not 키 자체가 없습니다
  • nb : 기본 규칙 끔. true 면 이 사이트에서 내장 기본 선택자를 쓰지 않습니다
  • ex : 기본 규칙 예외. 기본 선택자에만 적용되고 직접 지정한 선택자에는 적용되지 않습니다

필드가 저장되는 순서는 만들어진 경로에 따라 다를 수 있습니다. 값이 같으면 순서가 달라도 같은 설정으로 봅니다.

사이트 항목에 플래그도 selectors 도 texts 도 nb 도 ex 도 없으면 s:<host> 키 자체가 제거됩니다. 플래그는 true/false 일 때만, nb 는 true 일 때만, 목록은 실제 내용이 있을 때만 "있다" 고 봅니다. texts 는 word 가 실제로 있는 규칙이 하나라도 있어야 하므로, 제외 단어만 남은 항목은 내용으로 보지 않습니다. 빈 목록이나 nb: false 만 남은 항목은 그 사이트를 다시 저장할 때 정리됩니다.

진단 모드는 chrome.storage.session 에 저장되므로 탭을 닫거나 브라우저를 닫으면 사라집니다.

2. 백업과 복구

옵션 페이지의 "백업과 복구" 에서 파일로 주고받습니다.

"파일로 저장" 을 누르면 현재 설정 전체가 settings-backup-2026-09-16.json 처럼 날짜가 붙은 파일로 내려받아집니다. 내용은 { schema, global, sites } 형태이고 사람이 읽을 수 있게 들여쓰기돼 있습니다.

"파일에서 복구" 는 고른 파일의 내용으로 지금 설정을 교체합니다. 합치지 않습니다. 바꾸기 전에 사이트가 몇 개 추가·교체·삭제되는지, 어떤 사이트가 사라지는지 확인 창으로 알려주므로 그 자리에서 취소할 수 있습니다. v1.7.x 에서 만든 백업 파일도 그대로 복구됩니다. 알 수 없는 필드나 형식이 맞지 않는 항목은 조용히 버립니다.

같은 파일을 그대로 다시 복구하면 확인 창에 "사이트 설정 변경 없음" 이라고 나옵니다.

설정을 직접 고치고 싶으면 파일로 저장한 뒤 편집기에서 수정하고 다시 복구하십시오. 텍스트 규칙의 not 은 배열이 정석이지만 문자열 하나만 적어도 받아들이고, 낱말과 같은 글자나 빈 값은 버립니다.

3. 용량

storage.local 의 한도는 전체 10MB(10,485,760바이트)이고 항목당·항목 수 한도는 없습니다. sync 시절의 100KB·항목당 8KB·512개 한도는 더 이상 적용되지 않습니다. 백업 파일은 1MB 까지 복구할 수 있습니다. 한도를 넘으면 저장 실패를 화면에 알립니다. 규칙을 줄이거나 필요 없는 사이트를 지우십시오.

현재 사용량(예: 2.6KB / 10MB 사용 (1% 미만))과 사이트 개수는 옵션 페이지의 "백업과 복구" 카드 아래에서 봅니다. 한글은 UTF-8 에서 글자당 3바이트입니다. http/https 가 아닌 페이지에서는 사이트 항목을 만들지 않고 전역 기본값만 편집됩니다.

v. 한계와 문제 해결

1. 알려진 한계

  • Shadow DOM 내부에는 CSS 가 적용되지 않습니다.
  • 요소 선택기는 최상위 프레임에서만 동작합니다. iframe 광고는 iframe 자체를 선택하십시오. 팝업의 규칙 개수와 진단 범례 건수도 최상위 프레임 기준이고, 숨김 동작은 모든 프레임에서 됩니다.
  • 팝업의 건수는 규칙에 걸린 후보 수이고 배지 개수는 실제로 칠해진 수라서 어긋날 수 있습니다. 접힘 후보 7개 중 2개가 예외나 기본 규칙으로 이미 칠해졌으면 팝업은 7, 배지는 5 입니다. 직접 지정한 선택자가 기본 규칙과 겹칠 때도 팝업은 기본 규칙 쪽에, 배지는 내 규칙 쪽에 세므로 한 개 차이가 납니다. 기준 차이지 오류가 아닙니다.
  • 진단 표시는 한 페이지에 400개까지만 붙습니다. 출처별로 자리를 고르게 나누므로 내 규칙과 예외는 남지만, 기본 규칙에만 걸린 요소는 뒤쪽부터 빠집니다.
  • 텍스트 규칙의 포함 방식은 글자가 들어 있는지만 보므로 "광고문의" 가 "광고" 에 걸립니다. 제외 단어나 완전 일치로 그 경우를 뺄 수 있습니다.
  • 제외 단어는 요소 단위로 판정합니다. 한 요소가 낱말과 제외 단어를 함께 가지면 낱말 자리만 지우는 방식이라면 잡았을 경우에도 숨지 않습니다. 가장 안쪽 요소만 잡는 성질이 손실을 좁혀 주므로 문제가 되는 것은 가장 안쪽 요소 하나가 둘을 함께 가질 때이고, 그때는 범위를 좁히십시오.
  • 텍스트 규칙의 nav·footer 제외는 조상과 자손 양쪽을 봅니다. 그래서 반대로, 자체 메뉴(nav)를 품은 정상 광고 블록은 놓칩니다. 드문 형태라 그대로 두고 있으니 텍스트 규칙이 갑자기 덜 잡히면 이 검사를 먼저 의심하십시오.
  • 목록의 ✕ 는 누를 때 화면에 적힌 값과 저장된 값을 대조합니다. 두 화면에서 같은 사이트를 고쳐 순서가 어긋났으면 지우지 않고 "목록이 바뀌었습니다. 다시 확인하고 눌러 주십시오." 라고 알립니다.
  • 진단 모드의 배지는 의사 요소로 그리므로 iframe 과 img 에는 나타나지 않고 테두리만 남습니다. 감싼 div 가 걸린 경우에는 정상적으로 표시됩니다.
  • 부모와 자식이 모두 걸리면 배지가 같은 좌상단에 겹쳐 하나만 보입니다. 위에 그려진 쪽이 자식입니다. 텍스트 규칙은 가장 안쪽 요소만 잡으므로 텍스트끼리는 겹치지 않습니다.
  • 초록 실선과 팝업의 "예외 유지" 건수는 예외(ex)로 뺀 것과 구조 가드로 걸러진 것을 구분하지 않습니다. 둘 다 "기본 규칙에 닿았으나 숨지 않음" 이라는 뜻입니다.
  • 클래스 이름 문자열로는 광고를 판정할 수 없습니다. 국내 포털은 광고가 아닌 UI 에도 banner 를 씁니다. 기본 규칙은 느슨하게 두었으니 과탐이 생기면 예외나 기본규칙 끔으로 조정하십시오.
  • 기본 규칙의 banner 검사는 div 에만 걸립니다. li.banner-item 같은 요소는 잡히지 않습니다. 범위를 넓히면 과탐이 늘어나므로 의도적으로 두고 있습니다.
  • 여러 탭에서 같은 사이트의 설정을 동시에 고치면 나중 쓰기가 앞의 변경을 덮을 수 있습니다. 한 화면에서 고치십시오.

2. 저장된 값 보기

서비스 워커 콘솔(chrome://extensions → Unclasp → 서비스 워커)에서 실행합니다. Firefox·토르는 about:debugging#/runtime/this-firefox → Unclasp → "검사" 의 콘솔입니다.

chrome.storage.local.get(null, a => console.log(Object.keys(a)))
chrome.storage.local.get(null, a => console.log(JSON.stringify(a, null, 2)))
chrome.storage.local.getBytesInUse(null, n => console.log(n))

텍스트 규칙이 등록되지 않은 것 같을 때도 여기서 확인합니다. 페이지 콘솔에서는 chrome.storage 를 쓸 수 없습니다. 콘텐츠 스크립트가 격리된 환경에서 돌기 때문에 페이지 콘솔에 입력한 코드에는 그 API 가 없습니다. 한 사이트만 보려면 키를 지정하십시오.

chrome.storage.local.get("s:example.com", o => console.log(JSON.stringify(o, null, 2)))

진단 모드의 켜짐 상태는 session 에 탭별로 들어갑니다. 단축키가 안 먹는 것 같으면 같은 콘솔에서 아래로 확인하십시오. diag:<tabId> 키가 없으면 단축키 자체가 배경으로 가지 않은 것이고, 키가 true 인데 화면이 반응하지 않으면 그 탭의 콘텐츠 스크립트가 배경의 알림을 받지 못한 것입니다. 새로 고치거나 다른 주소로 이동하면 진단은 꺼집니다.

chrome.storage.session.get(null, a => console.log(a))

3. 숨긴 규칙 찾기

진단 모드의 배지로 확인하십시오. 평소(진단·선택기를 쓰지 않는 동안)의 숨김 규칙은 페이지가 확장을 알아채지 못하도록 페이지 DOM 에 <style> 이나 클래스를 남기지 않습니다. Firefox·토르는 사용자 스타일시트로 넣어 페이지 콘솔에서 보이지 않고, Chrome 은 document.adoptedStyleSheets 에 넣어 콘솔에서 규칙 글자를 읽을 수 있습니다. 텍스트 규칙과 빈 컨테이너 접기는 요소의 자리를 가리키는 선택자(:root>*:nth-child(2)>…)로 들어갑니다. 요소가 안 보이게 된 것 자체는 페이지가 알아챌 수 있습니다.

텍스트 규칙이 잡을 것 같은데 잡지 않는 경우에는 페이지 콘솔에서 걸러내기 조건을 직접 확인할 수 있습니다. 포함 방식 기준이고, div 와 광고 자리에 그 규칙의 범위와 낱말을 넣으십시오.

for (const el of document.querySelectorAll("div")) {
  const t = el.textContent || "", low = t.toLowerCase();
  const r = el.getBoundingClientRect();
  if (!low.includes("광고")) continue;
  console.log(el, {
    len: t.length,                                  // 200 초과면 제외
    skipUp: !!el.closest("nav, footer"),            // 조상 메뉴·푸터
    skipDown: !!el.querySelector("nav, footer"),    // 자손 메뉴·푸터
    w: r.width, h: r.height                         // 80 / 30 미달이면 제외
  });
}

4. 설정 되돌리기

특정 사이트 항목만 지우려면 서비스 워커 콘솔에서 chrome.storage.local.remove("s:example.com") 을 실행합니다. 설정 전체를 되돌리려면 옵션 페이지에서 백업 파일로 복구하십시오.

vi. 라이선스

MIT License, Copyright (c) 2026 META PUBLIC. LICENSE를 보세요. 아이콘(src/icons/)도 같은 라이선스입니다. 릴리스의 zip·xpi 안에도 LICENSE 가 들어 있습니다.

About

사이트의 배너·광고, 우클릭·복사 막기를 걷어내는 브라우저 확장 (Chrome · Firefox · Tor, Manifest V3)

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages