feat: add .note → pdf conversion (complement existing .note → html)

[kiki830621]

Problem

Original text:
「.note轉成pdf的東西我覺得macdoc也要加」
— Source: Claude Code session 2026-04-17

macdoc 目前已有 .note → html 轉換（NoteConverter，讀 Session.plist 筆畫向量 + 掛 Recordings/ 音訊，產出互動式 HTML player），但還沒有 .note → pdf。建議補上這個轉換，走同一條資料路線（讀 Session.plist 筆畫），輸出靜態 PDF。

Type

feature

Expected

macdoc convert --to pdf input.note --output output.pdf

輸出含完整手寫筆畫的靜態 PDF，不需要在 iPad 上開 Notability App 手動「分享 → PDF」。

Actual

目前 .note → pdf 未實作，執行會回報「不支援從 .note 轉換到 pdf」。

取得 Notability 筆記 PDF 的現有路徑都有缺陷：

1. extract_notability_pdf.py（teaching-toolkit 的 lecture-add skill） — heuristic 有結構性漏洞
   • 只檢查 .note/PDFs/ 裡 PDF 的 size ≥ 500 KB、頁數 ≥ 3、含 Quartz PDFContext 標記
   • 但 iOS 所有原生 App（備忘錄、Pages、Safari⋯）匯出的 PDF 都帶 Quartz PDFContext 標記，無法單憑此判斷 producer
   • 結果：使用者匯入到 Notability 當底圖的「備忘錄匯出 PDF」被誤判為「Notability 完整筆記匯出」並被抓出
   • 根本問題：真正的手寫筆畫在 Session.plist（vector ink），根本不存在 .note/PDFs/ 裡。.note/PDFs/ 只存使用者匯入的底圖資源
2. Notability App「分享 → PDF」 — 需要 iPad/iPhone 在手，無法在 Mac 上批次處理

Impact

• Claude / LLM 教學分析：Claude 的 Read 工具會把 PDF 頁面 rasterize 成圖像餵給視覺模型，能直接「看」手寫內容。HTML 的 <canvas> 渲染結果無法被工具擷取——LLM 只能讀到原始 JS 和 stroke 座標點，拼不出視覺內容。所以 Claude 理解 Notability 筆記需要 PDF 格式。
• 列印 / 長期歸檔：PDF 跨平台可攜、能印出；HTML player 綁 JS 和錄音，不適合作為長期保存格式
• 具體實例：teaching/20260305_wei/lectures/05_20260410/筆記 2026-04-10 15_31_24.note 的 Session.plist 有 1.8 MB 筆畫資料，extract_notability_pdf.py 卻只抓到備忘錄底圖（PDF metadata Creator 欄位顯示「備忘錄」，不是 Notability），老師在 Notability 上的教學註記全部丟失

實作入口

Sources/MacDocCLI/MacDoc+Convert.swift:107 目前：

case ("note", "html"):
    try convertNoteToHTML(inputURL: inputURL)

建議補上：

case ("note", "pdf"):
    try convertNoteToPDF(inputURL: inputURL)

實作方向：重用 NoteToHTML 模組的 Session.plist 筆畫解析邏輯，但改用 Core Graphics (CGContext 的 PDF context) 繪製，而非 HTML Canvas。音訊部分在 PDF 中無法互動，可以：

• 略過音訊（純筆畫版）
• 或把錄音時間軸做成 PDF 側邊的時間標註（選配）

Notes

• 做完這個之後，teaching-toolkit/lecture-add/scripts/extract_notability_pdf.py 應改為呼叫 macdoc convert --to pdf，淘汰目前不可靠的 heuristic

[kiki830621]

Diagnosis

Type

feature

Analysis

Confirmed the existing infrastructure:

• NoteParser (packages/note-to-html-swift/Sources/NoteToHTML/NoteParser.swift, 351 lines) — parses .note ZIP bundles into ParsedNote struct with: StrokeData (curves with [(x, y)] + color + width), NoteImage[] (embedded images with position/size), RecordingInfo[], page dimensions, multi-page support
• StrokeDecoder (169 lines) — decodes binary stroke data from Session.plist into [Curve]
• NoteConverter — takes ParsedNote → HTML <canvas> rendering with JS playback. NOT reusable for PDF (output is JS, not graphics calls)
• PlayerTemplate (572 lines) — HTML template with embedded JS. Not relevant for PDF

What needs to happen: reuse NoteParser + StrokeDecoder for data extraction, then render via CGContext (Core Graphics PDF context) instead of HTML Canvas. Each Curve → CGContext.addLines(between:) with RGBA color + line width. Each NoteImage → CGContext.draw(cgImage, in: rect). Multi-page → CGContext.beginPDFPage() for each page.

Architecture question: where does the PDF renderer live?

