[fix/MAT-542] handwriting dataJson 전환 — base64 wrapping 제거

[b0nsu]

Summary

5초 autosave 메인 스레드 4단계 직렬화(stringify → encodeURIComponent → unescape → btoa) 를 1단계 JSON.stringify 로 축소. dev 서버에 추가된 dataJson: string 필드 사용.

Stacked on #312 (MAT-524) — base: fix/mat-524-autosave-data-loss

Linear

• MAT-542 — handwriting 데이터 base64 wrapping 제거 (서버 합의 필요)

Changes

handwritingEncoder.ts

• canonicalize — Stroke / Point / TextItem 키 순서를 명시 재구성하여 byte-stable JSON 출력 보장 (동일 입력 → 동일 출력).
• encodeHandwritingData — 4단계 → 1단계 (JSON.stringify(canonicalize(...))).
• decodeHandwritingData — 응답 객체만 받는 단일 시그니처. dataJson 우선 → data(base64) fallback → 둘 다 없으면 빈값. 옛 strokes-only 배열 형식 호환 유지.
• parseHandwriting 내부 helper 분리.

useHandwritingManager.ts

• PUT body 를 { dataJson } 으로 (data 미포함) — 자연 마이그레이션.
• 응답 분기를 decodeHandwritingData(handwritingData) 로 단순화 (호출부에서 dataJson/data 분기 흡수).

schema.d.ts

• pnpm openapi 로 develop dev OpenAPI 동기화. ScrapHandwritingUpdateRequest / ScrapHandwritingResp 양쪽에 dataJson?: string 추가, data optional 화. 그 외 누적 schema drift 동시 반영.

Testing

• pnpm typecheck 통과
• pnpm lint 변경 파일 0 errors
• encoder 결정성 + canonicalize 검증 (node 인라인 4종 — 동일 입력 동일 출력, 키 reorder 후에도 동일, round-trip, 빈 입력)
• dev 빌드 동작 확인 (작성자 환경)
• 옛 base64 row 진입 → 한 획 추가 → 5초 autosave → PUT body { dataJson: "..." } 확인
• 새 dataJson row round-trip
• 빈 응답 → 빈 캔버스 (decodeError overlay 안 뜸)
• AppState background 진입 시 flushPending PUT 발화
• scrapId 빠른 전환 race — 이전 mutation 의 onSuccess 가 새 scrapId 캐시 오염 안 시킴 (queryKey 분리)
• strokes-only 옛 형식 row 진입 호환

Risk / Impact

• 영향 범위: 스크랩 상세 화면 필기 자동저장 / 로드
• 호환성: 옛 base64 row 는 decoder fallback 으로 한 번 디코드 → 다음 PUT 시 dataJson 으로 자연 전환. 마이그레이션 SQL 0건.
• 성능: 5초 autosave 메인 스레드 비용 4단계 → 1단계로 감소.
• 머지 순서: PR fix: handwriting API 캐시 전략 개선 #288 → PR [fix/MAT-524] 필기 자동저장 race 로 인한 백엔드 빈 PUT 회귀 fix #312 → 본 PR (stacked).

Follow-ups

• MAT-543 — autosave debounce + stroke count limit
• 향후 saveCoordinator / mutationCache 비교 로직 (PR [fix/MAT-524] autosave 데이터 유실 방지 #308 의 C1 해결책) 재도입 시, 본 PR 의 캐노니컬 인코더 덕분에 byte-equal 비교가 안전 작동

Screenshots / Video

(필요 시 디바이스 캡처 첨부)

[linear]

MAT-542 handwriting 데이터 base64 wrapping 제거 (서버 합의 필요)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
pointer-admin	Ready	Preview, Comment	May 5, 2026 0:30am

[Copilot]

Pull request overview

This PR updates the native scrap handwriting autosave/load pipeline to stop base64-wrapping handwriting payloads and instead persist/load plain JSON via the newly introduced dataJson field (with legacy data base64 fallback for reads). It also updates the generated OpenAPI TypeScript schema to reflect dataJson support and other upstream schema drift.

Changes:

• Replace handwriting save encoding from stringify → encodeURIComponent → unescape → btoa to a single deterministic JSON.stringify(canonicalize(...)).
• Simplify handwriting decode to accept the full API response object and prefer dataJson, falling back to legacy base64 data and older “strokes-only array” format.
• Update API schema typings to add dataJson?: string and make data optional for handwriting request/response types (plus additional OpenAPI sync changes).

Reviewed changes

Copilot reviewed 2 out of 3 changed files in this pull request and generated no comments.

File	Description
apps/native/src/types/api/schema.d.ts	Sync OpenAPI typings; adds dataJson/optional data for handwriting types and introduces additional schema drift updates.
apps/native/src/features/student/scrap/utils/handwritingEncoder.ts	Implement deterministic JSON encoding + unified decoder (dataJson preferred, data base64 fallback, strokes-only compatibility).
apps/native/src/features/student/scrap/hooks/useHandwritingManager.ts	Switch PUT body to { dataJson } and simplify load path to decodeHandwritingData(handwritingData).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.