pdfcraft 딥다이브
— PDF 한 장을 고치며 배우는 Rust 앱의 속사정

1프로젝트 한줄 요약

PdfCraft는 Rust로 만든 오픈소스 PDF 읽기·편집 앱입니다. 페이지 보기와 검색, 회전·삭제·병합·분할, 주석, 양식, 암호화 같은 작업을 다룹니다. 데스크톱 앱뿐 아니라 명령줄 도구와 WebAssembly 웹 앱도 같은 저장소에 들어 있습니다.

이 저장소의 핵심은 PDF 기능의 개수보다, 하나의 편집 엔진을 여러 사용 방식에서 재사용하는 구조입니다. 사람이 메뉴를 누르든 자동화 도구가 JSON을 보내든, 문서를 바꾸는 핵심 처리는 crates/engine에 모입니다.

세 진입점은 apps/pdfcraft, apps/pdfcraft-cli, apps/pdfcraft-web입니다. 사용자 인터페이스는 crates/ui-egui, 자동화는 crates/automation이 담당합니다. 웹 서비스를 만들 때 익힌 프론트엔드·백엔드 구분을 그대로 적용하면 헷갈립니다. 여기서 엔진은 주로 사용자 기기 안의 라이브러리로 실행됩니다.

초보자가 따라갈 첫 번째 기능: 페이지 회전

1. 자동화 도구 page_rotate가 사용자 기준 페이지 번호와 각도를 받습니다.
2. Automation::call()이 인자를 확인하고 Edit::RotatePages로 연결합니다.
3. Session::apply()가 작업용 문서에서 수정하고 실행 취소 상태를 남깁니다.
4. organize::rotate_pages()가 페이지 사전의 /Rotate를 바꿉니다.
5. 변경 내용을 바이트로 만들어 화면을 갱신하고, 별도의 저장 요청 때 파일에 기록합니다.

따라서 “90도 회전”은 화면 이미지를 돌리는 효과만을 뜻하지 않습니다. PDF의 회전 속성을 수정하는 편집과 현재 보기를 돌리는 동작은 구분해야 합니다. 이 구분이 문서 모델과 화면 상태를 나누는 출발점입니다.

2왜 주목받는가

TrendShift Monthly #14 선정 대상이며, 2026-10-23 GitHub 기준 스타 17,301, 포크 6,644입니다. 저장소 생성일은 2026-09-30으로 분석일까지 23일입니다. 매우 짧은 공개 이력에 관심이 모였다는 사실은 읽을 수 있지만, 생성일을 개발 시작일로 보거나 스타를 품질 점수로 바꾸어 해석할 수는 없습니다.

주목 요인으로 해석할 수 있는 부분은 세 가지입니다. 첫째, 익숙한 PDF 편집 문제를 Rust로 풀어 내부를 공개합니다. 둘째, 데스크톱·웹·자동화를 하나의 코드 기반으로 묶습니다. 셋째, 실행 취소·증분 저장·파일 교체처럼 눈에 잘 안 보이는 신뢰성 문제를 구현과 테스트로 드러냅니다. 이는 기능과 구조에 근거한 해석이며, 이용자 설문이나 유입 경로로 확인한 인기 원인은 아닙니다.

다른 선택지와 비교할 때 볼 지점

이 표는 제품별 모든 기능이나 속도를 판정하는 벤치마크가 아닙니다. PdfCraft의 실질적 장점은 처리 흐름을 관찰하고 바꿀 수 있는 범위입니다. 특히 PDF 라이브러리와 앱 사이에 어떤 상태·검증·운영 코드가 필요한지 보여 줍니다.

“순수 Rust로 처음부터”라는 소개를 정확히 읽기

GitHub 설명과 README는 Rust 구현을 강조합니다. 실제 앱·엔진은 Rust 중심이지만, crates/render/src/lib.rs는 현재 페이지 렌더링에 hayro, 검사·호환성 보완에 lopdf를 사용하는 초기 구현 단계라고 밝힙니다. 루트 Cargo.toml의 [patch.crates-io]와 vendor/도 이를 뒷받침합니다.

“Rust로 작성했다”와 “PDF 처리의 모든 부품을 독자 구현했다”는 서로 다른 주장입니다. 이 차이를 읽는 것이 오픈소스를 평가하는 좋은 훈련입니다. 의존성을 숨기는 대신 교체 경계를 둔 구조 자체도 배울 만합니다.

