あやみ 1.5(21)開発・検証記録
あやみ 1.5(21)開発・検証記録
2026年10月26日、codex/v1.5で開発。対象はREADME・設計書・AI生成Markdownを読む
Macのエンジニア。開発版の機能と検証を記録するもので、ストアでの提供開始を意味しない。
実装した機能
| 機能 | 操作・振る舞い |
|---|---|
| 一時的な蛍光ペン | 文章を選択し、ツールバーの蛍光ペン、またはMacの⌘⇧Hでピンクにマーク。マークをクリックして文書の操作メニューから個別解除、または一括解除 |
| 文書内検索 | 虫眼鏡、Macの⌘F。一致を色で示し、件数・前後移動・⌘G/⌘⇧Gに対応。日本語、書式をまたぐ文章、コード、表を検索 |
| 相対画像・リンク | アプリ内で相対画像、関連するMarkdown・HTML・テキスト・ソース、見出しアンカーを開く。必要な場合だけプロジェクトフォルダーを選択してアクセスを許可 |
| リンクの表示先 | Macの文書リンクは新しいタブが初期値。「閲覧設定」で新しいウィンドウを選択でき、端末内に保持 |
| HTMLとテキスト | Markdown内HTMLと.htmlを表示。.txt・.json・.cなどは原文として開き、検索・マーク・コピーに対応 |
| コードコピー | コードの囲み記号を含めず、ブロックの内容をクリップボードへコピー。Prismで色分けを維持 |
| Live Reload | Macの外部保存・原子的なファイル置換を監視し、読んでいた段落と画面内の位置を復元 |
| Mermaid拡大 | 図の「図を拡大」から25〜400%へ拡大・縮小、スクロール、「全体を表示」、完了/Escapeで閉じる |
| 導入 | Macのようこそ画面、日英の公開技術文書サンプル、閲覧・フォルダー許可・Finder Quick Lookの案内 |
マークは文書ごとのメモリーだけに置く。文書を閉じると消え、保存確認は出さない。 Markdown、PDF、UserDefaults、ログへ書き出さない。別の文書への移動中やレイアウト変更では 開いたままの文書のマークを保持する。外部変更後も、元の文章を一意に照合できる場合に保持する。 特定できない場合は解除して案内する。
実装上の判断
検索・選択・複数箇所のマークを同じ本文に対して扱うため、主な閲覧面を非永続の
WKWebViewへ移した。SwiftUIの目次、設定、文書管理、ステータス、印刷・PDF・AIは維持する。
ReaderSessionが文書ごとにページを保持し、compact/regularの切り替えでも使い直す。
弱参照のメッセージ中継でページ・Coordinator・セッションの循環参照を避ける。
ReaderWebView.swift: SwiftUIとWebKitの橋渡し、ネイティブのコピー、状態・遷移。ReaderResources.swift: 同梱資産、画像の取得、フォルダー境界と実パスの検証。Resources/Reader/reader.js: 検索、一時マーク、段落位置、画像、コード、図の拡大。ReaderGuideView.swift: ようこそ画面、サンプル、案内、iOSの関連文書画面。
文書内HTMLとHTML文書はDOMPurifyと許可リストで処理し、表・強調・折りたたみと
限定したインラインCSSを表示する。文書スクリプト・フォーム・イベント属性は除去する。
文書のIDに接頭辞を付け、操作用属性を分離する。同梱スクリプトだけを読み込み、
CSPで外部通信を拒否する。画像取得は文書のフォルダー、明示的に選んだプロジェクト、
同梱サンプルに限定する。realpathで範囲外のシンボリックリンクを拒否する。
フォルダーの許可はアプリのセッション内だけに保持し、ブックマークとして保存しない。
検証
環境: Apple silicon、macOS 27.0.1、Xcode 27.1(27A9275)、Swift 6.4。 iPhone/iPadはiOS/iPadOS 26.5 Simulatorを使用した。
| 対象 | 結果 |
|---|---|
| Macの単体・WebKit統合・既存回帰 | swift testは成功(報告48件、任意の実AI生成1件はskip)。日本語・コード・表、書式をまたぐ検索、1MiBの長文と多数の一致、マークの寿命・再配置、検索中の位置保持、図の拡大、相対画像の許可後再取得、境界・リンクの検証を含む |
| Macの製品アプリ | Apple Development署名、1.5(21)、本体・Quick Lookともarm64。起動と実操作を確認 |
| Mac実操作 | ⌘F、検索件数と前後移動、文章選択→ピンクのマーク、個別解除、図の拡大、コードコピー、相対SVG、関連Markdown、見出しリンクを確認 |
| Macの外部更新 | 公開テスト文書のSection 20にマークを付け、先頭に10段落を追加して原子的に置換。Section 20とマークを保持し、Reloaded表示を確認 |
| 元文書の保護 | マーク前後、および文書を閉じた後に公開テスト文書の内容・SHA-256を照合。検証用の外部更新以外の書き込みなし |
| マークの終了 | マーク付き文書を保存確認なしで閉じ、同じサンプルを開き直すとマークが消えることを製品アプリで確認 |
| iPhone 17 Pro | 共有単体・WebKit統合37件と検索・導入・回転UI 3件成功。別実行で目次・設定・PDF UI 3件、ガイド→サンプル→相対リンクの関連文書を開くUI 1件も成功 |
| iPad Pro 13-inch(M5) | 共有単体・WebKit統合38件と検索・導入・目次・回転UI 4件成功。相対リンクの関連文書を開くUI 1件も追加成功 |
件数は実行ごとの値。iPhoneの37件の後、1MiBの長文テストを追加し、MacとiPadで実行した。 今回、実機・Duo・最小対応OS・紙への印刷・AIの実生成は追加検証していない。
リンク設定・HTML・テキストの追加検証
- Macの
swift testは54件・17 suiteで成功。文字コード、拡張子別の表示、設定の初期値・保持、 HTMLの表・折りたたみ・アンカー、スクリプトと偽の操作属性の除去、ソース内のHTML記号の保持を含む。 - 署名付きMac製品アプリで、JSONを初期値のタブに開き、設定を新しいウィンドウへ変えて Cソースを別ウィンドウに開く操作を確認。設定をタブへ戻し、再起動後の値も確認した。
- TXT・JSON・C・HTML・未知の
.exampleをサンプルのリンクから開いた。 HTMLは表・強調・折りたたみを表示し、他の形式はHTMLやMarkdownの記号を原文として保持した。 - 既存タブへのリンクで同じウィンドウを再追加すると、タブと本文の対応が崩れる問題を修正。 同じタブグループへの再追加を避け、HTMLから既存READMEへ戻る操作と手動タブ切り替えを再確認した。
- iPhoneの共有単体・WebKit統合44件が成功。ガイドから関連Markdownを開くUIも成功。 JSONを開く追加UIは、色分けされた文字が複数のアクセシビリティ要素になることを考慮して修正し、 HTML記号を原文として表示する確認とコピー操作の表示確認まで再実行して成功した。
- 最終Macビルドと
codesign --verify --deep --strict、Info.plistと日本語文字列の検証が成功。 この追加変更ではiPadのUIと実機は再実行していない。
追加ログは.build/logs/swift-1.5-links-html-text.log、
mac-1.5-text-final-build.log、ios-1.5-html-text.log、ios-1.5-json-confirmed.log。
最初のiPhone実行には上記のUIテスト失敗を含み、再実行の結果は
.build/results/ios-1.5-json-confirmed.xcresultに保存した。
MacのHTMLとタブの実画面は.build/logs/mac-1.5-html-and-tabs.jpg。
起動画面の表示設定
起動画面に「次回起動時もこの画面を表示する」を追加した。初回は案内を表示し、
チェックの初期値はオフ。以降はオンにした場合だけ自動表示し、ヘルプからはいつでも呼び出せる。
Mac製品アプリのビルドが成功し、日本語のチェックボックス、オンの保持と再起動後の表示を確認した。
最後はオフに戻して再起動し、公開文書を通常どおり開けることも確認した。
ビルドログは.build/logs/mac-1.5-welcome-build.log、画面は
.build/logs/mac-1.5-welcome-checkbox.jpg。この小変更ではiOSテストを再実行していない。
リンクの右クリックメニューの修正
WebKit標準メニューが本文クリックのアプリ処理を通らず、ayami-reader://bundle/を基準にした
内部URLを使っていた。Macのリンク上だけ専用メニューに置き換え、元文書基準のリンク処理へ接続した。
- 「リンクを開く」は表示設定に従い、タブ・ウィンドウの明示指定は設定より優先する。
- 「リンクをコピー」は実ファイルまたはWebのURLをコピーし、見出しのフラグメントも保持する。
- 「ダウンロード」は保存先パネルを表示。ローカルファイルは許可境界を検証して元のバイト列をコピーし、 元ファイル自身への上書きを拒否する。HTTP(S)は利用者の操作時だけ取得する。
- 文書内のリンク以外の右クリックメニューは変更しない。iOSのメニューも今回の置き換え対象外。
Mac製品アプリの日本語メニューから、JSONの通常オープン、Cソースの新規タブ表示、
既存JSONタブを別ウィンドウへ分離、URLコピー後の検索欄への貼り付け、保存先指定と実保存を確認した。
保存した.build/logs/link-menu-download/config.jsonは元の同梱ファイルとSHA-256が一致した。
HTTP(S)の実ダウンロードは今回の実操作検証には含めていない。
Macのswift testは56件・18 suiteで成功。メニューの各オープン操作、独立したクリップボードでの
アンカー付きURLコピー、保存データ一致、元ファイルとそのシンボリックリンクへの上書き拒否を含む。
初回のテストでコピーURLからアンカーが落ちる問題を検出し、保持するよう修正して再実行した。
iPhoneの閲覧ランタイム回帰テストも成功。
ログは.build/logs/swift-1.5-link-menu-confirmed.log、mac-1.5-link-menu-build.log、
ios-1.5-link-menu-regression.log。
修正した問題
-
Quick Look設定への直接移動の検証後、一覧にAyamiが表示されなくなった。 製品の
io.github.hshimomura.MDViewer.QuickLookはpluginkitに有効な状態で残っていたが、 システム設定の一覧には出ていなかった。検証用アプリの登録解除だけで後片付けを完了し、 通常のAyamiの実表示まで再確認していなかった点を修正する。dist/validation-1.5/Ayami.appと/Applications/Ayami.appの親アプリ・同梱拡張を再登録し、 実際のQuick Look一覧にAyamiがオンで戻ったことを確認した。原因となった登録の詳細は未確定。 ビルドスクリプトではXcodeの中間生成物だけでなく、最終コピーも明示的に登録するよう変更した。 今後の検証用登録の後片付けでも、製品の登録と設定一覧への実表示を確認する。 -
閲覧ガイドからシステム設定のトップだけを開いていたボタンを「Quick Lookの設定を開く」に変更。 macOS 27.0.1で、別IDのMac検証アプリのガイドからQuick Look拡張機能のスイッチ一覧が 直接開くことを実操作で確認した。各スイッチは変更していない。 macOS 26での同じ移動先は未検証。URLが開けない場合の公開APIによるログイン項目への移動と、 ガイドの手動経路を保持する。製品アプリと検証アプリのビルドは成功した。 ログは
.build/logs/mac-1.5-quicklook-settings-build.logとmac-1.5-quicklook-settings-ui-build.log、画面はmac-1.5-quicklook-settings.jpg。 -
蛍光ペンの解除・全消去で、データ上の状態と実際の色の描画が一致しない場合があった。 毎回
Highlightを置き換える方法をやめ、同じ登録オブジェクトをclear()/add()で更新する。 WebKit 321567の再描画問題に該当する更新経路を避ける。 GUIと解除操作は変更しない。 新しいMacテストは表示用ウィンドウでWebKitの画像を取得し、追加・個別解除・再追加・全消去の ピンク色画素を検証する。解除後には再選択・クリック・スクロールを送らず、色が消えることを確認する。 本文の文字列も照合する。修正前は再追加時の色の検証に失敗し、修正後は成功した。 Mac全体は57件・18 suiteで成功。ログは.build/logs/swift-1.5-mark-repaint-fixed.log、 製品ビルドはmac-1.5-mark-repaint-build.log。 iPhoneの共有閲覧ランタイム11件も成功(ios-1.5-mark-repaint.log)。 - Macのフォルダー選択では、追加のsecurity-scopedアクセス開始が不要な場合があった。 明示的なフォルダー選択を許可境界として記録し、画像を新しいURLで再取得する形へ修正。 修正前は画像が出ず、修正後は実際のSVG表示まで確認した。
openDocumentはiOSでは使えないため、iOSの関連文書は専用の読み取り専用画面で開く。- 検索中のLive Reloadで最初の一致箇所へ戻らないよう、再検索の表示移動を抑制した。
- 画面構成の変更でページを作り直さず、マークと読書状態を保持する形にした。
- UIテストの要素クエリーの指定ミスを修正し、関連文書へ遷移する操作まで再実行した。
ローカルの証跡
生成物はGit管理外の.build/に置く。
logs/swift-1.5-complete.log: Macの全テスト。logs/mac-1.5-build-complete.log: 署名付きMacビルド。logs/mac-1.5-live-reload.jpg: 外部更新後もSection 20とマークが残る画面。results/ios-1.5-reading-fixed.xcresult: iPhoneの目次・設定・PDFと共有テスト。results/ios-1.5-final.xcresult: iPhoneの検索・導入・回転と共有テスト。results/ipad-1.5-reading.xcresult: iPadの検索・導入・目次・回転と共有テスト。results/ios-1.5-related-links-fixed.xcresult、results/ipad-1.5-related-links.xcresult: 関連文書を開く追加UI検証。results/ios-1.5-final-confirmed.xcresult: 最終ソースの閲覧ランタイム8件と、サンプルから関連文書を開くUI 1件。
スクリーンショットの準備
Mac製品ターゲットの1.5(21)と同梱の公開サンプルだけを使い、日英各5枚の素材を撮影した。
保存先はAppStore/Screenshots/1.5/macOS/{ja,en-US}/。JPEG、2560×1600、不透明。
拡大補間や画面内容の合成は行っていない。
01-reading-mark.jpg: ピンクのマーク、目次、Mermaid、表。02-find.jpg: 検索語、一致件数と本文・表の一致箇所。03-mermaid-expanded.jpg: 図の拡大表示、125%と表示操作。04-project-links.jpg: 相対SVGと関連文書・見出しへのリンク。05-code-copy.jpg: 色分けしたコードとコピー完了。
ストアへ提出する画像の選定前の素材。カーソルや余白、見せる図の複雑さは最終選定で調整する。 iPhone/iPadのストア画像、紹介動画、ストア原稿は今回の撮影には含めない。
Quick Lookの追加素材として、公開用の通知サービス設計書を日英で作成し、Finderで実際にプレビューした。
同梱製品拡張による描画を撮影し、06-quicklook-source.jpgに1940×1526の原画を保持する。
Quick Lookの描画ソースは1.4から変更していないことを差分で確認した。
AppStore/Screenshots/quicklook-layout.htmlで画面の比率・内容を保持して縮小し、短い説明を添えた
06-quicklook.jpgを日英各1枚作成。1280×800の不透明JPEGで、Mac用の受け入れ寸法と一致する。
Mermaid・表・見出しの表示、言語、文字切れ、私的な文書が含まれないことを目視確認した。
画像はAsset Libraryの未提出素材として準備し、1.5の掲載枠へ追加する。動画は今回制作しない。
アカウント固有のアップロード・確認記録はGit管理外のAppStore/private/へ保存する。
iPhone Duo用として、1.5(21)のAyamiIOS製品ターゲットを現在のソースからビルドした。
iOS 27.1で日英それぞれ、内側の閲覧・一時マーク・検索・表示設定と外側の閲覧を撮影した。
内側は開いた状態で2007×2853、外側は閉じた状態で1398×2034。物理回転後に縦向きの
レイアウトを確認し、表示設定は100%、目次は閉じた状態にした。
日本語の「リクエスト」は1 / 3、英語のrequestは1 / 5と表示され、本文・表の一致箇所を確認した。
全10枚は不透明JPEGで、元解像度を維持。私的な文書やUIテスト用ホストは含まない。
保存先はAppStore/Screenshots/1.5/iPhoneDuo/{ja,en-US}/。
同ディレクトリーのmanifest.jsonへ寸法・ファイルサイズ・SHA-256を記録した。
ビルドログは.build/logs/ios-1.5-duo-screenshots-build.log。
撮影中のDevice Hubの操作接続が不安定になった際は、コンパクト表示と標準表示を切り替えて復旧した。
今回の確認は撮影した閲覧操作の範囲であり、Duoでの全機能回帰テストや実機確認を意味しない。
追加依存とライセンス
- markdown-it 15.0.3のUMDバンドルを同梱。 npm公式レジストリーのtarballを取得し、公開されたSHA-512 integrityと照合した。
- バンドルのSHA-256:
391f2aa638e75e6c7859d0a5c5650ef0956722a45998f17e05b83bc655778e1e。 - 同梱ソースマップでmdurl、uc.micro、entities、linkify-it、punycode.jsを確認し、
MITライセンスを
Legal/markdown-it-dependencies-LICENSE.txtへ保持。 - Prism 1.29.0は固定依存Textual 0.5.0の資産と同一。既存のPrismライセンスを利用。
- DOMPurify 3.4.17の公式npm tarballを公開SHA-512 integrityと照合して同梱。
バンドルSHA-256:
cd37898f9782adf54820c413191b5691803f0f137c799d6edcfd38523b4c2c31。 Apache-2.0を選択し、Legal/DOMPurify-LICENSE.txtへ全文を保持。 - Swift依存とMermaid 12.2.0の固定版は変更しない。
Macのウインドウ再表示(2026-10-26)
「ウインドウ → 起動画面を表示」を追加。起動画面を自動表示しない設定でも、 文書を開いていない状態から起動画面を再表示できる。全ウインドウを閉じてもアプリは終了しない。
隔離したAyamiMacUIValidationのUIテスト
MacOutputUITests/testWelcomeCanBeReopenedAfterAllWindowsCloseで以下を確認した(1件成功、失敗0件)。
- 起動画面の自動表示をオフにし、公開テスト文書のウインドウをすべて閉じる。
- ウインドウがゼロでもアプリが起動したままであり、再表示メニューが有効。
- メニューから起動画面を開き、閉じ、再び開ける(2回連続)。
- さらに全ウインドウを閉じた後、⌘Oで公開テスト文書を開き直せる。
- 元の文書に変更がない。
結果は/private/tmp/ayami-window-recovery-test-2.xcresult。テストホストでの検証であり、
製品バンドルの再アーカイブと配布は別工程とする。
制限と次の確認
- マークと相対画像の追加対応はアプリの閲覧画面が対象。Quick LookとPDFの画像対応は従来のまま。 マークは印刷・PDFへ含めない。Quick Lookは引き続き連続表示を使う。
- 検索は本文・コード・表を対象とする。Mermaid内部の文字と操作用ラベルは対象外。
一度に表示する一致は最大10,000件で、上限に達した件数には
+を付ける。 - 外部画像は読み込まない。ローカル画像は1件20MiBまで。
- HTMLは許可した要素・インラインCSSのみ。JavaScript、外部CSS、iframe、フォーム、数式の専用描画は対象外。
- テキストは最大20MiB、UTF-8・BOM付きUTF-16/32・Shift JIS。バイナリーは拒否する。 Markdown以外の印刷・PDFはHTML表示も含め原文のコード出力となり、出力側の1MiB上限を維持する。
- 同文・同文脈の繰り返し、読んでいた段落の全面変更ではマークや位置を厳密に保持できない場合がある。
- VoiceOver全操作、長文と多数の複雑な図を組み合わせた継続利用、実機・最小対応OSの検証は今後の範囲。
- App Store用アーカイブ、配布パイプラインの1.5更新、ストア提出は別のリリース工程とする。
2026-10-27の配布前検証
- Macの
swift test: 57件、18 suiteで成功(任意のAI実生成はskip)。 蛍光ペンのスナップショット判定は、ネイティブ状態の通知後もWebKitの描画フレームを待つようにした。 テキストの再選択・クリック・スクロールを追加せず、追加と個別解除・全消去の実画面を判定する。 - iPhone 17 ProとiPad Pro 13-inch(M5)、iOS/iPadOS 26.5 Simulator: それぞれ共有単体・WebKit統合44件成功、UIテスト12件中11件成功・1件skip・失敗0件。 skipは任意のAI実生成。検索、サンプル導入、関連JSON、目次、回転、設定保持、PDF保存、 印刷オプションの表示・取消を含む。印刷ジョブは送信しない。
- Mac・iOSの1.5(21)ReleaseアーカイブとApp Store書き出しが成功。 Macは本体・Quick Lookともarm64。配布署名、バンドルID、版・ビルド、権限、 iOSのApp Storeプロファイル、Reader/サンプル/依存ライセンス同梱を検証した。
- 日本語プロモーション文のCommandキー記号は入力制約に合わせて
Command-Fへ変更した。 日英・Mac/iOSの紹介文と文字数検証を再実行した。 - 日英のHeader/Search Results画像を既存アイコンと公開製品画面から構成した。 5244×2950、不透明RGB PNGを検証し、両言語の描画を目視確認した。
紙への印刷、実機、最小対応OS、任意のAI実生成の追加成功は主張しない。
アカウントに依存するAPI応答、審査状態、識別子、審査メモ、実行ログはGit管理外の
AppStore/private/へ保持する。