Visual Intelligence integration / ビジュアルインテリジェンス統合 (WWDC26)

[touyou]

概要

ビジュアルインテリジェンス（Visual Intelligence）をアプリに統合する。カメラ/スクリーンショット入力に対する画像検索を、VisualIntelligence フレームワークとVisionフレームワーク経由で提供する。

関連セッション:

• WWDC26-297 アプリにビジュアルインテリジェンスを統合するためのベストプラクティス

新API

• VisualIntelligence フレームワーク — 画像検索機能の有効化
• IntentValueQuery + SemanticContentDescriptor（ピクセルバッファ入力）→ [VisualSearchResult]
• @UnionValue で複数エンティティ型（例: アルバムとコンサート）を返却
• OpenIntent — 検索結果からコンテンツへ遷移する軽量Intent
• Vision: GenerateImageFeaturePrintRequest — オンデバイスの画像類似マッチング、feature print事前計算カタログ
• semanticContentSearch スキーマ — アプリ内検索体験への継続

このリポジトリへの反映案

• 新しいブリッジ概念: ピクセルバッファ（画像）入力をDartへ渡すか、Swift側（Vision）で完結させるかの設計判断が必要
• IntentValueQuery 対応（IntentValueQuery (structured & visual search) / IntentValueQuery対応 (WWDC26) #51）が前提
• app_intents_annotations: ビジュアル検索ハンドラ用の新アノテーション
• app_intents_codegen: IntentValueQuery(visual) 準拠型と OpenIntent の生成
• Vision の feature print 計算はネイティブで重い処理になるため、Flutter側に出さずSwift側で完結させる方が現実的な可能性

制約・備考

• 未リリース/ベータのiOS SDK（VisualIntelligence/Vision）が前提（blocked: needs-sdk）
• 画像データのMethodChannel往復はパフォーマンス上の課題があり、ネイティブ完結の設計を優先検討
• IntentValueQuery基盤（IntentValueQuery (structured & visual search) / IntentValueQuery対応 (WWDC26) #51）に依存

---

🌐 English

Overview

Integrate Visual Intelligence into the app, providing image search over camera / screenshot input via the VisualIntelligence framework and the Vision framework.

Related session:

• WWDC26-297 Best practices for integrating Visual Intelligence into your app

New APIs

• VisualIntelligence framework — enable image search capabilities
• IntentValueQuery + SemanticContentDescriptor (pixel-buffer input) → [VisualSearchResult]
• Return multiple entity types via @UnionValue (e.g. albums and concerts)
• OpenIntent — a lightweight intent to navigate from a search result to content
• Vision: GenerateImageFeaturePrintRequest — on-device image similarity matching, with a pre-computed feature-print catalog
• semanticContentSearch schema — continue into the in-app search experience

Proposed changes in this repo

• A new bridging concept: decide whether to pass pixel-buffer (image) input to Dart, or keep it entirely on the Swift side (Vision)
• Depends on IntentValueQuery support (IntentValueQuery (structured & visual search) / IntentValueQuery対応 (WWDC26) #51)
• app_intents_annotations: a new annotation for the visual-search handler
• app_intents_codegen: generate the IntentValueQuery (visual)-conforming type and OpenIntent
• Vision feature-print computation is heavy native work, so keeping it entirely on the Swift side (not exposing it to Flutter) is likely more realistic

Constraints / notes

• Requires an unreleased/beta iOS SDK (VisualIntelligence/Vision) (blocked: needs-sdk)
• Round-tripping image data over MethodChannel has performance concerns; prioritize a native-only design
• Depends on the IntentValueQuery foundation (IntentValueQuery (structured & visual search) / IntentValueQuery対応 (WWDC26) #51)

[touyou]

状態更新: 依存する #51 の構造化版が着地（PR #68）

ビジュアルインテリジェンス（#58）が前提とする #51 IntentValueQuery の構造化/テキスト版が PR #68 でマージされました。ブリッジの土台（FlutterBridge.queryValues 等）と設計の線引きは docs/adr/0001 に整理済みです。

本 issue（ビジュアル）はまだ未着手で、Input == SemanticContentDescriptor（VisualIntelligence、pixelBuffer: CVPixelBuffer を保持）= ネイティブ完結が前提です。

🔜 iOS 27 が安定版になったら検討してよい改良

• ビジュアル版 IntentValueQuery: SemanticContentDescriptor を入力に取る生成型。ピクセルデータの MethodChannel 往復は避け、Vision（GenerateImageFeaturePrintRequest）の feature print 計算は Swift 側で完結させる設計（Flutter には結果のエンティティ id のみ返す）。
• OpenIntent 生成（検索結果 → コンテンツ遷移の軽量インテント）。
• semanticContentSearch スキーマ（App Schema カタログの visualIntelligence ドメイン）への対応。
• @UnionValue で複数エンティティ型の検索結果を返却（IntentValueQuery (structured & visual search) / IntentValueQuery対応 (WWDC26) #51 の union 対応と共通）。

[touyou]

前提の整理（Xcode 27 RC 時点）

依存していた #51 の構造化 IntentValueQuery は完了し、さらに experimental からも卒業しました（@available(iOS 26.0, *)、#if 不要）。ブリッジの土台は揃っています。

着手前に効く実測事実

VisualIntelligence.framework は iOS の実機 SDK にのみ存在し、Simulator SDK にはありません。

iPhoneOS.sdk/System/Library/Frameworks/VisualIntelligence.framework       → あり
iPhoneSimulator.sdk/System/Library/Frameworks/VisualIntelligence.framework → なし

つまり #if canImport(VisualIntelligence) がシミュレータビルドでは false になり、ビジュアル用の IntentValueQuery 型はバイナリに入りません。このリポジトリの検証手段（Simulator 上の swiftc -typecheck / flutter build ios --simulator）では検証できません。 実機か macOS destination が必要です。

姉妹プロジェクト（IntentTodo）で確認済みの関連制約:

• SemanticContentDescriptor を受ける IntentValueQuery はアプリに1つだけ（WWDC26-297 11:39）。複数エンティティ型を返したい場合は @UnionValue で1つの query に集約するのが正しい対処
• visual search が返す entity は全て openable（OpenIntent を持つ）必要がある。openable でない entity は結果に出てこない。ただしコンパイルエラーとして enforce されるのは macOS destination のビルドのみ
• SemanticContentDescriptor は labels: [String]（一般的な英語ラベル、en_US、固有名は来ない）と pixelBuffer を持つ
• IntentValueQuery は AppEntity と違い @Dependency が使える
• #if canImport(VisualIntelligence) だけに頼らない — visionOS 実機 SDK で import 可能になった時点で visionOS 非対応 API までコンパイルされて落ちた実例あり

ラベルを blocked: needs-device に変更しました（SDK は揃ったので needs-sdk ではありません）。実機検証は別途行う想定です。