3기술 스택 전체 지도

루트 Cargo.toml은 resolver = "3", edition = "2024", 워크스페이스 버전 0.13.0, rust-version = "1.95"를 선언합니다. 실제 하위 패키지는 crates/ 33개, apps/ 3개, xtask 1개로 총 37개입니다. vendor는 워크스페이스 멤버에서 제외되지만 패치 의존성으로 사용됩니다.

이 프로젝트의 “백엔드”는 HTTP 서버보다 문서 처리 엔진에 가깝습니다. 별도 데이터베이스나 서버 애플리케이션을 필수로 두지 않습니다. 프론트엔드도 React·Tauri·Electron이 아니라 Rust의 egui 계열입니다.

① 엔진·문서 처리

Cargo.lock에는 skrifa 0.42.1·0.44.0·0.47.0처럼 같은 이름의 여러 버전도 있습니다. 따라서 잠금 파일에서 이름 하나만 검색해 “앱의 버전”이라고 단정하면 안 됩니다. 먼저 해당 크레이트의 의존성 선언을 찾으세요.

② 화면·운영체제 연결

PDF를 픽셀로 만드는 단계와 그 픽셀·버튼을 창에 그리는 단계는 다릅니다. crates/render/src/lib.rs는 hayro-interpret와 vello_cpu 경로를 설명합니다. wgpu가 의존성에 있다고 PDF 해석 전체가 GPU에서 실행된다고 읽으면 안 됩니다.

③ 인프라·빌드·검증

스택을 읽을 때는 라이브러리 이름보다, 어느 계층이 어떤 기능을 켜서 사용하는지를 함께 보아야 합니다. 예를 들어 CLI의 MCP는 기본 빌드 기능에 포함되어도, 서버 실행은 pdfcraft-cli mcp를 명시적으로 호출해야 시작됩니다.

4아키텍처 심화 분석

전체 시스템 구조

계층 번호의 근거는 xtask/src/layers.rs의 TABLE입니다. 기초 도구 L0, 객체 계층 L1, 모델 L2, 렌더링·양식 L3, 편집 기능 L4, 엔진 L6, UI·플랫폼·자동화 L7로 구분합니다. 표에는 미래용 이름도 있으므로, 이름이 등록되었다고 해당 크레이트가 실제 존재하는 것은 아닙니다.

UI_MIN_LAYER = 7은 낮은 계층에 UI 도구가 들어오는 일을 막는 기준입니다. cos의 내부 의존성 허용 목록도 filters·crypt·geom으로 제한합니다. 설계 문구를 넘어서 검사 가능한 규칙으로 만든 점이 중요합니다.

패턴 1. 파사드와 명령 목록: 같은 규칙으로 들어오는 여러 문

파사드는 복잡한 내부 기능 앞에 두는 공통 출입구입니다. crates/engine/src/lib.rs의 Session은 열린 문서와 편집 기록을 관리합니다. GUI의 PdfCraftApp::apply_edit()는 self.session.apply(id, edit.clone())를 호출합니다. 자동화도 동일한 Session을 소유합니다.

crates/engine/src/commands.rs의 CommandSpec·Needs는 명령의 이름·단축키·실행 조건을 표현합니다. Needs::Undo처럼 실행 가능 조건을 데이터로 두면 메뉴와 자동화가 공통 기준을 참고할 수 있습니다. 모든 UI 상태가 엔진에 들어가지는 않습니다. 확대율·다음 검색 결과처럼 보기 전용 동작은 화면 상태에 남습니다.

자동화 쪽의 crates/automation/src/tools.rs는 별도의 도구 정의표입니다. ToolDef에는 input_schema, read_only, destructive, 대응 명령 command가 있습니다. 명령 목록과 도구 목록은 연결되지만 동일한 자료구조는 아닙니다.

// crates/automation/src/lib.rs의 Automation::call() 일부
let def = tools::find(name).ok_or_else(|| ToolError::UnknownTool(name.into()))?;
tools::check_args(def, args)?;
// 이후 도구별 분기에서 엔진 기능을 호출합니다.

