あやみ 1.5 開発版(21)実装仕様

Mac・iPhone・iPadの読み取り専用ビューアーを共通SwiftUIコードで構成する。 利用者向け機能はREADME、データフローは設計、 1.5の変更と検証は1.5検証記録、従来機能の履歴は 1.4検証記録を参照する。

ターゲットと責務

対象・責務 実装
Mac Ayami、Apple silicon、macOS 26+、AyamiMacApp.swift
iPhone・iPad AyamiIOS、iOS/iPadOS 18+、Sources/AyamiIOS/AyamiApp.swift
共有ソース Sources/Ayami/。Mac専用の入口・ウィンドウ制御はiOSから除外
文書管理・監視 MarkdownDocument、DocumentGroup(viewing:)、PreviewDocumentModel
読書・目次・設定 PreviewView、ReaderSession、ReaderWebView、OutlineSidebar、ReadingPreferences、ReadingSettingsView
読書画面の図 Resources/Reader/reader.js、MermaidRendererResources、同梱ランタイム
PDF入力・スタイル OutputDocument、OutputTextStyle
PDF生成・図合成 DocumentPDFGenerator、MermaidPDFRenderer
出力画面・OS操作 DocumentOutputView、PDFKit、PDFExportDocument、OS別印刷ボタン
Finder Quick Look AyamiQuickLook、PreviewProvider、QuickLookHTMLRenderer、SVG添付
端末内AI DocumentSummary、DocumentSummaryView

project.ymlが構成の正本。Mac本体・拡張・MacテストはARCHS: arm64。 アプリと拡張のバージョンは1.5、ビルドは21。アプリのBundle IDは io.github.hshimomura.MDViewer、製品拡張は末尾.QuickLookで互換性を維持する。 改名時の判断は構成変更記録に残す。

文字サイズと文書画面

  • readerFontScaleを端末単位の@AppStorageで保存。初期値1.0、範囲0.80〜1.60、5%刻み。
  • 範囲外を制限し、NaN・無限大は初期値へ戻す。「標準に戻す」は100%。
  • 本文のCSSルート文字サイズへ適用。Dynamic Typeの倍率も反映。目次・ステータスはシステム設定に従う。
  • MarkdownやPDFの独立したレイアウトは変更しない。Dynamic Typeも維持する。

Macの「ファイルを開く」は個別ウィンドウ、「新しいタブでファイルを開く」はネイティブタブへ追加する。 文書中のローカルリンクはタブが初期値。「閲覧設定」の「文書リンク」で新しいウィンドウにも変更できる。 readerLinkDestinationにtabまたはwindowを保存し、同一ファイル内のアンカーは現在の文書で移動する。 Webリンクは既定のブラウザーへ渡す。 Macのリンク右クリックはアプリの専用メニューを使い、通常表示・新しいタブ・新しいウィンドウ・ 保存・URLコピーを扱う。WebKitの表示用URLではなく、元文書を基準にした実URLを解決する。 保存は保存先パネルで選択し、ローカルファイルには通常のフォルダー境界検証を適用する。 元ファイル自身への保存は拒否する。HTTP(S)の保存は利用者の操作時だけ、非永続URLSessionで取得する。 Webリンクの表示先はブラウザーへ任せ、Macのタブ・ウィンドウ指定はローカル文書に限定する。 起動画面は初回に一度案内する。「次回起動時もこの画面を表示する」は初期値オフ。 hasSeenWelcomeとshowWelcomeAtLaunchを端末内に保存し、次回以降はチェックした場合だけ表示する。 非表示にした後も「ヘルプ」から起動画面と技術文書サンプルを開ける。 「ウインドウ → 起動画面を表示」は起動画面のSceneに登録し、文書を開いていない状態でも使えるようにする。 すべてのウインドウを閉じてもアプリは終了しない。このメニューから起動画面を再表示し、文書を開き直せる。 左右配置は文書ウィンドウだけを対象とし、Macのみ外部ファイルを約400ms間隔で監視する。