Option	Approach	Trade-off
A. Add to note-to-html-swift	New NoteToPDFRenderer.swift in existing package. Rename package?	Simple dep management but package name becomes misleading ("html" but also does PDF)
B. New package note-to-pdf-swift	New Layer 3 converter depending on note-to-html-swift for NoteParser/StrokeDecoder	Clean separation but NoteParser is only public for HTML right now — need to re-export or move to a shared package
C. Extract note-core-swift	Move NoteParser + StrokeDecoder + TimelineDecoder into a shared Layer 1 package; both html and pdf converters depend on it	Cleanest architecture but requires refactoring the existing note-to-html-swift and updating macdoc Package.swift

Recommendation: Option C — same pattern as ooxml-swift (Layer 1 parser) + word-to-md-swift / word-to-html-swift (Layer 3 converters). Extract parsing to note-core-swift, keep HTML in note-to-html-swift (now lighter), add note-to-pdf-swift. This is the "macdoc way" per the architecture docs.

Impact

• New package: packages/note-core-swift/ (Layer 1 — parser + stroke decoder + models)
• New package: packages/note-to-pdf-swift/ (Layer 3 — CGContext renderer)
• Modified package: packages/note-to-html-swift/ (refactor: depends on note-core-swift, removes parser into shared layer)
• Modified: Sources/MacDocCLI/MacDoc+Convert.swift (new case ("note", "pdf"))
• Modified: Package.swift (add note-to-pdf-swift + note-core-swift deps)
• Platform: macOS 14+ (CGContext for PDF, same as existing)

Strategy

• Extract NoteParser, StrokeDecoder, TimelineDecoder, ParsedNote, StrokeData, Curve, NoteImage, RecordingInfo into new note-core-swift package
• Refactor note-to-html-swift to depend on note-core-swift (remove inline parser code, import shared types)
• Verify note-to-html-swift tests still pass after refactor
• Create note-to-pdf-swift package with NoteToPDFConverter using CGContext PDF drawing
• Handle multi-page rendering: calculate page breaks from ParsedNote.pageHeight, create one PDF page per note page
• Handle embedded images: convert NoteImage.data → CGImage, draw at correct position/size
• Handle stroke rendering: for each Curve, set color/width from Curve.color/Curve.width, draw CGMutablePath from Curve.points
• Wire up CLI route ("note", "pdf") in MacDoc+Convert.swift
• Write tests: round-trip a .note fixture → PDF → verify page count and non-empty output
• Update CLAUDE.md project structure and dependency graph

Complexity

SDD-warranted, reasons:

1. 3 packages touched (note-core-swift new, note-to-pdf-swift new, note-to-html-swift refactored) with interdependent changes
2. New shared package (note-core-swift) — new Layer 1 abstraction
3. Architecture decision on package split (Option A vs B vs C)
4. CGContext API surface for PDF rendering involves coordinate transform decisions (Notability's coordinate system → PDF points), page break calculations, image embedding
5. 10+ strategy steps with order dependencies (extract → refactor → verify → new converter → wire CLI)

Risks

• Coordinate system mismatch: Notability uses custom float coordinates (pageWidth ~560, pageHeight ~730). PDF uses 72 DPI points. Need a scale factor and possibly Y-axis flip (Notability may be top-left origin; PDF is bottom-left)
• Stroke fidelity: CGContext line rendering may look slightly different from HTML Canvas (anti-aliasing, line join/cap styles). Acceptable but worth visual comparison
• Parser extraction may break subtle internal deps: NoteParser might reference types or helpers that are package-internal. Need to audit exports
• Large notes (100+ pages): PDF could be large. No streaming support in CGContext — entire PDF is in memory. Acceptable for typical notes (1-20 pages)

[kiki830621]

Implementation Complete

New CLI route: macdoc convert --to pdf input.note

Architecture:

• note-core-swift (Layer 1): extracted NoteParser + StrokeDecoder + TimelineDecoder + all model types from note-to-html-swift
• note-to-pdf-swift (Layer 3): NoteToPDFConverter renders ParsedNote → PDF via CGContext
• note-to-html-swift (Layer 3): refactored to import NoteCore (thin converter only)

Spectra change: note-to-pdf

[kiki830621]

Closing Summary

Problem

No .note → pdf conversion. Claude/LLM cannot visually read HTML Canvas strokes. Existing extract_notability_pdf.py heuristic extracts background PDFs instead of handwritten strokes.

Solution

New note-to-pdf-swift converter renders Session.plist vector strokes via CGContext PDF. Coordinate transform (scale + Y-flip) maps Notability coordinates to PDF space. Multi-page support via pageHeight boundaries. Images as background layer. Audio skipped (static format).

Verification

All 3 packages build clean. macdoc builds with new CLI route. Spectra change artifacts validated.