PDF를 페이지별 배경 이미지로 깔고, 그 위에 텍스트·도형·직접 만든 객체를 레이어로 올리는 편집기와 뷰어. 프레임워크에 종속되지 않는다 — 렌더 층이 vanilla DOM 이고 React·Vue 래퍼가 같은 컴포넌트를 제공한다.

두 예제는 같은 패키지로 전혀 다른 앱을 만든다 — 레이아웃·다이얼로그·뷰어 모드·툴바 전략이 모두 다르고, 둘 다 편집기·뷰어·Ports·저장·검증·문항 3종을 풀세트로 쓴다.

화면의 </> 배지를 누르면 그 부분의 코드가 나온다. 상단 [테마 ON/OFF] 는 @layer 오버라이드가 실제로 이기는지 눈으로 확인하는 장치다.

무엇을 눌러 봐야 하는지, 어떤 기능이 어느 파일에 있는지는 예제 앱 두 개 에 정리했다.

npm install @h_domi/pdf-canvas-kit

아직 beta 다. prerelease 를 latest 태그로 올리므로 위 명령이 최신 beta 를 받는다.

// React
import { PDFCanvasEditor } from '@h_domi/pdf-canvas-kit/react'
import '@h_domi/pdf-canvas-kit/styles.css'

<PDFCanvasEditor initialDoc={doc} onChange={setDoc} />

<!-- Vue / Nuxt -->
<script setup>
import { PDFCanvasEditor } from '@h_domi/pdf-canvas-kit/vue'
import '@h_domi/pdf-canvas-kit/styles.css'
</script>
<template><PDFCanvasEditor :initial-doc="doc" @change="onChange" /></template>

// 프레임워크 없이 — imperative facade
import { createPDFCanvasEditor, createPDFCanvasViewer } from '@h_domi/pdf-canvas-kit'

const editor = createPDFCanvasEditor(container, { initialDoc: doc })
const viewer = createPDFCanvasViewer(other, { doc: editor.toPublicDoc() })

initialDoc 은 최초 1회만 읽는다. 편집기가 문서를 소유하고 onChange 로 밀어낸다 — controlled 가 아니다. 이름이 그 계약이다.

런타임 의존성은 pdfjs-dist 하나다. react · vue 는 optional peer 라 쓰는 쪽만 설치한다. 번들 크기는 코어 10.9KB + React 래퍼 3.5KB / Vue 래퍼 5.7KB + CSS 21.9KB. 패키지 전체는 140KB(압축) · 447KB(해제) 다 — 소스맵을 배포하지 않는다 (2026.08.25 실측).

이 둘을 빠뜨리면 에러 없이 조용히 잘못 동작한다.

pdf.js는 CMap·표준 폰트·wasm 을 런타임에 URL로 가져온다. 빠뜨리면 한국어 PDF에서 글자가 사라진다.

// package.json
"postinstall": "node -e \"const{cpSync}=require('fs');for(const d of ['cmaps','standard_fonts','wasm','iccs'])cpSync('node_modules/pdfjs-dist/'+d,'public/pdfjs/'+d,{recursive:true});cpSync('node_modules/pdfjs-dist/build/pdf.worker.mjs','public/pdfjs/pdf.worker.mjs')\""

configurePdfResources({
  workerSrc: '/pdfjs/pdf.worker.mjs',
  cMapUrl: '/pdfjs/cmaps/',              // ⚠️ 이것 없으면 한글이 사라진다
  standardFontDataUrl: '/pdfjs/standard_fonts/',
  wasmUrl: '/pdfjs/wasm/',
  iccUrl: '/pdfjs/iccs/',
})

.pck-editor 는 height: 100% 다. 확정 높이가 없으면 편집기가 접힌다.

html, body, #app { height: 100%; margin: 0; }
/* flex 안이면 min-height: 0 도 필요하다 */

자세한 것은 시작하기.

전체 사용 설명서는 docs/ 에 있다.

내부 구조는 따로 있다.

호스트 앱에 맞추는 길이 네 개다. 위에서부터 시도하면 대부분 첫 단계에서 끝난다.

/* 1. 토큰 — 색·간격·폭·모달 모양 */
.my-app .pck-editor {
  --pck-accent: #3b82f6;
  --pck-pagelist-width: 200px;
}