iOSはFilesから開き、compact幅は目次シート、regular幅は230ptの目次と本文をHStackで並べる。 DocumentGroupにNavigationSplitViewを重ねず、Duoの文書バー重複を防ぐ。 端末名や.phoneで配置を固定せず、iPadの複数ウィンドウはOSへ任せる。 独自のファイルポーリングは行わず、外部変更が反映されない場合は文書を開き直す。

1.5の閲覧セッション

  • 文書ごとに非永続WKWebViewを保持。compact/regularのレイアウト変更でも同じページを再利用する。
  • メッセージハンドラーは弱参照の中継を使い、ページとCoordinator・セッションの循環参照を避ける。
  • 検索とピンクのマークはCSS Custom Highlightで描画。元文書の文字列やDOMの本文を注釈用に書き換えない。
  • 登録済みのHighlightを保持し、clear()/add()で描画範囲を更新する。 同じキーへのCSS.highlights.set()による置き換えは、WebKitで再描画されない場合があるため避ける。
  • マークはページのメモリーだけに置く。保存、UserDefaults、ログ、PDFへの転記を行わない。
  • 再読み込み時は引用文字列と前後の文脈でマークを照合。特定できないマークは解除して案内する。
  • 読書位置は表示中の段落の内容と画面内の位置で復元。挿入された文章の行数に依存しない。
  • 相対画像は専用URL schemeで渡す。文書のフォルダー、利用者が選んだプロジェクト、同梱サンプルだけを許可する。
  • 実パスの解決でシンボリックリンクの範囲外参照を拒否。画像は1件20MiBまで。外部画像は読み込まない。
  • プロジェクトの許可はアプリのセッション内だけ有効。ブックマークとして保存しない。
  • 関連文書はMacではDocumentGroupで開く。iOSでは専用の読み取り専用画面で開く。
  • Markdown内のHTMLと.html/.htmをDOMPurifyで処理。表・強調・折りたたみと許可したインラインCSSを表示する。
  • 文書のスクリプト、iframe、フォーム、イベント属性を除去。文書のIDは接頭辞で読書UIと分離する。
  • スクリプトは同梱資産のみ。外部通信はCSPで拒否し、画像は許可したローカル画像とrasterのdata URIに限定する。

テキストファイル

MarkdownDocumentはMarkdownのほか、テキスト・JSON・ソースコード・一般データのViewerとして登録する。 追加形式はLSHandlerRank=Noneで既定アプリを奪わず、読み込み時にテキストかどうか判定する。 TextFileContentは最大20MiB、UTF-8(BOM含む)、BOM付きUTF-16/32、Shift JISに対応する。 NULなどの制御文字を含むバイナリーと上限を超える入力は説明付きで拒否する。

.md/.markdownはMarkdown、.html/.htmはHTML、それ以外の拡張子は原文を保つテキストとして表示する。 JSON・Cなどは対応するPrism文法がある場合に色分けし、検索・マーク・コピーも利用できる。 印刷・PDFは別パイプラインのため、Markdown以外は原文をコードとして出力する。 HTMLの見た目の再現は行わない。出力側の1MiB上限は維持する。

印刷・PDF

文書メニューの「印刷とPDF」、MacのCommand-Pから共通画面を開く。 入力は開いているMarkdownのスナップショット。A4/Letterを選び直すと生成をやり直し、 PDFKitでプレビューする。保存成功のコールバック後だけ完了表示し、取消はエラーにしない。

  • OutputDocument: UTF-8、最大1MiB。見出し、段落、リスト、引用、コード、表、水平線、Mermaidを分離。
  • OutputTextStyle: FoundationのインラインMarkdown解析とCoreTextの文字属性。コード以外の<br>に対応。
  • DocumentPDFGenerator: CoreText/CoreGraphicsで最大500ページ。選択可能な文字、ページ番号、表見出しの繰り返し。
  • 大きすぎる表の行や幅は文字として改ページし、切り落としを避ける。
  • MermaidPDFRenderer: 非永続WKWebViewで同梱JSからSVGを作り、WebKitのベクターPDFを合成。 図の上限64KiB、ロード待ち15秒・描画待ち12秒。失敗時だけ警告とソースへフォールバック。
  • Mac: NSPrintOperationをアクティブなウィンドウに付随させ、出力シートから操作できるようにする。
  • iOS: UIPrintInteractionController。用紙変更後の最新PDFとタイトルをCoordinatorへ反映する。