schema()는 additionalProperties: false를 넣습니다. 인자 오타를 무시하지 않고 오류로 처리하겠다는 계약입니다. crates/automation/src/mcp.rs의 McpServer::serve()는 표준입력에서 한 줄씩 읽어 JSON-RPC로 해석하고 표준출력으로 응답합니다. HTTP 포트를 열지 않습니다.

패턴 2. 작업 사본과 상태 스냅샷: 성공한 편집만 채택하기

cos::Document는 원본 바이트를 Arc<Vec<u8>>로 공유하고, 바뀐 객체를 overlay: BTreeMap<u32, Slot>에 따로 보관합니다. 변경하지 않은 큰 데이터는 공유하고 변경분만 따로 갖는 방식이 복사 시 쓰기입니다.

Session::apply()는 먼저 editor.cos.clone()으로 작업 사본을 만든 뒤 run_edit()를 실행합니다. Document::clone()이 항상 비용 0인 것은 아닙니다. 바이트와 객체 등은 공유하지만 overlay 맵과 일부 메타데이터의 복사 비용은 남습니다.

// crates/engine/src/lib.rs, apply()의 서로 떨어진 핵심 단계
let mut next = editor.cos.clone();
// run_edit(&mut next, ...)가 성공한 뒤 이전 상태와 교환합니다.
let previous = std::mem::replace(&mut editor.cos, next);
// 이전 상태와 암호 키·갱신 범위를 실행 취소 기록에 함께 넣습니다.
editor.undo.push((label, previous, previous_keys, scope));

문서별 실행 취소 상한은 MAX_UNDO = 100입니다. 새 편집이 성공하면 redo 목록을 비웁니다. undo()와 redo()는 현재 상태와 보관 상태를 교환합니다. 단순히 “반대 명령”을 계산하지 않으므로, 복잡한 편집도 상태로 되돌릴 수 있습니다.

갱신한 문서를 표시할 수 없으면 apply()는 이전 상태를 복구하고 오류를 반환합니다. 다만 이것을 데이터베이스의 완전한 트랜잭션이나 외부 부작용 전체의 원자성으로 확대해 읽으면 안 됩니다. 이 경계가 보호하는 대상은 엔진의 문서 편집 상태입니다.

좋은 반례도 있습니다. crates/organize/src/lib.rs의 delete_pages() 주석은 함수 자체가 트랜잭션을 보장하지 않으며 실패 시 일부 변경이 남을 수 있다고 밝힙니다. 그래서 상위 엔진이 작업 사본을 사용하는 것입니다. 안전한 동작은 모든 함수가 아니라 적절한 경계에서 완성됩니다.

패턴 3. 증분 저장과 원자적 교체: 내용과 파일을 따로 보호하기

crates/cos/src/writer.rs의 write_incremental()은 원본 뒤에 수정 객체와 새 교차 참조 정보를 붙입니다. 새 trailer의 /Prev는 이전 교차 참조 구역을 가리킵니다. 기존 객체의 모든 속성을 새 스키마로 재생성하지 않아 모르는 데이터를 보존하는 데도 유리합니다.

하지만 write_incremental()의 맨 앞에는 예외가 있습니다. reconstructed(), encryption_changed(), full_save_required() 중 하나가 참이면 write_full()로 넘어갑니다. 손상 파일 복구, 암호화 변경, 민감 내용 삭제에는 전체 재작성이 필요할 수 있습니다.

// crates/cos/src/writer.rs의 실제 분기
if doc.reconstructed() || doc.encryption_changed() || doc.full_save_required() {
    return write_full(doc, opts);
}

여기서 가림 표시와 실제 삭제를 구별할 수 있습니다. 민감한 글자 위에 검은 사각형을 그려도 원본 내용은 남을 수 있습니다. 삭제를 적용한 뒤 예전 revision을 파일에 남기는 것도 위험하므로, 전체 재작성 여부가 보안 의미를 가집니다.

Automation::doc_save_with()는 같은 파일이면 기본적으로 증분 저장, 새 경로면 기본적으로 전체 저장을 선택합니다. 이어 publish_save()가 Session::check_save() → 파일 쓰기 → mark_saved() 순서를 지킵니다. “검사했지만 저장은 실패한 상태”와 “저장 완료 상태”를 섞지 않는 순서입니다.