/* 2. CSS 규칙 — @layer 라서 단일 클래스가 이긴다. !important 불필요 */
.pck-toolbar { justify-content: center; }

{/* 3. 문구·아이콘 — 번역이나 아이콘 라이브러리 */}
<PDFCanvasEditor
  strings={{ 'toolbar.text': 'Text' }}
  renderIcon={{ undo: UndoIcon }}
/>

{/* 4. 다이얼로그 위임 — 내 모달을 쓴다 */}
<PDFCanvasEditor
  onRequestUpload={() => setMyUploadOpen(true)}
  onRequestConfirm={(req) => setMyConfirm(req)}
/>

{/* 5. 툴바를 내가 만든다 — 상태 스냅샷 + 명령 */}
const [handle, setHandle] = useState<EditorHandle | null>(null)
const state = useEditorState(handle)

<button disabled={!state?.canUndo} onClick={() => handle?.undo()}>되돌리기</button>
<PDFCanvasEditor ref={setHandle} />

스타일 · 문구 · 아이콘 · 다이얼로그 · 내 툴바 에 각각 자세히 있다.

패키지는 기본 틀(사각형·리사이즈·색)만 그린다. 그 안을 내 컴포넌트가 채운다.

const shortAnswer = defineObjectType<Answer, Omit<Answer, 'answers'>>({
  kind: 'answer.short',
  label: '단답형',
  defaultSize: { w: 160, h: 44 },
  defaultData: () => ({ answers: [], points: 1 }),
  validate: (d) => (d.answers.some((a) => a.trim()) ? null : ['정답을 입력하세요']),
  toPublic: ({ answers: _a, ...rest }) => rest,   // 뷰어에 나가면 안 되는 것
})

<PDFCanvasEditor
  objectTypes={[shortAnswer]}
  renderObject={{ 'answer.short': AnswerBadge }}       // 캔버스 — 미리보기
  renderInspector={{ 'answer.short': AnswerFields }}   // 인스펙터 — 편집
/>

핸들로 틀을 키우면 안쪽 컴포넌트가 자기 CSS 대로 다시 흐른다. 커스텀 객체.

배포됨 — 아직 beta 다. npm · 데모. 편집기와 뷰어 모두 React·Vue·vanilla 에서 쓸 수 있다. 남은 일은 docs/TODO.md 에 있다.

0.1.0 (안정판) 으로 올리는 조건은 실제 앱에 붙여 보는 것이다. 지금까지 붙여 본 것은 examples/ 둘뿐이다.

npm install
npm run dev      # 3100 데모(레포 소스) · 3101 React 예제 · 3102 Vue 예제

examples/* 는 별칭 없이 설치된 dist 를 쓴다 — exports 맵·진입점·.d.ts 를 검증하는 유일한 자리다. 패키지 소스를 고치면 npm run build 후 반영된다.

두 예제는 각 부분에 </> 배지가 있다 — 누르면 그 UI 가 어떻게 구현됐는지 코드가 나온다.

main 에 push 하면 Pages 워크플로가 세 사이트를 하나로 합쳐 배포한다 (/ · /react/ · /vue/).

자동 테스트 러너는 없다. 대신 npm run checks 가 커밋 전 게이트다 — 이유와 한계는 ARCHITECTURE §11. 줌·팬·스크롤·IME 는 실제 브라우저 레이아웃에 의존해 덮이지 않는다. 손으로 확인해야 한다.

자동 테스트 러너는 없다. npm run checks 가 커밋 전 게이트다 — 이유와 한계는 ARCHITECTURE §11. 줌·팬·드래그·한글 IME 는 실제 브라우저 레이아웃에 의존해 덮이지 않으므로 손으로 확인한다.

이 패키지는 MIT 다. LICENSE 참고.

MIT · Apache-2.0 · BSD · ISC · CC0 · 0BSD 만 허용한다. GPL/LGPL/AGPL/SSPL/상업 라이선스는 금지 — 이 패키지가 남의 제품에 임베드 배포되므로 copyleft 의무나 좌석 과금이 소비자에게 전염된다.

PDF 계열에 특히 함정이 많다: mupdf·iText 는 AGPL, PSPDFKit·PDFTron 은 상업 라이선스다. 런타임 의존성은 pdfjs-dist(Apache-2.0) 하나뿐이다. npm run license-check 로 검사한다.