作品ギャラリー

[temoki]

将来構想（旧 PLAN.md §13）。

メモ

• 作品（.tortoiseblocks）のサムネイル一覧。DocumentGroup のドキュメントブラウザとの棲み分けを設計から
• サムネイルは 最後に実行した評価済みコマンド列のドキュメント内永続化 #10（評価済みコマンド列の永続化）が入れば SVG/PNG 生成で作れる
• テンプレートギャラリー（新規ドキュメントのテンプレート（サンプルから選んで開始） #5）との統合も検討

[temoki]

設計（2026-07-20）

前提の決定（確認済み）: QuickLook サムネイル拡張でシステムのブラウザをギャラリー化する。アプリ内に専用のギャラリー画面は作らない。

• 「ギャラリー」の実体 = Finder / ファイル App / 起動時のドキュメントブラウザ。DocumentGroup の起動フロー・iCloud・検索・共有と一切衝突せず、メモにあった「棲み分け」問題が構造的に消える
• 依存: 最後に実行した評価済みコマンド列のドキュメント内永続化 #10（評価済みコマンド列のドキュメント内永続化）が先。サムネイルの素材は project.lastRun

アーキテクチャ

• 新ターゲット: QuickLook Thumbnail Extension（macOS / iOS で各 1 つ）。.tortoiseblocks（space.hiraku.tortoiseblocks.project）を QLSupportedContentTypes に宣言し、QLThumbnailProvider で JSON を decode → lastRun を画像化して返す
• extension は TortoiseBlocksKit をリンク（decode は Kit の凍結フォーマットそのまま。2 段階 decode の version ゲートも同じものを通す）
• 画像化の手段は要調査（実装の最初に spike）:
  1. まず現行 PNG 書き出しと同じ TortoiseCanvas + ImageRenderer（SwiftUI）を extension 内で試す
  2. extension 内で SwiftUI レンダリングが不可・不安定な場合は、コマンド列 → CGContext の軽量レンダラが必要。これは描画の責務なので TortoiseGraphics2 への upstream 候補（TortoisePlayer / reset() / command Codable と同じ流れ）。アプリ側 workaround で抱えない
• lastRun が無い（未実行の）ドキュメント: 亀のプレースホルダ画像を返す（真っ白より「開けば描けるよ」感を出す）
• 壊れたファイル・新しすぎる schemaVersion: サムネイル提供を辞退（システムのデフォルトアイコンに任せる）。extension は決して落とさない
• 描画コストは展開上限 10,000 コマンドで有界。QL の要求サイズ（例 256px）に合わせて縮小描画

pbxproj / CI

• 手書き pbxproj（objectVersion 77・buildable folders）への extension ターゲット追加が工事の中心。App への embed、INFOPLIST 設定、Kit のリンクを両プラットフォーム分
• CI は署名なしビルドを維持（extension を含めても CODE_SIGNING_ALLOWED=NO で通ることを確認）

テンプレート（旧 #5）との整理

空ワークスペースのサンプルボタン（実装済み）を継続。ギャラリーがシステム側になったため、アプリ内テンプレート一覧との統合は不要と整理する。

やること

• （前提）最後に実行した評価済みコマンド列のドキュメント内永続化 #10 を先に実装
• spike: extension 内で ImageRenderer が動くか検証 → 不可なら upstream issue（CG レンダラ）を起票して待つ/先行実装
• pbxproj: Thumbnail Extension ターゲット追加（macOS / iOS）+ App へ embed
• extension 実装: decode → lastRun 画像化 → QLThumbnailReply（未実行はプレースホルダ、異常系は辞退）
• プレースホルダ画像（亀 + アクセントカラー）
• 動作確認: Finder（アイコン/ギャラリー表示）・ファイル App・起動時ドキュメントブラウザ
• （stretch）QuickLook プレビュー拡張（スペースキー / 長押しプレビュー）— 同じ基盤で薄く足せる

受け入れ条件

• 実行 → 保存したファイルが Finder / ファイル App でサムネイル表示される（表示 = 保存された lastRun の絵）
• 未実行ファイルはプレースホルダ、壊れたファイルはデフォルトアイコン（クラッシュしない）
• 旧フォーマット（v1・lastRun なし）のファイルでも安全
• CI（署名なしビルド）green 維持、swift test + 両プラットフォームビルド green

検討ポイント

• サムネイルのキャッシュ・無効化は QuickLook 側の責務（ファイル更新日時で自動）。アプリ側では何もしない
• プレビュー拡張（stretch）を入れる場合も同じレンダリング経路を共有する