필기웹 (pdf-ink)

굿노트처럼 PDF 위에 펜으로 필기하는 웹앱. 서버도 로그인도 없습니다.

써 보기 → https://pdf-ink.vercel.app

무엇	PDF를 열어 펜·형광·색연필로 쓰고, 쪽을 오리고 붙이고, 목차를 달고, PDF로 굽는다
어디에 남나	필기는 이 브라우저에. 원하면 드롭박스·구글 드라이브의 PDF 옆에 작은 파일로
서버	없음. 정적 호스팅뿐이라 우리 쪽에 남는 문서가 없다
기술	바닐라 JS + Vite · pdf.js(렌더) · pdf-lib(쓰기) · PWA(오프라인)
라이선스	AGPL-3.0-or-later

---

이런 앱입니다

• 종이가 먼저. 툴바·서랍이 종이 크기나 비율을 깎지 않습니다(미리보기 서랍만 예외로 밀어냅니다).
• 바 하나. 굿노트4식 유틸리티 바 한 줄. 두 번째 알약이나 레일을 만들지 않습니다.
• 조용히 이기지 않습니다. 남의 기기가 고친 것을 덮어쓰지 않고, 지운 것은 되돌릴 수 있고, 실패는 한 줄로 말합니다.
• 펜이 먼저입니다. S펜·애플펜슬이 보고하는 표본을 하나도 버리지 않고 곡선으로 잇고, 그리는 동안에는 그 획만 따로 얹어 필기가 쌓여도 느려지지 않습니다. 저장은 획 사이가 아니라 한가할 때 합니다.
• 필기는 좌표입니다. 1000쪽 문서라도 저장은 몇 KB, 언제든 다시 고칠 수 있습니다.

30초 시작

1. PDF만 올려요 상자에 PDF를 놓습니다. 드롭박스·구글 드라이브에서 바로 열 수도 있습니다.
2. 문서는 잠금(보기)으로 열립니다. 헤더 오른쪽 자물쇠로 편집으로 바꿉니다.
3. 바에서 도구를 고르고 씁니다. 클라우드 문서라면 2.5초 뒤 알아서 올라갑니다 — 평소엔 저장을 누를 일이 없습니다.

---

도구

바 한 줄

칸	탭하면	길게 누르면(400ms)
펜	펜으로 쓰기	색·굵기 팔레트
형광	형광펜(끌 정도 투명, 납작한 팁)	팔레트
색연필	색연필(기본 채점 빨강)	팔레트
지우개	쓰던 모드로 지우기	획/픽셀 모드와 크기
손바닥	종이를 끌어 옮기기 (편집 진입 시 기본)	—
선택	상자로 고르기 · 영역 잡기	—
되돌리기 / 다시 실행	한 단계	되돌리기를 길게 = 다시 실행
⋯	전체화면 · 이미지 · 쪽 가져오기 · 스티커 · 회전 · 쪽 복사/붙여넣기 · 선반 · 저장 · PDF에 굽기 · 다른 이름으로 저장 · 내보내기 · 필기 옮기기

PC에서는 스페이스를 누르는 동안만 손바닥이 되고, 떼면 쓰던 도구로 돌아옵니다.

색과 굵기

• 팔레트는 2×3. 흰색도 있고, 색 칸을 길게 누르면 색상환이 뜹니다 — 각도가 색, 중심거리가 채도, 미끄럼대가 밝기입니다. 고른 색은 팔레트 끝에 최근 5개까지 남습니다.
• 굵기는 0.5부터 반 칸 단위로, 지금 굵기가 숫자로 보입니다.
• 스포이드로 종이를 탭하면 눈에 보이는 그 색(PDF·필기·이미지가 겹친 그대로)을 가져옵니다.
• 색은 바에 미니 점으로만 보입니다.

도형 만들기

펜·형광·색연필로 한 획을 긋고 끝에서 400ms 멈추면 후보 도형이 40% 고스트로 뜨고 직선·사각·원 칩이 종이 위에 납니다. 칩을 눌러야 도형이 되고, 안 고르면 손 획 그대로입니다.

선택과 영역

• 탭하면 그 획이 잡히고, 이미 고른 것 위에서 끌면 옮겨집니다.
• 글씨 위에서 시작한 끌기는 상자를 그립니다 — 빽빽한 곳에서도 영역을 잡을 수 있습니다. 그림·도장은 예전처럼 바로 끌립니다.
• 상자에 잡힌 게 없으면 점선 영역이 남습니다. 길게 누르거나 오른쪽 클릭하면 붙여넣기·복사·복제·삭제·캡처·마스킹 메뉴가 뜹니다.
• 고른 것은 화살표키로 밀 수 있습니다(Shift는 크게, Alt는 화면 한 점씩). 연달아 민 것은 되돌리기 한 번에 통째로 돌아갑니다.
• 모서리로 크기를 바꾸면 비율이 유지되고, 선택 바의 자유비율을 켜면 마음대로 늘어납니다. 선택 바는 고른 것을 가리지 않게 자리를 잡습니다.