読書画面とは別レンダラーであり、画像の外部・相対パス解決、HTML/CSSの完全再現、 入れ子リストや表の配置指定の完全対応は行わない。 旧DocumentPrintCoordinatorとTextKit印刷フォーマッターは削除し、二重実装を残さない。

Finder Quick Look

閲覧ガイドの「Quick Lookの設定を開く」は、システム設定のログイン項目と機能拡張へ extensionPointIdentifier=com.apple.quicklook.previewを指定して移動する。 Quick Lookの一覧を直接開くURLはOS側の仕様に依存するため、ガイドの手動経路も残す。 URLの起動要求が失敗した場合は公開APIのSMAppService.openSystemSettingsLoginItems()へ戻す。 有効化スイッチをアプリから変更することはない。

MacアプリがAyamiQuickLook.appexを同梱する。net.daringfireball.markdownを対象に、 データ方式のQLPreviewProviderがUTF-8を読み、QuickLookHTMLRendererで連続HTMLを生成する。 Mermaidは同梱ランタイムでSVGを生成し、QLPreviewReplyAttachmentとしてCID参照で渡す。 HTML内で文書由来のスクリプトは実行せず、本文のHTML記号をエスケープする。 改ページ・用紙サイズ・ページ番号は印刷/PDF保存に限定する。 OSが選択とスクロールを管理する。AIやアプリの設定は組み込まない。

サンドボックス、ユーザー選択read-only、ローカルWebKit用network.clientを付ける。 本文やファイル名はログに含めず、初期化・準備要求・完了・エラー型だけを記録する。 他社のMarkdown拡張が残る環境では選択・登録状態の確認が必要。診断経緯は検証記録へ分離する。

端末内AI「文書の要点」(試作)

OS 26+でSystemLanguageModel.defaultの利用可否・言語対応を確認し、明示的な生成操作だけで実行する。 未対応端末、Apple Intelligence無効、モデル準備中、非対応言語は説明を表示する。 生成失敗・取消は読書やPDFへ波及させない。結果は画面表示だけで、元文書へ書き戻さない。

  • 最大32,000文字。800文字単位に分割し、長文は部分要約から段階的に縮約する。
  • 日本語環境では日本語、それ以外は英語を出力指示する。
  • 文書中の命令を信頼せず、参照資料内の事実だけを要約するよう指示する。
  • クラウドフォールバック、Private Cloud Compute、他社モデル、ツール、ファイル操作は渡さない。
  • AIが誤る可能性と原文照合を画面に表示する。iOSは弱リンクとavailabilityで最低OS 18を維持する。

生成精度と全端末での利用成功は保証しない。Mac実生成は成功したが、iPhoneシミュレーターの失敗と iPad/Duoの未確認が残る。試作を配布対象へ含める判断と検証範囲は検証記録を参照する。

資産・プライバシー・ビルド

Swift依存とMermaidの固定版は1.3と同じ。1.5ではmarkdown-it 15.0.3と、Textual同梱版と同じ Prism 1.29.0のブラウザーバンドルを追加。取得元・SHA-256・ライセンスは1.5検証記録と 第三者通知を参照する。 読書用と出力用Mermaidは同じ資産を使い、CSP・外部遷移拒否・リンク除去・タイムアウトを適用する。 Privacy ManifestはUserDefaults理由CA92.1、更新時刻理由3B52.1、収集・追跡なしを記録する。

ローカルMacも拡張を同梱するXcodeビルドを使う。SwiftPMは単体テストに使うが拡張の配布バンドルを作らない。 Mac UIテストは別識別子の同じ製品ソース、iOS UIテストは共有画面の専用ホストを使う。 製品にブラウザーバイパスを追加せず、ストア画像は製品ターゲットから撮影する。

ビルドとテストの入口 · 配布チェックリスト · 名称・アイコン · 初期iOS計画との差分