파일 교체는 crates/platform/src/staging.rs의 write_atomically()가 담당합니다. 대상 옆에 create_new(true)로 임시 파일을 만들고, 내용을 기록·동기화한 뒤 이름을 바꿉니다. 이미 존재하는 임시 이름을 열어 덮어쓰지 않습니다. 파일 내용의 동기화는 수행하지만, 정전 때 부모 디렉터리의 이름 변경까지 영속화된다는 보장은 주석에 명시적으로 제외되어 있습니다.

증분 저장은 문서 내용을 어떻게 구성할지의 문제이고, 원자적 저장은 완성된 파일을 어떻게 교체할지의 문제입니다. 서로 다른 실패를 막으므로 두 가지가 함께 필요합니다.

패턴 4. 제한된 작업 큐: 지금 필요한 화면을 먼저 그리기

큰 PDF에서 모든 페이지를 최고 해상도로 동시에 그리면 메모리와 응답성이 무너집니다. crates/render/src/raster.rs의 RenderPool은 렌더 요청을 처리하고, RenderRequest는 페이지·배율·타일·종류·태그를 담습니다. RequestKind는 픽셀 요청과 텍스트 요청을 구분합니다.

crates/render/src/raster/work_queue.rs의 WorkQueue::replace()는 새로 필요한 요청 목록으로 교체하고 중복을 제거합니다. 필요 없어진 완료 결과도 버립니다. State::take()는 완료 순서만 따르지 않고 현재 요청 우선순위를 다시 봅니다. 페이지를 급히 넘겼을 때 과거 화면이 현재 화면보다 먼저 나오는 일을 줄이는 설계입니다.

완료 결과 보관 기준은 RESULT_BYTES = 32 * 1024 * 1024, RESULT_COUNT = 32입니다. pop()은 한도에 도달하면 새 작업을 꺼내지 않습니다. 다만 진행 중인 렌더링은 이 보관 예산 바깥이고, 큰 완료 결과 하나를 단독으로 허용하는 예외도 있습니다. 이 수치를 프로세스 전체 메모리 제한으로 읽으면 안 됩니다.

5디렉토리 구조 해부

위 트리의 crates/ 묶음은 실제 존재하는 33개 패키지입니다. 내부 파일까지 펼치지 않아도 “화면”, “엔진”, “문서 부품”, “검증·배포”가 갈린다는 점을 먼저 찾을 수 있습니다.

역할별로 처음 열 파일

줄 수가 큰 파일은 처음부터 끝까지 읽지 않아도 됩니다. 식별자를 검색해 정의·호출·테스트를 오가세요. apply처럼 흔한 이름은 경로를 좁힌 뒤 찾고, Edit::RotatePages처럼 고유한 이름은 저장소 전체에서 찾는 편이 효율적입니다.

# 저장소 루트에서 읽기만 하는 탐색 명령
rg -n 'pub fn apply|pub fn undo|pub fn save_bytes' crates/engine/src/lib.rs
rg -n 'RotatePages|page_rotate|fn rotate_pages' crates apps
rg -n 'check_save|mark_saved|write_atomically' crates/automation crates/platform
rg -n 'RESULT_BYTES|fn replace|fn take' crates/render/src/raster/work_queue.rs

코드 규모: 크다고 모두 앱의 독자 구현은 아닙니다

집계 기준은 커밋 0dc77fe의 확장자별 텍스트 줄 수이며 .git/는 제외합니다. 테스트·생성 데이터·주석·빈 줄을 포함하고, Markdown 문서는 위 코드 표에서 제외했습니다. TOML 15,087줄, YAML 계열 570줄도 vendor 바깥에서 확인되지만, 구현 언어와 설정을 섞지 않기 위해 따로 봅니다.

특히 crates/ui-egui의 Rust는 102,466줄, crates/engine은 23,505줄, crates/automation은 19,910줄입니다. 이 수치도 테스트를 포함한 폴더별 합계입니다. 작은 핵심 흐름부터 읽는 편이 30만 줄을 순서대로 읽는 것보다 이해에 도움이 됩니다.

6학습 포인트 (기술별)

① Rust 소유권: 큰 문서의 사본은 어떻게 관리할까?