지우개와 펜 느낌

• 지우개 칸을 탭하면 쓰던 모드 그대로(기본 획 지우개), 모드는 길게 눌러 여는 패널에서만 바뀝니다.
• 펜을 뒤집은 지우개 꼭지는 언제나 지우개입니다.
• 펜을 종이 위에 띄우면 닿을 자리가 지금 색·굵기로 보이고, 도구마다 모양이 다릅니다(지우개는 점선 원, 형광은 모난 자국, 선택은 얇은 점).
• 마우스 커서도 도구를 따릅니다 — 잠금·손바닥은 손 모양, 선택은 화살표, 지우개는 실제 지우는 크기의 원, 링크 위에서는 손가락. 펜 종류는 호버 점이 커서 역할을 하므로 커서를 감춥니다.
• 설정의 펜만을 켜면 S펜·애플펜슬만 획을 만들고 손가락은 페이지를 움직입니다(기본 꺼짐).

---

페이지와 문서

미리보기 서랍

헤더 왼쪽 위 아이콘으로 엽니다. 눌러 두면 종이를 만지거나 획을 그어도 열린 채 남고, 본문을 가리지 않고 왼쪽 자리를 차지하며 밀어냅니다(오른쪽 가장자리를 끌어 96~360px). 썸에는 필기도 함께 보이고, 한 번 그린 쪽 그림은 저장해 두었다가 다시 열 때 바로 씁니다.

쪽 다루기

• 썸을 길게 누르거나 오른쪽 클릭: 복사·붙여넣기·복제·삭제·여러 개 고르기·위로·아래로·왼쪽 90°·오른쪽 90°.
• 잡은 채로 끌면 순서가 바뀌고 필기도 따라갑니다. 복제·붙여넣기로 생긴 쪽은 필기를 따로 가집니다.
• ⋯의 쪽 가져오기로 그림·PDF를 지금 보는 쪽 다음에 끼웁니다. 원본 크기·비율을 지킵니다.
• 페이지 탭의 빈 쪽은 앞 쪽과 같은 크기의 백지 한 장입니다.

목차와 책갈피

목차 항목은 쪽 번호가 아니라 그 쪽 자체를 가리켜서, 순서를 바꾸거나 앞에 쪽을 끼워도 같은 쪽으로 갑니다. 탭하면 이동, 더블탭하면 이름 고치기, 길게 누르면 이름 변경·삭제입니다. 원래 목차가 든 PDF를 열면 그 목차를 읽어 채웁니다. 목차와 책갈피(별)는 내보낸 PDF 안에 박힙니다.

이미지와 스티커

• 그림 파일을 종이에 끌어다 놓거나 Ctrl+V로 붙입니다. 붙인 그림은 보던 크기 그대로 앉고, 원본 해상도를 지켜 확대해도 또렷합니다.
• 누른 자리 없이 그냥 붙여넣으면 있던 그 자리에 들어갑니다(영역캡처한 것은 오려 낸 자리로).
• ⋯의 스티커: 그림에서 영역을 잘라 스티커를 만들고 폴더로 정리합니다. 스튜디오에서 투명(색 찍기)·지우개·회전·크롭으로 다듬고, 취소와 되돌리기가 있습니다. 지울 때는 한 번 더 묻습니다.
• 도장은 기본 스티커 「도장」 폴더로 들어 있습니다.
• 설정의 스티커 동기화에서 드롭박스나 드라이브를 고르면 기기 사이에서 스티커가 합쳐집니다.

필기 옮기기

같은 자료의 다른 판에서 필기를 가져옵니다. 쪽 번호가 아니라 쪽에 적힌 글자(없으면 쪽 그림)로 짝을 찾으므로 판마다 쪽 수가 달라도 제자리를 찾아갑니다. 두 문서를 나란히 놓고 짝을 고쳐 정할 수 있고, 되돌리기 한 번으로 통째 취소됩니다.

---

저장과 동기

