chore(fig-extract): v2.19.1 cropCanvas 제거 계약 반영 + 벤더링 버전 핀

[onetwothr1]

엔진 repo가 v2.19.1에서 figure.cropCanvas 필드와 cropCanvas() 접근자를 제거했다 ([BREAKING]). 이 PR은 그 계약 변경을 타입·테스트·문서에 반영한다.

엔진 벤더링은 하지 않음 — src/core/fig-extract.js는 v2.14.0 그대로고 추후 벤더링은 별도 PR.

왜 지금 타입만 고치는가

cropCanvas를 호출하는 코드가 이 repo에 하나도 없다. tab-figures.ts는 cropDataURL만 쓰고, 애초에 Pick<FigExtractApi, 'extract' | 'cropDataURL'>로 API를 좁혀 놨다. 나머지 등장 위치는 전부 타입 선언과 테스트 더미({} as HTMLCanvasElement)였다.

운영 원칙을 문서에 명시했다: 선언 타입은 벤더링 런타임이 실제로 제공하는 것의 부분집합으로 유지한다 — 제거는 지금, 추가는 벤더링과 함께. 근거는 두 방향의 실패 방식이 다르기 때문이다.

• 좁히기는 컴파일 타임에 요란하게 실패한다 — 누가 그 필드를 쓰고 있었다면 이 PR에서 타입 에러가 난다.
• 넓히기는 런타임에 조용히 실패한다 — 컴파일도 배포도 되고 아무 일도 안 일어난다.

그래서 v2.15.0~v2.19.1이 추가한 captionPage·onDiagnostic·cropImages는 타입에 넣지 않고 「다음 벤더링 할 일」로 남겼다.

변경

• src/core/fig-engine.ts — EngineFigure.cropCanvas 필드 · FigExtractApi.cropCanvas 메서드 제거
• VENDORED_ENGINE_VERSION 상수 + 검사 테스트 신설 — 벤더링하면 테스트가 깨져 할 일 목록으로 돌려보낸다. 버전 스큐를 날짜 박힌 문단이 아니라 테스트가 지키게 하려는 것
• docs/fig-extract-integration.md — §크롭 이미지 수명 재작성, 버전 스큐 절 신설, 「다음 벤더링 할 일」 5항목, 「벤더링과 무관한 선재 결함」 분리
• 테스트 더미 5곳 정리. toFigureEntries의 shape 단언은 surplusEngineField로 보강했다 — 더미 제거로 rest-spread 리팩터를 못 잡게 되는 걸 막는다

알아 둘 것 — 지금 이 확장에도 같은 결함이 있다

엔진 백로그 B7의 원인은 Chrome이 메모리 압력에서 캔버스 백킹 스토어를 예외 없이 회수하는 것이다. 회수된 캔버스는 그리기가 전부 무성과로 끝나고 읽으면 전면 투명이다.

벤더링본 v2.14.0은 figure마다 cropCanvas를 만들어 문서 스캔이 끝날 때까지 들고 있고(tab-figures.ts가 cropDataURL을 렌더 시점에야 부른다), FigRenderError도 없다. 즉 같은 상황에서 오류도 재시도 버튼도 없이 프리뷰 카드가 백지로 뜬다. 엔진 전수 배치에서는 한 논문 크롭 23장이 통째로 백지 PNG가 됐고 그게 출하본에까지 들어갔다.

문서에 이 사실과, 벤더링 전까지 유효한 주의 두 가지를 남겼다.

• v2.14.0의 cropDataURL은 f.cropCanvas를 읽는 순수 접근자다. 엔진이 준 figure 객체를 그대로 넘겨야 한다 — 선언된 필드만으로 재구성하거나 structuredClone/JSON 왕복을 거치면 타입은 통과하고 런타임에서 죽는다. M3의 storage 저장 작업이 정확히 이 함정을 부른다.
• tab-figures.ts가 signal을 넘기지 않아 문서 교체 시 이전 스캔이 계속 돈다. 스캔 두 개가 동시에 돌면 크롭 세트가 두 벌 상주해 이 결함의 발생 확률을 호스트가 스스로 올린다. 엔진 버전과 무관한 선재 결함이라 벤더링을 기다릴 이유가 없다.

검증

npm run typecheck:win exit 0 · vitest run 27/27 · npm run build:win exit 0 · dist/ 무변화

🤖 Generated with Claude Code

Summary by CodeRabbit

• 변경 사항

  • 벤더링 엔진 버전과 타입 정의 간 차이, 크롭 처리 방식 및 관련 제한 사항을 문서화했습니다.
  • cropCanvas 공개 API를 제거하고 크롭 결과는 데이터 URL 또는 Blob 방식으로 제공합니다.
  • 잘못된 렌더링 결과를 감지하면 FigRenderError로 처리되는 동작을 명확히 했습니다.
  • 캡션·페이지 레이아웃 지원 범위와 향후 보완 항목을 문서에 추가했습니다.

• 테스트

  • 엔진의 추가 필드가 결과 데이터에 노출되지 않는 동작을 검증하도록 테스트를 강화했습니다.

[coderabbitai]

📝 Walkthrough

Walkthrough

벤더링 엔진 버전과 선언 타입/API의 차이를 정리하고, cropCanvas 공개 계약을 제거했다. 크롭·렌더링 규약과 후속 작업을 문서화했으며, figure 변환 테스트를 새 타입 표면에 맞게 갱신했다.

Changes

엔진 계약 및 통합 문서

Layer / File(s)	Summary
엔진 버전과 공개 계약 정렬 src/core/fig-engine.ts	벤더링 버전 상수를 추가하고 EngineFigure와 FigExtractApi에서 cropCanvas 선언을 제거했으며, FigRenderError 거부 조건을 문서화했다.
벤더링 스큐와 런타임 규약 문서화 docs/fig-extract-integration.md	엔진 버전 스큐, 크롭 직렬화 규약, 렌더 실패 조건, 후속 벤더링 작업 및 기존 AbortController 배선 결함을 기록했다.
figure 변환 테스트 갱신 test/fig-engine.test.ts, test/tab-figures.test.ts	선언되지 않은 엔진 필드의 FigureSeed 누출 여부를 검증하고 cropCanvas 없는 figure 모킹을 반영했다.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• enu3379/PDFViewer#2: 초기 fig-extract/fig-engine 통합 이후 타입과 API 표면을 추가로 조정한 후속 변경이다.
• enu3379/PDFViewer#23: EngineFigure의 캔버스 처리 스키마와 관련 타입, API, 테스트, 문서를 함께 조정했다.

Suggested reviewers: enu3379

Poem

깡충 토끼 엔진 버전을 세고
낡은 캔버스 계약은 살며시 놓고
새 타입 들판을 정돈했네
숨은 필드도 새지 않게
문서와 테스트 함께 뛰네 🐇

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	주요 변경인 cropCanvas 계약 반영과 벤더링 버전 고정이 잘 드러나는 구체적인 제목입니다.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/fig-extract-crop-canvas-contract

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}