Arc<T>는 여러 소유자가 같은 값을 공유하도록 하는 참조 카운트 포인터입니다. 여기서는 원본 PDF 바이트와 이미 읽은 객체를 여러 상태가 함께 보유합니다. 마지막 소유자가 사라질 때 데이터가 해제됩니다. Arc를 복제하는 것과 내부 Vec 전체를 복제하는 것을 구별해야 합니다.

읽을 파일은 crates/cos/src/document.rs입니다. Document의 data·cache·overlay를 나란히 보세요. 원본 공유, 파싱 결과 재사용, 편집 변경분 저장은 서로 다른 목적입니다. Mutex는 공유 가변 데이터에 접근할 순서를 조정합니다.

작은 실습: 종이에 원본 바이트 하나, 편집 상태 둘, undo 상태 하나를 그려 연결하세요. 상태를 하나 지웠을 때 원본이 해제되는지 설명해 보세요. 이후 crates/automation/src/text_cache.rs가 문서 버전에 Weak<Vec<u8>>를 쓰는 이유를 찾아보세요.

② 오류 처리: 실패해도 문서가 남게 하기

crates/render/src/lib.rs의 OpenError는 읽기 불가·암호 필요·암호 오류·지원 불가를 나눕니다. 자동화의 ToolError도 알 수 없는 도구, 잘못된 인자, 실행 실패를 구분합니다. 호출자가 다음 행동을 선택하려면 실패 종류가 표현되어야 합니다.

?는 오류를 호출자에게 전달합니다. 편집 경계의 guard()는 catch_unwind를 사용해 예기치 않은 panic을 오류로 바꾸는 마지막 방어선입니다. 무한 반복이나 프로세스 강제 종료까지 해결하는 장치는 아니므로, 입력 예산과 작업 감시도 따로 필요합니다.

작은 실습: page_rotate에 45도를 넣는 경우를 따라가세요. 자동화 계층은 degrees % 90을 검사하고, 낮은 계층의 rotate_pages()도 다시 검사합니다. 서로 다른 API 진입 경로에서도 계약을 지키기 위한 중복 검증입니다.

③ PDF 자료구조: 페이지는 왜 트리인가?

crates/model/src/lib.rs의 PageTree는 Iterator로 페이지를 방문합니다. seen: HashSet<ObjRef>는 같은 객체를 반복 방문하지 않게 합니다. 손상된 문서는 순환 참조를 가질 수 있어, 정상 트리라는 가정만으로 재귀를 쓰면 위험합니다.

상속 가능한 속성은 Resources·MediaBox·CropBox·Rotate 네 가지입니다. 부모가 선언한 값을 자식 페이지가 물려받습니다. 페이지 순서를 재구성할 때는 유효한 상속값을 보존해야 하므로 단순한 배열 재정렬보다 일이 많습니다.

작은 실습: 부모에 /Rotate 90, 첫째 자식에 회전값 없음, 둘째 자식에 /Rotate 180을 둔 트리를 그립니다. 두 페이지의 유효 회전이 무엇인지 적고, 부모를 없애도 같은 결과가 되려면 무엇을 자식에 복사해야 하는지 설명해 보세요.

④ 좌표와 변환: 화면의 왼쪽 위가 PDF의 원점일까?

자동화 API는 표시된 페이지의 왼쪽 위를 원점으로, 아래쪽을 y축 양의 방향으로 삼아 PDF 포인트 좌표를 받습니다. 반면 model::Page::view_matrix()와 view_matrix_for()는 왼쪽 아래가 원점이고 위쪽이 y축 양의 방향인 표시 좌표를 PDF 사용자 공간으로 변환합니다. 따라서 자동화 좌표에 이 행렬을 적용하려면 y축 방향 차이도 반영해야 합니다. 두 함수 중 앞의 함수는 페이지의 회전·표시 영역·UserUnit을, 뒤의 함수는 인자로 받은 회전·영역을 반영합니다.

// crates/model/src/lib.rs, view_matrix_for()의 90도 분기
90 => [0.0, 1.0, -1.0, 0.0, x1, y0],
// 여섯 값은 [a, b, c, d, e, f] 형태의 2차원 아핀 변환입니다.
// x' = a*x + c*y + e, y' = b*x + d*y + f

