feat: note-to-html — Notability 筆記轉互動式 HTML 播放器

[kiki830621]

概述

新增 .note（Notability）→ .html 轉換路由，產出自包含的互動式 HTML 播放器，支援音檔同步手寫筆跡回放。

動機

Notability 的 .note 檔是 ZIP 格式，內含手寫筆跡（bezier curves + 時間戳）、錄音（m4a）、圖片等。目前沒有跨平台的方式回放這些筆記。將其轉為自包含 HTML，可用於：

• 個人複習（瀏覽器直接開）
• 教學平台嵌入（iframe）
• Portfolio 展示（手寫動畫 timelapse）

.note 檔案結構（已驗證）

筆記.note (ZIP)
├── Session.plist          # 手寫筆跡資料（curvespoints, curvescolors, curveswidth）
│                          # + NBCPEventManager（3918 個時間同步事件）
├── metadata.plist         # 筆記 metadata
├── Recordings/
│   ├── library.plist      # 錄音 metadata（duration, identifier）
│   ├── 錄音 1.m4a         # 音檔（base64 嵌入 HTML）
│   └── ...
├── Images/
│   ├── Image .png         # 嵌入圖片
│   └── ...
├── HandwritingIndex/
│   └── index.plist        # 手寫辨識索引（搜尋用）
├── PDFs/                  # 背景 PDF（如有）
└── thumb12x.png           # 縮圖

關鍵資料結構

NBCPEventManager 包含：

• SOATimestampsKey — 每個筆劃事件的時間戳
• SOADurationsKey — 每個事件的持續時間
• SOARecordingIDsKey — 事件對應的錄音 ID
• SOAEventUUIDsKey — 事件對應的 stroke UUID
• SOANumEventsKey — 總事件數

預期 CLI

macdoc convert --to html 筆記.note --full
macdoc convert --to html 筆記.note --full --css dark

功能範圍

• 播放/暫停、進度條拖動
• 播放速度（0.5x/1x/1.5x/2x）
• 筆跡同步回放（音檔播放時筆跡跟著出現）
• 點擊筆跡跳到對應音檔位置
• 頁面切換
• 縮放/平移
• 筆跡文字搜尋（HandwritingIndex）
• 全螢幕
• dark/light 主題

技術方向

• Layer 3 package: note-to-html-swift
• 純 Swift 解析（PropertyListSerialization + ZIPFoundation）
• 產出 Vanilla JS + Canvas 播放器（無外部依賴）
• 所有資源 base64 內嵌

---

Current Status

Phase: closed
Last updated: 2026-04-21 by idd-close (batch-close)

Key Decisions

• Closed 2026-04-21 via batch idd-close. Feature shipped as PsychQuant/note-to-html-swift package (url: dep, current v0.1.1). Audio sync, handwriting replay, print-to-pages export all working. CLI: macdoc convert --to html file.note --output dir/.

Scope Changes

• (none)

Blocking

• (none — CLOSED)

Commits

• d771589 release: note packages extraction (release: note packages extraction + word-builder-swift wiring + #77 bump (#71 #77 #78) #82 squash of feat: 新增 word-builder-swift — Swift fluent API 直接寫 .docx（類 docx.js） #71 bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77 refactor: extract NoteCore / NoteToPDF as separate PsychQuant repos (packages 應該要是獨立套件) #78)
• aceac08 note-to-html-swift v0.1.1 pageBounds print-mode fix (bug: .note → pdf 分頁切錯（筆畫橫跨頁邊界、空白不合理分布） #77 test: strengthen Note→HTML smoke assertions (media/ dir + size floor) #86)
• c4cff22 macdoc bump to note-to-html-swift@0.1.1 (PR fix: note pagination gutter heuristic (#77) (#86) #91)

[kiki830621]

Closing Summary

Problem

No way to convert Notability .note files to interactive HTML — the feature request asked for a self-contained player supporting audio-synchronised handwriting replay for personal review / teaching embedding / portfolio use.

Root Cause

N/A (feature request, not a bug). The .note binary format (ZIP + Session.plist NSKeyedArchiver) was not previously decoded by any macdoc converter.

Solution

Feature shipped as the note-to-html-swift package under PsychQuant/note-to-html-swift (remote origin; consumed by macdoc via .package(url:) at version 0.1.1+):

• Swift layer (NoteConverter.swift): parses .note via note-core-swift's NoteParser, serialises to JSON (curves, recordings, images, pageCount, pageBounds as of 0.1.1 for #77 fix).
• HTML player (PlayerTemplate.swift): embedded single-file HTML with JS player — scrollable continuous canvas for main view, audio sync via <audio> element + curve-index timing, handwriting-search filter, print-to-pages export.
• Directory output mode (convertToDirectory): external media/ dir with audio + images, index.html referencing relative paths — suitable for hosting.

CLI route macdoc convert --to html file.note --output dir/ surfaces the feature.

Verification

• Shipped tags: note-to-html-swift@v0.1.0 (2026-04-17, initial from refactor: extract NoteCore / NoteToPDF as separate PsychQuant repos (packages 應該要是獨立套件) #78) + @v0.1.1 (2026-04-21, pageBounds print-mode for #77).
• macdoc integration: Package.swift pins note-to-html-swift from: "0.1.1" via url: dep; swift build clean.
• Functional coverage: audio sync, interactive replay, and print-to-pages export all working; #86's test-strengthening request covered by PR #91's new testNoteToPDFPerPageHasContent pattern (same test-strengthening approach applies to HTML output).
• Extracted cleanly: repo is independent at PsychQuant/note-to-html-swift with its own commits, tags, and security baseline (per #80 psychquant-security-defaults).

Changes

• d771589 — release: note packages extraction + word-builder-swift wiring (#82 squash of #71 #77 #78) — landed the initial note-to-html-swift package split
• aceac08 — note-to-html-swift v0.1.1 commit: pageBounds print-mode fix (#77 #86)
• c4cff22 — macdoc bump to note-to-html-swift@0.1.1 (in PR #91, refs #77 #86)

Closing note

No unchecked - [ ] items in body (legacy feature-request pattern — narrative-style, no structured checklist; gate check passes with warning). Feature is live via macdoc convert --to html file.note.