무엇	어디에
필기·쪽 구성·목차	이 브라우저(localStorage, 넘치면 IndexedDB) + 클라우드 사이드카 <이름>.pdf.ink
PDF 원본	열어 온 곳(로컬 파일 · 드롭박스 · 구글 드라이브) + 다시 열기용 사본(IndexedDB)
쪽 그림(썸네일)	IndexedDB. 문서별 설정으로 <이름>.pdf.thumbs 공유
스티커	IndexedDB + (고르면) 드롭박스·드라이브

• 자동 저장: 클라우드 문서는 필기가 바뀌면 2.5초 뒤 사이드카가 올라갑니다(그리는 중에는 미루고, 창을 덮거나 닫을 때는 즉시).
• 합치기: 다른 기기가 쓴 필기를 항목 단위로 합칩니다 — 서로 다른 쪽에 쓴 것이 어느 쪽도 지워지지 않고, 지운 획은 지워진 채로 남습니다. 문서를 열어 두면 20초마다 받아 합치고, 새 필기가 왔을 때만 알립니다.
• PDF에 굽기: 주석이 박힌 PDF를 원본에 다시 씁니다(그 사이 남이 고쳤으면 덮어쓰지 않고 알립니다). 크롬처럼 파일 핸들을 주는 브라우저는 연 파일에 그대로 덮어쓰고, 사파리·iOS는 이름-필기.pdf를 내려받습니다.
• 내보내기: 같은 PDF를 공유 시트로. 글자는 고를 수 있는 채로 남고 필기만 위에 얹히며, 마스킹한 쪽만 통째 그림으로 구워 가린 글자를 지웁니다.
• 다른 이름으로 저장: 드롭박스의 원하는 폴더에 사본(필기 없이 · 옆 파일로 · 구워서).

링크

PDF에 들어 있던 링크는 잠금(보기)일 때 눌러 따라갑니다(http·https·mailto만). 자리는 옅은 하늘색으로 보이고, 설정에서 표시만 끌 수 있습니다. 굿노트 export처럼 파일 안에서 이미 목적지가 끊긴 링크는 길게 눌러 「이 문서의 몇 쪽」이나 웹 주소로 고칩니다 — 같은 곳을 가리키던 링크 전부를 한 번에 고칠 수도 있습니다. 고친 목적지는 쪽 자체를 가리키고, 사이드카에 담겨 다른 기기까지 따라가며 굽기·내보내기 때 파일에 박힙니다. 확인은 node scripts/inspect-links.mjs 문서.pdf.

기기와 저장 공간

• 열 수 있는 PDF 크기는 기기 메모리에 따라 80 · 120 · 200MB입니다(브라우저가 메모리를 알려 주지 않으면 가장 조심스러운 쪽).
• 첫 화면은 목록 보기와 표지 보기를 오갑니다. 표지는 1쪽을 그려 캐시하고, 제목은 표지 아래에 옵니다.
• 카드마다 문서 크기와 ✕(지우기)가 있고, 아래에 로컬 문서 모두 지우기가 있습니다. 지울 때는 배너로 한 번 더 묻습니다(이 앱은 브라우저 대화상자를 쓰지 않습니다).
• 맨 아래 줄에 이 기기에 얼마를 썼고 얼마가 남았는지 나옵니다(브라우저가 알려 주는 경우).
• 저장 공간이 차면 다시 그리면 그만인 미리보기 캐시를 먼저 비우고 저장을 다시 시도합니다.

설정

항목	하는 일
툴바 위치	위·아래·왼쪽·오른쪽·떠 있게 (그립을 끌어도 됩니다)
보기	페이지 넘김 ↔ 세로 스크롤
펜만	S펜·애플펜슬만 그리기, 손가락은 이동
이 문서 썸네일 올리기	쪽 그림을 드롭박스에 함께 두고 다른 기기에서 한 번 내려받기
링크 자리 표시	링크 자리의 하늘색 표시
스티커 동기화	안 함 · 드롭박스 · 드라이브
배율 고정	핀치가 배율을 바꾸지 않게

키보드와 손가락

Ctrl/Cmd + C · V · X · Z	복사 · 붙여넣기 · 잘라내기 · 되돌리기 (다시 실행은 Ctrl+Shift+Z 또는 Ctrl+Y)
Space (누르는 동안)	손바닥
Ctrl + 휠 · 헤더의 ＋/－	확대·축소 (PC)
화살표 / Shift·Alt + 화살표	고른 것 밀기
두 손가락	확대·이동 (0.7~8배, 멈추면 그 배율로 다시 그려 또렷하게)
빠르게 튕기기	관성으로 쪽이 넘어갑니다