작은 실습: 너비 200, 높이 300인 페이지를 90도 회전하면 표시 크기가 300×200이 되는지 계산하세요. Page::display_size()는 회전뿐 아니라 /UserUnit도 반영합니다. 크기 계산과 좌표 변환을 분리해 확인하는 습관이 이미지·지도 앱에서도 유용합니다.

⑤ UI 설계: 문서 상태와 보기 상태 나누기

crates/ui-egui/src/lib.rs의 impl eframe::App for PdfCraftApp와 ui()를 읽어 보세요. 현재 상태를 바탕으로 화면을 구성하고, 문서 변경은 crates/ui-egui/src/editing.rs를 거쳐 엔진에 전달합니다. 즉시 모드 UI라고 해서 매 프레임 PDF를 처음부터 다시 파싱해야 하는 것은 아닙니다.

확대율·현재 탭·선택 영역은 보기 상태이고, 주석·양식값·페이지 순서는 저장할 문서 상태입니다. 둘을 섞으면 확대만 했는데 “저장하지 않은 변경”이 생기는 식의 버그가 나옵니다. 어떤 동작이 undo에 들어가는지도 이 경계와 연결됩니다.

작은 실습: “확대”, “페이지 회전 편집”, “검색 다음 결과”, “주석 추가”를 보기 상태와 문서 상태로 분류하고, 각 동작에서 파일 내용이 바뀌어야 하는지 써 보세요.

⑥ 자동화 API: 사람이 보는 번호와 코드의 인덱스

도구의 페이지는 1부터, 엔진에 전달하는 배열 인덱스는 0부터 시작합니다. Automation::call()의 회전 분기가 사용하는 self.pages()와 낮은 계층의 인덱스 검증을 연결해 보세요. 외부 인자를 바로 usize로 바꾸지 않는 이유도 이해할 수 있습니다.

검색 결과도 단순한 배열만이 아닙니다. text_find의 complete·next·warnings는 “다 읽었는가”, “이어 읽을 곳이 있는가”, “실패한 페이지가 있는가”를 구분합니다. 오류가 났는데 빈 결과로 숨기지 않는 API를 배울 수 있습니다.

작은 실습: 검색이 끝났지만 한 페이지 추출에 실패한 경우를 생각하세요. complete: false이며 next는 없을 수 있습니다. “완료가 아니면 무조건 next로 재요청”하는 클라이언트가 왜 틀리는지 설명해 봅니다.

⑦ 테스트: 결과보다 불변식을 먼저 정하기

invalid_save_bytes_never_reach_publication_or_mark_saved()는 저장할 바이트가 잘못되었을 때 쓰기 콜백이 호출되지 않았는지, 기존 파일과 문서 요약이 그대로인지 함께 확인합니다. 오류 문자열 하나보다 훨씬 구체적인 동작 계약입니다.

좋은 테스트는 “성공했다”만 확인하지 않고, 실패했을 때 무엇이 그대로 남아야 하는지를 확인합니다. 이 저장소에서 배운 원칙을 메모장·이미지 편집기·설정 파일 저장에도 적용할 수 있습니다.

7하드웨어 / 시스템 요구사항

모든 사용 방식에 적용되는 공식 최소 CPU·RAM·VRAM 수치는 README와 주요 빌드 설정에서 확인되지 않습니다. 대신 플랫폼 조건과 메모리를 제한하는 코드값은 확인할 수 있습니다. 아래에서 운영체제 정보는 README·패키징 설정, 메모리 수치는 소스 상수 또는 계산값입니다.

메모리는 파일 크기 하나로 결정되지 않습니다

2000×3000 픽셀 RGBA 버퍼 하나는 2000 × 3000 × 4 = 24,000,000바이트, 약 22.9 MiB입니다. 원본 PDF가 작아도 압축 이미지가 풀리고, 페이지 픽셀·글꼴 캐시·undo·작업 결과가 함께 살아 있으면 메모리는 훨씬 커집니다.

개별 버퍼와 캐시의 상한을 더해도 프로세스 전체의 최대 메모리를 보장하는 숫자는 나오지 않습니다. 실제 사용량은 문서 구조, 페이지 크기, 동시에 열린 문서와 작업 수에 따라 측정해야 합니다.

개발 빌드는 디버그 정보와 중간 산출물 때문에 디스크도 많이 씁니다. 루트의 [profile.low-disk]는 debug = "line-tables-only", incremental = false를 설정합니다. 용량을 줄이는 대신 재빌드 비용이 달라질 수 있다는 절충을 읽을 수 있습니다.

GPU와 웹 문서에서 확인할 차이

데스크톱의 apps/pdfcraft/src/main.rs는 기본 wgpu 시작이 실패하면 OpenGL을 시도하는 경로를 둡니다. PDFCRAFT_RENDERER=gl로 선택하는 코드도 있습니다. 따라서 GPU 표시 경로와 CPU 페이지 래스터화, 호환성 대체 경로를 함께 보아야 합니다.

packaging/web/README.md는 WebGPU → WebGL2 전환과 ?webgl·?cpu를 안내합니다. 그러나 커밋 0dc77fe의 apps/pdfcraft-web/src/main.rs는 eframe::Renderer::Glow를 지정하고, Cargo 기능도 glow를 켭니다. 이 진입점에는 해당 플래그의 렌더러 선택 분기가 확인되지 않습니다. 이 버전을 이해할 때는 소스에 보이는 경로를 기준으로 삼으세요.

웹 배포는 정적 파일을 제공하는 형태입니다. packaging/web/_headers는 WASM MIME을 application/wasm으로, 해시 파일 캐시를 1년·immutable로, index.html을 no-cache로 설정합니다. 배포 문서의 WASM 약 13 MB·압축 약 5 MB는 안내 수치이며 브라우저 실행 메모리와 다릅니다.

8직접 해볼 수 있는 실습 과제

각 과제는 작은 합성 문서나 연습용 복사본을 기준으로 합니다. 명령 예시는 해당 버전의 CLI 또는 개발 환경을 준비한 독자가 수행할 실습 절차입니다. 완료 기준을 먼저 읽고, 그 기준을 입증할 결과를 남기세요.

[
  {"tool":"doc_create","args":{"from":"blank","width":200,"height":300}},
  {"tool":"doc_save","args":{"doc":1,"path":"before.pdf"}},
  {"tool":"page_rotate","args":{"doc":1,"pages":[1],"degrees":90}},
  {"tool":"page_render","args":{"doc":1,"page":1,"dpi":96},"out":"after.png"},
  {"tool":"doc_save","args":{"doc":1,"path":"after.pdf","full":false}},
  {"tool":"edit_undo","args":{"doc":1}},
  {"tool":"doc_info","args":{"doc":1}}
]

# 모든 출력 경로는 --root 안쪽으로 제한합니다.
pdfcraft-cli run --script rotate.json --root ./practice --report

# 원본 바이트가 시작 부분에 보존되는지만 비교합니다.
python3 - <<'PY'
from pathlib import Path
before = Path('practice/before.pdf').read_bytes()
after = Path('practice/after.pdf').read_bytes()
print(after.startswith(before), len(before), len(after))
PY

완료 기준: 초기 200×300 포인트 페이지의 표시 방향이 바뀌고, after.pdf의 시작 부분에 before.pdf가 그대로 들어 있음을 확인합니다. 이는 합성 문서에서 증분 저장을 명시한 조건의 검사입니다. 전체 재작성이나 시각적 동일성까지 판정하지 않습니다.

더 생각하기: 새 경로 저장은 기본적으로 전체 재작성인데, 여기서는 왜 full: false를 넣었을까요? 마지막 undo는 메모리 상태에만 반영되므로 저장된 after.pdf가 저절로 원래 방향이 되는지도 구분해 보세요.

# 개발용 사본에서 organize 크레이트의 테스트 실행 예시
cargo test -p pdfcraft-organize -j 2

과제의 완성은 기능을 한 번 실행하는 데서 끝나지 않고, 성공과 실패의 경계를 설명할 수 있을 때 드러납니다.

9관련 기술 심화 학습 로드맵

이미 모든 기술을 알아야 시작할 수 있는 저장소는 아닙니다. 다만 30만 줄 이상의 Rust를 처음부터 읽는 방식은 피하는 편이 좋습니다. 아래 경로는 회전과 저장이라는 작은 기능을 계속 다시 보면서 필요한 배경을 늘리는 학습안입니다.