바깥 앱에서 복사한 것은 Ctrl+V가 가장 잘 붙습니다 — 브라우저의 클립보드 읽기는 몇 형식만 내주지만 진짜 붙여넣기는 원본 앱이 넣은 것을 그대로 들고 오기 때문입니다. 굿노트처럼 필기를 앱 안에만 담는 앱은 어떤 웹앱도 읽을 수 없어서, 그럴 땐 그렇다고 알려 주고 이미지로 내보내 끌어다 놓으라고 안내합니다.

설치 (PWA)

브라우저의 설치(홈 화면에 추가)로 앱처럼 씁니다. 주소창이 사라져 종이가 넓어지고, 앱 껍데기와 PDF 엔진이 캐시돼 오프라인에서도 최근 문서를 엽니다. 새 버전이 준비되면 한 줄로 알리고 새로고침할 때 바뀝니다. 문서를 처음 열 때 저장공간 유지를 한 번 요청합니다 — 필기는 이 기기에만 있으니까요.

---

개발

npm install
npm run dev      # http://localhost:5173
npm test         # node --test (순수 모듈 + 계약 테스트)
npm run build && npm run preview
npm run smoke    # 빌드한 dist를 진짜 크로미움으로 — 열기·링크·펜·되돌리기·성능 예산
npm run notices  # 서드파티 표시 다시 만들기

npm run smoke는 CI(GitHub Actions의 smoke 잡)가 매 PR마다 돌립니다. 로컬에서 돌리려면 npx playwright install chromium으로 크로미움을 받거나, 이미 있는 실행 파일을 SMOKE_CHROME으로 가리킵니다(루트 없이 apt-get download로 받은 라이브러리는 SMOKE_LD). /tmp가 작은 tmpfs라 차 있으면 크로미움 렌더러가 조용히 죽으니 TMPDIR를 넉넉한 곳으로 두세요.

• src/main.js가 DOM과 이벤트를 배선하고, 나머지 순수 모듈 47개가 각자 *.test.js를 답니다. 배선·디자인 수치는 정규식 계약 테스트로 못 박습니다.
• 작업 규칙(이슈 → 브랜치 → PR → 스쿼시 머지)은 CLAUDE.md에 있습니다.

클라우드 키

드롭박스 App key는 코드에 들어 있어 바로 됩니다. 구글 드라이브는 값 두 개가 필요하고, 없으면 「구글 드라이브에서 열기」 버튼이 아예 보이지 않습니다.

VITE_GOOGLE_CLIENT_ID=...apps.googleusercontent.com
VITE_GOOGLE_API_KEY=AIza...

로컬은 .env.example을 .env.local로 복사해 채우고, 배포는 Vercel 환경변수에 같은 이름으로 넣고 재배포합니다(빌드 때 박힙니다). 둘 다 브라우저에 노출되는 공개값이라 시크릿이 아니며, 보호는 승인된 JavaScript 원본과 리퍼러 제한으로 합니다. 그래서 저장소에는 넣지 않습니다.

배포

Vite 정적 호스팅만 씁니다. vercel.json이 빌드·출력(dist)·SPA fallback과 **콘텐츠 보안 정책(CSP)**을 지정합니다 — 스크립트는 우리 것만, 연결은 드롭박스·드라이브 원본만 허용합니다. 서버·로그인·시크릿은 없습니다.

문서

docs/PRD.md	제품 정의 — 원칙, 되는 것, 아직 아닌 것
docs/ARCHITECTURE.md	구조와 UML(컴포넌트·모델·열기/저장 흐름)
docs/PROCESS.md	이슈별로 무엇을 왜 그렇게 했는지의 기록
docs/LICENSES.md	무엇이 실려 나가고 왜 섞어도 되는지
docs/BOARD.md	이슈 보드

라이선스

GNU AGPL-3.0-or-later (LICENSE). 자유롭게 쓰고 고치고 나눠 주되, 고친 것을 웹에서 서비스하면 그 소스도 같은 라이선스로 공개해야 합니다(13조). 그냥 쓰는 사람에게는 아무 의무가 없고, 가져가서 자기 서비스로 다시 파는 경우에만 걸립니다. 그래서 앱 화면에 소스 링크를 둡니다.

「필기웹」·「pdf-ink」라는 이름과 아이콘은 라이선스에 포함되지 않습니다. 포크는 다른 이름을 쓰세요.

함께 쓰는 것: pdfjs-dist(Apache-2.0), pdf-lib(MIT)와 그 의존성(MIT·Zlib·0BSD), workbox-window(MIT) — 모두 AGPL 안에 넣을 수 있습니다. 저작권 표시는 public/THIRD-PARTY-NOTICES.txt에 모아 앱의 다른 코드 링크로 엽니다.