웹에 관심이 있다면 5주차 뒤 apps/pdfcraft-web/src/main.rs로 이동해 WASM과 브라우저 이벤트를 읽으세요. 시스템 프로그래밍에 관심이 있다면 cos의 파서 예산, filters의 압축 해제 한도, crypt의 암호화 경로로 확장할 수 있습니다.

테스트에 관심이 있다면 crates/testkit의 합성 문서와 crates/oracle의 외부 검증 도구 연결을 비교하세요. 자기 코드로 만든 파일을 자기 코드로만 읽으면 같은 오해를 공유할 수 있으므로, 다른 구현으로 확인하는 발상이 중요합니다.

학습 범위를 넓힐 때도 “이 기능의 입력·상태·실패·출력은 무엇인가”라는 같은 질문을 유지하세요. 기술 이름은 달라도 큰 프로그램을 읽는 방법은 반복됩니다.

10핵심 키워드 사전

11참고 링크

공식 저장소·사용 문서

• storytold/pdfcraft 공식 저장소 — 현재 개발과 이슈를 확인하는 출발점입니다.
• v0.13.0 릴리스 — 2026-10-23 기준 최신 릴리스입니다.
• 분석 기준 README — 기능 소개·플랫폼·보고된 검증 수치·알파 한계를 함께 읽으세요.
• ROADMAP.md — 앞으로의 우선순위입니다. 계획과 이미 배포된 기능을 구별합니다.
• MCP 문서 — 자동화 도구와 접근 범위 설정을 살펴볼 수 있습니다.
• 웹 배포 문서 — MIME·압축·캐시 설명을 읽되 렌더러 설명은 해당 커밋 소스와 대조하세요.
• 기능 대응 현황 — 프로젝트가 제시하는 기능 범위와 준비도를 확인할 때 참고합니다.
• TrendShift — 이 글의 선정 맥락은 Monthly #14입니다.

구현 근거를 바로 열기

• Cargo.toml · Cargo.lock — 선언 범위·선택 버전·vendor 패치를 비교합니다.
• crates/engine/src/lib.rs — Session::apply(), undo(), save_bytes(), check_save().
• crates/engine/src/commands.rs — CommandSpec와 Needs.
• crates/cos/src/document.rs · crates/cos/src/writer.rs — 객체 공유·overlay·증분·전체 저장.
• crates/model/src/lib.rs · crates/organize/src/lib.rs — 페이지 상속·좌표·회전·구조 변경.
• crates/automation/src/lib.rs · crates/automation/src/tools.rs · crates/automation/src/mcp.rs — 인자 계약과 공통 자동화 경로.
• crates/render/src/raster/work_queue.rs — 요청 교체·우선순위·완료 결과 보관 예산.
• crates/platform/src/staging.rs — 임시 파일 생성·동기화·교체와 실패 정리.
• 웹 진입점 · 웹 Cargo 설정 — Glow 선택과 브라우저 API 경계.
• 계층 검사 · CI 설정 — 설계 규칙을 자동으로 검사하는 방법.

관련 기술의 공식 학습 자료

• The Rust Programming Language — 소유권·오류 처리·스레드의 기초.
• Cargo 워크스페이스 문서 — 공통 의존성과 설정 상속.
• Rust 표준 라이브러리 Arc 문서 — 공유 소유권과 내부 값의 가변성 구분.
• egui 공식 저장소 — Rust UI와 eframe의 배경.
• hayro 공식 저장소 — 현재 렌더링 부품의 원본 프로젝트.
• lopdf 공식 저장소 — PDF 객체 처리 라이브러리.
• MCP 공식 문서 · JSON-RPC 2.0 명세 — 도구 인터페이스와 메시지 형식을 나눠 학습합니다.
• WebAssembly 공식 사이트 · Trunk 공식 문서 — Rust 웹 실행과 정적 파일 빌드.
• qpdf 공식 문서 · PDF Association — 독립 검증 도구와 PDF 표준 배경.

현재 상태 (2026-10-23 확인)

릴리스 날짜와 소스 커밋 날짜는 다른 기준입니다. 위 구현 설명은 0dc77fe에 고정되어 있으므로, 이후 push나 릴리스 바이너리의 변경을 자동으로 포함하지 않습니다. 파일 줄 수도 이 스냅샷의 값입니다.