デバイスとサービス

Asuka のパッケージを使うと、ビューの外にあるデバイスの機能も扱えます。カメラ、バーコードや QR コード、画像に写っているものの認識、写真とファイル、プレビュー、印刷と PDF、メールとメッセージの作成画面、位置情報、通知とプッシュ通知、サウンド、再生中の情報（Now Playing）と録音、ネットワークの状態、写真やファイルのライブラリへの保存、バックグラウンドでの処理、ほかのアプリからの共有、JavaScript、サインインと生体認証、画面、地図、ストアのサービス、クラッシュレポートです。このページでは、パッケージごとに何ができるか、その API、必要になる権限、プラットフォームごとの動作を説明します。

どのパッケージも、すべてのプラットフォームで同じ API を持ちます。iOS と Android ではほぼすべての機能が使えます。macOS、Windows、Linux では、ホストが各パッケージをデスクトップ自身のサービスで実装し、ブラウザーでは Web の API で実装します。プラットフォームに対応する機能がない場合、パッケージはその機能を持たないスマートフォンと同じように振る舞います。つまり ErrNotAvailable を返すか、足りないものを示すエラーを返すか、何もしない呼び出しになります。各パッケージの節では、何ができるか、各プラットフォームが何を使ってそれを実現しているかを説明します。さらに、各デスクトップとブラウザーにはそれぞれ専用の節があり（Mac の場合、Windows の場合、Linux の場合、ブラウザーの場合）、そこで必要な設定と、iOS や Android との違いを表にまとめています。

権限と利用目的の説明文

アプリがパッケージをインポートすると、そのパッケージに必要なものが自動で加わります。Android ではマニフェストの権限、iOS では Info.plist の利用目的の説明文（purpose string）、そしてプラットフォーム側のコードそのものです。インポートしていないパッケージのものは加わらないので、写真アプリがマイクの許可を求めることはありません。Mac アプリにも同じ説明文と、それに必要なエンタイトルメントが加わります。Windows、Linux、Web では何も宣言する必要はありません（下のそれぞれの節を参照してください）。

asuka/sdk/device、asuka/sdk/audio、asuka/sdk/splash、asuka/sdk/imageedit、asuka/sdk/widget、asuka/sdk/js、asuka/sdk/secure、asuka/sdk/preview、asuka/sdk/print は何も必要としません。

リリースビルドでエンタイトルメントを使うには、アプリの App ID（developer.apple.com の Identifiers）でそのケイパビリティ（capability）を有効にしておく必要があります。そうすれば、プロビジョニングプロファイルにもそのケイパビリティが含まれます。プロファイルに足りないケイパビリティがあると、asuka build --platform ios は何が足りないかを示して止まります。シミュレーター向けのビルドにはすべてが含まれます。

Asuka が書き込む利用目的の説明文は汎用的なもの（"To take a photo."）です。iOS と macOS はユーザーに許可を求めるときにこの文を表示するので、asuka.json の ios.usage に独自の文を書いておきましょう。

{
  "ios": {
    "usage": {
      "NSCameraUsageDescription": "To photograph your receipts.",
      "NSLocationWhenInUseUsageDescription": "To find stores near you."
    }
  }
}

各パッケージがユーザーに許可を求めるのは、起動時ではなく、初めてその機能が必要になったときです。何かを待つ呼び出し（ユーザーの操作、位置情報の測位、プラットフォームの処理）には、以下で「メインスレッド以外から呼ぶ」と書いてあります。これらはゴルーチンから呼び、結果を ui.Post でメインスレッドに戻してください（メインスレッドを参照）。それ以外の呼び出しはコールバックを受け取り、そのコールバックはメインスレッドで呼ばれます。

Mac の場合

Mac アプリ（asuka dev と asuka build）の Info.plist にも同じ利用目的の説明文が入ります（位置情報の説明文は NSLocationUsageDescription としても入ります）。アプリの署名には、許可を求める機能（カメラ、マイク、位置情報、連絡先、カレンダー、写真）に対応する Hardened Runtime のエンタイトルメントが含まれます。これがないと、Developer ID で署名したビルドはその機能へのアクセスを拒否されます。プッシュ通知の aps-environment、Sign in with Apple、App Attest は、プロビジョニングプロファイルでしか付与されないエンタイトルメントです。これらを使うアプリには、asuka build がプロファイルを埋め込みます（asuka.json の mac.profile、なければ ASUKA_MAC_PROFILE、それもなければインストール済みのプロファイルからもっとも合うもの）。プロファイルがなくてもアプリはビルドでき、CLI が何が動かないかを知らせます。その場合 Mac では、プッシュ通知の登録と Sign in with Apple が失敗し、App Attest は非対応と答えます。asuka dev はプロファイルなしでアドホック署名するので、同じことが当てはまります。Mac App Store 向けのビルド（--appstore）はサンドボックス化され、ネットワークとユーザーが選んだファイルにアクセスできます。配布を参照してください。

macOS でも各パッケージは iOS と同じフレームワーク（AVFoundation、PhotoKit、Core Location、MapKit、Vision、Speech、UserNotifications、AuthenticationServices）を通じて、iOS と同じように動きます。Mac で異なる点は次のとおりです。

Windows の場合

Windows アプリは何も宣言しません。asuka build --platform windows はケイパビリティを書き込まず、Windows はデスクトップアプリに権限を求めません。ただし「設定」の「プライバシーとセキュリティ」にあるスイッチは、カメラ、マイク、位置情報に対して有効です。オフになっていると、カメラと録音は "not allowed" で、位置情報は location.ErrDenied で失敗します。

Windows では、各パッケージは Windows 自身のサービス（Media Foundation、WIC、WinRT、Windows Hello、SAPI、資格情報マネージャー）を通じて動きます。Windows で異なる点は次のとおりです。Windows に対応する機能がない場合、パッケージはその機能を持たないデバイスと同じように振る舞います。

Linux の場合

Linux アプリも何も宣言しません。ホストが XDG デスクトップポータルを通す機能（ファイル、カメラ、位置情報、通知、メール、印刷、ファイルやリンクを開く、システムをスリープさせない）では、ポータルがいつもどおりユーザーに確認します。これは Flatpak のサンドボックスの中でも外でも同じように動きます。asuka build --platform linux が書き出す Flatpak マニフェストで、アプリがアクセスできるのはディスプレイ、GPU、ネットワーク、ポータルだけです。ホストがポータルを通さずに使うサービス（Speech Dispatcher、連絡先とカレンダーの Evolution Data Server、接続の種類を調べる NetworkManager、iio-sensor-proxy、Video4Linux のカメラ）を使うには、それらへのアクセスを開く finish-args をマニフェストに追加する必要があります。追加しない場合、パッケージはそのサービスがないシステムと同じように振る舞います。後で届く通知にはサンドボックスの外の systemd が必要です。Flatpak の中では、アプリの実行中にしか表示されません（プラットフォームごとの動作を参照）。

Linux のホストは、ポータルがあればポータルを通じて、ほかに GLib と GTK、そしてデスクトップにあるライブラリを通じて、デスクトップのサービスを使います。各ライブラリは初めて使うときに読み込まれます。ライブラリがないシステムでは、足りないものを示すエラーが返ります。

ブラウザーの場合

ページは何も宣言しません。パッケージが初めてカメラ、マイク、位置情報、通知を必要としたときに、ブラウザーがユーザーに確認します。これらの API の多くは安全なページ、つまり https か localhost から配信されるページでしか使えません（asuka dev --platform web のアドレスは該当しますが、--lan のアドレスは該当しません）。各パッケージは Web の API を呼び出します。詳しくは Web を参照してください。通知と Web Push のための Service Worker についてもそこで説明しています。

カメラ：asuka/sdk/camera

camera.Take はシステムのカメラ（iOS のカメラ画面、Android のカメラアプリ）を表示し、撮った写真のファイル（JPEG）を引数に done を呼びます。ユーザーがキャンセルした場合は "" が渡ります。カメラのないデバイス（iOS シミュレーター）では、エラーは camera.ErrNoCamera です。デスクトップにはカメラ画面がないので、Take はウィンドウの上に Asuka 独自のダイアログを出し、ライブプレビューと「写真を撮る」「キャンセル」を表示します。ブラウザーではスマートフォンのカメラか、同様のダイアログが開きます。

ui.Button(ui.ButtonProps{Title: ui.Val("Take a photo"), OnPress: func() {
	camera.Take(func(path string, err error) {
		switch {
		case errors.Is(err, camera.ErrNoCamera):
			status.Set("This device has no camera")
		case err != nil:
			status.Set(err.Error())
		case path != "":
			photo.Set(path) // ui.Image で表示する
		}
	})
}})

アプリ独自の撮影画面を作るときは、camera.View がカメラに映っているものをライブで、枠いっぱいに表示します（iOS と Mac では AVFoundation のプレビュー、Android では CameraX の PreviewView、Windows では Media Foundation のもの、Linux では GStreamer のもの、ブラウザーでは <video>）。そして camera.Capture でそこから写真を撮ります。

camera.View(camera.ViewProps{
	Mode:    camera.Video,
	Facing:  camera.Back,
	Style:   ui.Style{Grow: 1},
	OnError: func(message string) { status.Set(message) },
}),
ui.Button(ui.ButtonProps{Title: ui.Val("Photo"), OnPress: func() {
	camera.Capture(func(path string, err error) {
		if err != nil {
			status.Set(err.Error())
			return
		}
		status.Set("Saved " + path)
	})
}}),

ViewProps：

• Facing：camera.Back（既定）か camera.Front。
• Mode：camera.Photo（既定）か、asuka/sdk/camera/record で録画するための camera.Video。camera.Video でも写真は撮れます。
• Style：ビューの枠。
• OnError：カメラを表示できないときに呼ばれます。ユーザーが拒否した場合は "not allowed"、カメラがない場合は "no camera" です。
• Scan：映っているものからコードを読み取ります。asuka/sdk/scan を参照してください。

ビューは初めて表示されたときにカメラの許可を求め、ビューが画面に出ているあいだカメラはオンになります。表示するビューは一度に一つにしてください。Capture と録画は画面に出ているビューを使い、ビューがなければ "no camera view" で失敗します。

Take と Capture のファイルはアプリのキャッシュに置かれ、システムに消されることがあります。残しておきたいファイルは store.Dir() に移すか、asuka/sdk/library で写真ライブラリに保存してください。

Android：asuka/sdk/camera はカメラの権限を宣言する（ビューに必要なため）ので、Android はカメラアプリを使うときにもその権限を要求します。そのため Take は先に権限を求め、ユーザーが拒否すると "not allowed" で失敗します。

ビデオの録画：asuka/sdk/camera/record

asuka/sdk/camera/record は、画面に出ている Mode が camera.Video の camera.View からビデオを録画します。record.Start は record.Stop が呼ばれるまで（MaxDuration を設定していればその時間まで）録画し、ビデオのファイルを引数に done を呼びます。ファイルはアプリのキャッシュに置かれ、形式は iOS と Mac では .mov、Android と Windows では .mp4、Linux ではエンコーダーに応じて .mp4、それができなければ .webm です。

ui.Button(ui.ButtonProps{
	Title: signal.Func(func() string {
		if recording.Get() {
			return "Stop"
		}
		return "Record"
	}),
	OnPress: func() {
		if recording.Peek() {
			record.Stop()
			return
		}
		recording.Set(true)
		record.Start(record.Options{MaxDuration: time.Minute}, func(path string, err error) {
			recording.Set(false)
			if err != nil {
				status.Set(err.Error())
				return
			}
			status.Set("Recorded " + path) // ui.Video で再生する
		})
	},
})

音声も一緒に録音し、初回にマイクの許可を求めます。ユーザーが拒否すると、ビデオは無音になります。record.Options{Mute: true} を指定すると、許可を求めずに音声なしで録画します。録画は一度に一つだけです。

マイクの権限と利用目的の説明文は、asuka/sdk/camera ではなくこのパッケージに付いてきます。写真を撮るだけのアプリには加わりません。

バーコードと QR コード：asuka/sdk/scan

asuka/sdk/scan は、camera.View に映っているものからライブで、または画像ファイルから、バーコードと QR コードを読み取ります。iOS と Mac では AVFoundation と Vision、Android では ML Kit（asuka/sdk/scan をインポートしたアプリにだけ組み込まれます）、Windows では Go で書かれた Asuka 独自のリーダー、Linux では ZBar、ブラウザーでは BarcodeDetector を使います。すべてのリーダーがすべての種類に対応しているわけではありません。Windows の場合と Linux の場合を参照してください。

scan.Codes はビューの Scan を作ります。指定した種類（指定しなければすべての種類）を読み取り、コードが視界に入るとメインスレッドで関数を呼びます。コードが映り続けているあいだは一度だけで、1 秒間視界から外れたあとにまた映ると、もう一度呼びます。

camera.View(camera.ViewProps{
	Style: ui.Style{Grow: 1},
	Scan: scan.Codes(func(c scan.Code) {
		found.Set(fmt.Sprintf("%s: %s", c.Kind, c.Value))
		ui.Haptic(ui.HapticSuccess)
	}, scan.QR, scan.EAN13),
})

scan.File は、撮影した写真や選んだ写真などの画像からコードを読み取り、それらを引数に done を呼びます（コードがなければ空です）。

scan.File(path, func(codes []scan.Code, err error) {
	switch {
	case err != nil:
		found.Set(err.Error())
	case len(codes) == 0:
		found.Set("No code in it")
	default:
		found.Set(codes[0].Value)
	}
}, scan.QR)

scan.Code は、種類を表す Kind と、コードが保持するテキストである Value からなります。種類は QR、Aztec、DataMatrix、PDF417、EAN13、EAN8、UPCA、UPCE、Code128、Code39、Code93、Codabar、ITF です。

iOS は UPC-A を先頭に 0 の付いた EAN-13 として読み取ります。UPCA を指定した場合、Asuka はそれを UPC-A に戻して返します。

画像の内容の認識：asuka/sdk/vision

vision.Analyze(path, options) は、画像の中のテキスト、顔、コードと、それぞれの位置を見つけます。処理はデバイス上で行われます。iOS と Mac では Apple の Vision、Android では ML Kit の同梱モデル（asuka/sdk/vision をインポートしたアプリにだけ組み込まれます）、Windows では Windows の OCR と顔検出、Linux では Tesseract（顔は検出できません）、ブラウザーでは Shape Detection API が対応しているものを使います。メインスレッド以外から呼んでください。

go func() {
	r, err := vision.Analyze(photo, vision.Options{Languages: []string{"zh-Hans", "en-US"}})
	if err != nil {
		return
	}
	ui.Post(func() {
		for _, l := range r.Lines {
			fmt.Println(l.Text, l.Box)
			for _, w := range l.Words {
				fmt.Println(" ", w.Text, w.Box, w.Start, w.End)
			}
		}
		fmt.Println(len(r.Faces), "faces,", len(r.Codes), "codes")
	})
}()

• Box は、画像を正しい向きにしたときの左上を起点に、画像に対する割合で表します。そのため、画像に重ねたビューでも asuka/sdk/imageedit のピクセルでも、どの縮尺でも同じ値で使えます。
• Line は Text、Box、Words を持ちます。Word は、プラットフォームの単語分割が見つけた単語（中国語と日本語では辞書に基づく分割）か、句読点一つです。Start と End は行のテキストにおける単語の位置を、rune 単位で表します。
• Code は Kind（asuka/sdk/scan と同じ名前）、Value、Box を持ちます。
• Options で不要なもの（NoText、NoFaces、NoCodes）をオフにできます。Languages はテキストの言語を可能性の高い順に並べたもので、iOS だけで使われます。Vision がうまく読めるのは先頭の言語が属する系統の文字だけなので、中国語が含まれうる場合は中国語を先頭にしてください。中国語のモデルはラテン文字も読めます。Android は常に中国語とラテン文字を読み取ります。

iOS は読み取ったものを一つのまとまりとして枠で囲みます。中国語の行で枠を共有する単語は、その枠を各単語の幅で分け合うので、そうした単語の枠は推定値です。Vision が返すバーコードの枠は、読み取りに使った線になることがあります。Asuka はそれをバー全体まで広げます。Android では、単語の枠は各文字（symbol）の枠から求めます。

OCR は渡された画像を独自のサイズに縮小するので、非常に縦長のスクリーンショットでは小さな文字が読めなくなります。imageedit.Crop で切り分けて、それぞれを解析してください。

写真ライブラリ：asuka/sdk/photos

asuka/sdk/photos は、ユーザーの許可を得てユーザーのライブラリを読み取ります。iOS と Mac では PhotoKit、Android では MediaStore、Windows ではピクチャフォルダーを使います。Linux と Web にはアプリが読めるライブラリがないので、アクセスは Denied です。このパッケージは、ライブラリそのものを画面にするアプリのためのものです。ユーザーに数枚の写真を選んでもらうだけなら、権限を求めない device.PickPhotos を使えます。それで足りる場合はそちらを使ってください。Google Play は、ライブラリを読むアプリにその理由を Play Console で尋ねます。どの呼び出しも待つので、メインスレッド以外から呼んでください。

go func() {
	if a, _ := photos.Request(); a == photos.Denied {
		return
	}
	assets, _ := photos.List(photos.Query{Screenshots: true, Limit: 60})
	thumb, _ := photos.Thumbnail(assets[0].ID, 300) // ui.Image 用のファイル
	full, _ := photos.Export(assets[0].ID)          // オリジナルをファイルとして
	fmt.Println(thumb, full.Path, full.Name)
}()

• photos.Current() は、許可を求めずに現在の状態を返します。NotAsked、Denied、Limited（ユーザーが選んだ写真だけ。iOS 14、Android 14）、Allowed のいずれかです。photos.Request() は初回に許可を求めます。photos.ManageLimited() を使うと、Limited のユーザーが対象の写真を変更できます。
• photos.List(query) は新しい順に、Offset から最大 Limit 件を返します。Asset は ID、Width、Height、Created()、Screenshot を持ちます。Screenshots を指定するとスクリーンショットだけに絞り込みます。iOS はスクリーンショットかどうかを知っていますが、Android では Screenshots フォルダーにあるものがスクリーンショットとして扱われます。
• photos.Thumbnail(id, size) は、短辺が size ピクセル以上の JPEG を返します。次回のためにアプリのキャッシュに保存されます。
• photos.Export(id) は、ライブラリにあるままの画像（HEIC、JPEG、PNG）をファイル名ごとコピーします。iCloud の写真は先にダウンロードされます。

写真、ブラウザー、クリップボード：asuka/sdk/device

asuka/sdk/device は、ビューの外でプラットフォームが提供する機能をまとめたものです。

ui.Button(ui.ButtonProps{Title: ui.Val("Pick photos"), OnPress: func() {
	device.PickPhotos(3, func(paths []string, err error) {
		if err == nil && len(paths) > 0 {
			photos.Set(paths)
		}
	})
}}),
ui.Button(ui.ButtonProps{Title: ui.Val("Help"), OnPress: func() {
	device.Browse("https://example.com/help")
}}),

• device.PickPhotos(limit, done) は、システムの写真ピッカー（iOS では PHPicker、Android では写真選択ツール、デスクトップではファイルを開くダイアログ、ブラウザーではファイル選択）を表示し、最大 limit 枚（1〜255）の画像を選ばせます。権限は求めません。選ぶのはユーザーで、アプリに見えるのは選ばれたものだけです。done には画像のファイルが渡され、ui.Image で表示できます。ユーザーがキャンセルした場合は空です。ファイルはアプリの一時ファイルかキャッシュに置かれたコピーなので、残しておきたいものは移動してください。
• device.Browse(url) は、アプリの画面の上に Web ページを表示します（SFSafariViewController、Custom Tab）。URL は http か https でなければなりません。これに対して ui.OpenURL は、アプリを離れてブラウザーで開きます。デスクトップではユーザーのブラウザーで、ブラウザーでは新しいタブでページを開きます。
• device.Clipboard() はクリップボードのテキストを読み取ります。テキストがなければ ok は false です。メインスレッド以外から呼んでください。iOS では、ほかのアプリが置いたものをアプリが初めて読むときにユーザーに確認します。書き込むには ui.Copy を使います。
• device.KeepAwake(on) は、on が true のあいだ画面をオンのままにします。ビデオ、レシピ、地図などに使います。それを必要とする画面が閉じたらオフにしてください。
• device.PickFiles(options, done) は、システムのドキュメントピッカー（iOS の「ファイル」ブラウザー、Android のストレージピッカー、デスクトップではファイルを開くダイアログ、ブラウザーではファイル選択。権限は不要）を表示します。Types は MIME タイプ（"application/pdf"、"image/*"。指定しなければどのファイルでも）で、Multiple を指定すると複数選べます。done には選ばれたファイルごとに device.File が渡されます。Path はアプリのキャッシュにあるコピーで、Name、Type、Size も持ちます。ユーザーがキャンセルした場合は空です。
• device.ClipboardHas() は、クリップボードの中身を読まずに、Text、Image、URL のどれがあるかを返します（iOS はこのときユーザーに確認しません）。貼り付けるものがあるときだけ「ペースト」ボタンを表示する、といった使い方ができます。device.ClipboardImage() はクリップボードの画像を、コピーされたときの形式のままファイルに読み出します。device.CopyImage(path, done) は画像ファイルをクリップボードに置きます。device.OnClipboardChange(f) は、stop を呼ぶまで、クリップボードが変わるたびに f を呼びます。
• device.GetInfo() はデバイスとアプリの情報を返します。Model（"iPhone"、"Pixel 9"、"Mac"、"PC"）、System（"iOS"、"Android"、"macOS"、"Windows"、"Linux"）、SystemVersion、そして asuka.json の version と build である AppVersion と Build です。メインスレッド以外から呼んでください。

func Player() ui.Node {
	info := signal.New("")
	go func() {
		if i, err := device.GetInfo(); err == nil {
			ui.Post(func() { info.Set(i.Model + ", " + i.System + " " + i.SystemVersion) })
		}
	}()
	device.KeepAwake(true)
	signal.OnCleanup(func() { device.KeepAwake(false) })
	return ui.Text(info)
}

Web でのサインイン：asuka/sdk/webauth

webauth.Start は、システム自身のサインインシートにサインインページを表示します。iOS では ASWebAuthenticationSession（SwiftUI の webAuthenticationSession）、Android では Custom Tab です。中身はブラウザーなので、ユーザーのセッション、パスキー、パスワードの自動入力がそのまま使えます。また、アプリ独自の WebView を拒否するプロバイダー（Google のサインイン）にも拒否されません。OAuth には ui.WebView ではなくこちらを使ってください。

Mac にも ASWebAuthenticationSession があります。Windows と Linux にはシステムのシートがないので、ホストがウィンドウの上に独自の Web ビュー（WebView2、WebKitGTK）を開いてページを表示します。この Web ビューはアプリの Web プロファイルを使い、ユーザーのブラウザーのセッションは持ちません。また、埋め込みの Web ビューを拒否するプロバイダーには、ここでも拒否されます。ブラウザーではページをポップアップで開き、アプリと同じオリジンのページに戻ってきたら完了です（カスタムスキームではページを開けないため）。

s := webauth.Start(webauth.Options{URL: authorizeURL, CallbackScheme: "myapp"},
	func(callback string, err error) {
		if errors.Is(err, webauth.ErrCanceled) {
			return // ユーザーが閉じた
		}
		// callback は myapp://…?code=…。コードを交換する。
	})

終わり方は 2 通りあります。

• コールバックスキーム。 ページが CallbackScheme（アプリ自身のスキーム）の URL に移動すると、シートが閉じて done にその URL が渡されます。Android では、スキームはアプリのもの、つまり asuka.json の scheme でなければなりません。その URL は ui.OnOpenURL ではなく done に届きます。
• アプリが終わらせる。 スキームを使わない場合は、アプリが受け取れる場所にページをリダイレクトさせます。ループバックインターフェースへのリダイレクト（http://localhost:port/callback、RFC 8252）を許す OAuth サーバーなら、そのポートでアプリが動かしているサーバーにコードを送ってくるので、そのサーバーが s.Cancel() を呼んでシートを閉じます。Android では、キャンセルするとタブの上にアプリが戻ってきます。

ユーザーがシートを閉じたとき、または Cancel で閉じたとき、done には webauth.ErrCanceled が渡ります。Ephemeral を指定すると、ブラウザーの Cookie を使わないプライベートセッションを求めます（iOS の prefersEphemeralWebBrowserSession。Android の Custom Tab は Cookie を保持します）。examples/usage は、この方法とループバックサーバーで Claude にサインインします。

コピー、共有、URL を開く：ui.Copy、ui.Share、ui.OpenURL

ui には、テキストをシステムに渡す呼び出しが 3 つあります。どれもメインスレッドで動きます。

ui.Button(ui.ButtonProps{Title: ui.Val("Copy link"), OnPress: func() { ui.Copy("https://example.com/s/42") }}),
ui.Button(ui.ButtonProps{Title: ui.Val("Share"), OnPress: func() { ui.Share("https://example.com/s/42") }}),
ui.Button(ui.ButtonProps{Title: ui.Val("Open in browser"), OnPress: func() { ui.OpenURL("https://example.com") }}),
ui.Button(ui.ButtonProps{Title: ui.Val("Call"), OnPress: func() { ui.OpenURL("tel:+15555550100") }}),

• ui.Copy(text) はテキストをクリップボードに置きます。
• ui.Share(text) はシステムの共有シートを表示し、アプリ、連絡先、AirDrop、Nearby Share にテキストを送れるようにします。URL はリンクとして共有されます。Mac では共有サービスのピッカー、Windows では共有 UI、ブラウザーでは Web Share のシート（ある場合）が表示されます。Linux には共有シートがないので、テキストはクリップボードにコピーされ、トーストが表示されます（Web Share のないブラウザーでも同じくコピーされます）。
• ui.OpenURL(url) は、URL を開くようシステムに頼みます。Web のアドレスはブラウザーで、それ以外のスキーム（tel:、mailto:、ほかのアプリのスキーム）はそれを扱うアプリで開きます。

ui.ShareFiles(paths, options, done) は、ファイルの共有シートを表示します。送りたいビデオ、「ファイル」に保存したい PDF、AirDrop で送りたい写真などに使います。done は、ユーザーが共有したかどうかにかかわらず、シートが閉じたあとにメインスレッドで呼ばれます。シートを表示できなかった（ファイルが存在しない）場合は、エラーでそれを知らせます。

var share ui.Node
share = ui.Button(ui.ButtonProps{Title: ui.Val("Share"), OnPress: func() {
	ui.ShareFiles([]string{report}, ui.ShareOptions{MIME: "application/pdf", Title: "Send the report", From: share}, func(err error) {
		if err != nil {
			status.Set(err.Error())
		}
	})
}})

ShareOptions は expo-sharing と同じものです。

iOS では、拡張子がタイプと合わないファイルは、expo-sharing と同じく、タイプに合う名前で共有されます。たとえば JPEG として共有した image.pdf は image.pdf.jpeg として送られます。これはコピーではなく、ファイルへのリンクです。Android では、ファイルはアプリの FileProvider を通じて渡されます。アプリ自身のフォルダーの外にあるファイルは、先にキャッシュにコピーされます。Mac では共有サービスのピッカーです。Windows では共有 UI です（Windows はいつ閉じたかを知らせないので、done は表示された時点で呼ばれます）。Linux には共有シートがないので、テキストの共有と同じく、ファイルはクリップボードに置かれます。ブラウザーでは、可能なら Web Share のシートでファイルを共有し、できなければファイルを一つずつダウンロードします。

アプリ自身を URL で開けるようにするには、配布の asuka.json の scheme と links、そして ui.OnOpenURL を参照してください。

ファイルのプレビュー：asuka/sdk/preview

preview.Show(sources, options, done) は、メールアプリが添付ファイルを表示するように、システムのビューアーでファイルを表示します。PDF、画像、ビデオ、オーディオ、Office と iWork の書類、テキストに対応します。ソースには、ファイルのパス、アセットのパス（ui.Image が受け取る形式）、http(s) の URL を指定できます。URL の場合、ホストが先にアプリのキャッシュへ、元の名前で（またはサーバーが返すタイプの拡張子を付けて）ダウンロードします。メインスレッドで呼びます。

var open ui.Node
open = ui.Button(ui.ButtonProps{Title: ui.Val("Open the invoice"), OnPress: func() {
	preview.Show([]string{invoice, "docs/terms.pdf"}, preview.Options{From: open}, func(err error) {
		if errors.Is(err, preview.ErrNoViewer) {
			status.Set("Nothing on this device opens it")
		}
	})
}})

done はビューアーが閉じたあとにメインスレッドで呼ばれます。ファイルを表示できるものがない場合は preview.ErrNoViewer が、それ以外の問題（ファイルが存在しない、ダウンロードに失敗した）の場合はほかのエラーが渡ります。

Android にはシステムのビューアーも、複数のファイルをめくれるビューアーもありません。そのため、Android のメールアプリが添付ファイルを一つずつ開くのと同じく、一つのファイルだけを開きます。

印刷と PDF：asuka/sdk/print

asuka/sdk/print は、ファイル、HTML マークアップ、WebView のページに対して、プリンターとオプション（部数、ページ、用紙、向き。Android と Mac では「PDF として保存」も）を備えたシステムの印刷ダイアログを表示します。また、HTML をページに割り付けて PDF にすることもできます。PDF 以外の呼び出しはメインスレッドで動き、ダイアログが閉じると done に print.Result が渡ります。

var printButton ui.Node
printButton = ui.Button(ui.ButtonProps{Title: ui.Val("Print"), OnPress: func() {
	print.HTML(receipt, print.Options{Job: "Receipt", From: printButton}, func(r print.Result, err error) {
		if err == nil && r == print.Printed {
			status.Set("Sent to the printer")
		}
	})
}})

• print.File(source, options, done) は PDF か画像を印刷します（ソースは preview.Show と同じく、パス、アセット、http(s) の URL）。それ以外のタイプは print.ErrUnsupported で失敗します。ただし Windows と Linux は例外です（プリンターが、CUPS で印刷できるものを受け付けます）。
• print.HTML(markup, options, done) はマークアップを、ブラウザーがページを印刷するのと同じようにページ分けして印刷します。CSS の @media print と break-before が効きます。画像とスタイルは絶対 URL（https:、data:）から読み込みます。
• print.WebView(web, options, done) は ui.WebView に表示されているものを印刷します。

Options には、キューに表示されるジョブ名の Job（既定はファイル名、ページのタイトル、どちらもなければアプリ名）、ダイアログを開いたときの向きの Orientation（print.Portrait、print.Landscape）、ダイアログがポップオーバーになる場合（iPad）にダイアログが指し示すビューの From があります。

Result は、print.Printed（ジョブがプリンターのキューに入った、またはダイアログから PDF として保存された）、print.Cancelled、プラットフォームが結果を知らせない場合の print.Unknown のいずれかです。失敗したジョブはエラーになります。print.ErrUnavailable は、デバイスが印刷できないことを示します。

Android と iOS では、写真の印刷と同じく、横長の画像は横向きで始まります。

HTML から PDF を作る

print.PDF(markup, options) は、print.HTML と同じようにマークアップをページに割り付けますが、ダイアログは出さず、アプリのキャッシュに PDF を書き出します。ファイル名はページの <title> から付けられます（"Receipt.pdf"。<title> がなければ "Document.pdf"）。戻り値はそのパスで、共有したり、メールで送ったり、移動したりできます。テキストはテキストのまま残るので、検索も選択もできます。メインスレッド以外から呼んでください。

go func() {
	path, err := print.PDF(receipt, print.PDFOptions{Page: print.A4, Margins: print.Uniform(48)})
	ui.Post(func() {
		if err == nil {
			ui.ShareFiles([]string{path}, ui.ShareOptions{Title: "Receipt"}, nil)
		}
	})
}()

レイアウトは、iOS では WebKit（UIPrintPageRenderer と Web ビューの print formatter）、Android では WebView の print adapter、Mac では WebKit の print operation、Windows では WebView2（Chromium の Page.printToPDF）、Linux では WebKitGTK（ファイルへの印刷）で行います。ブラウザーは印刷ダイアログを通してしか PDF を作れないので、PDF は失敗します。代わりに print.HTML を使えば、ユーザーが「PDF として保存」を選べます。

メールとメッセージ：asuka/sdk/compose

asuka/sdk/compose は、システムのメールとメッセージの作成画面を、内容を入れた状態で開きます。送信するのはユーザーです。メインスレッドで呼び、done には compose.Result が渡ります。compose.Sent、Saved（下書き）、Cancelled、またはメールをほかのアプリが扱っていて結果を知らせない場合の Unknown のいずれかです。

compose.Mail(compose.MailMessage{
	To:      []string{"support@example.com"},
	Subject: "Order 1042",
	Body:    "<p>Hello,</p><p>The receipt is attached.</p>",
	HTML:    true,
	Attachments: []compose.Attachment{{Source: receiptPDF, Name: "Receipt 1042.pdf"}},
}, func(r compose.Result, err error) {
	if errors.Is(err, compose.ErrUnavailable) {
		status.Set("Set up a mail account to send it")
	}
})

compose.Message(compose.TextMessage{To: []string{"+15555550100"}, Body: "On my way"}, nil)

MailMessage は、宛先の To、CC、BCC、件名の Subject、本文の Body（HTML なら HTML マークアップ）、Attachments を持ちます。TextMessage は、To（電話番号か iMessage のアドレス）、Subject（「メッセージ」で件名がオンになっている場合。そうでなければ本文の前に入ります）、Body、Attachments を持ちます。Attachment は、Source（パス、アセット、http(s) の URL）、Type（既定は拡張子から決まるタイプ）、受信者に表示される Name（既定はファイル名）からなります。メールがマークアップを運べない場合（mailto: リンク、Simple MAPI）、本文は compose.PlainText で作ったものと同じテキストとして送られます。

compose.Check() はデバイスで何ができるかを返します（メインスレッド以外から呼んでください）。Mail はメールのアカウントかアプリがあること、MailComposer は iOS 自身の作成画面があること（ユーザーの操作の結果が分かり、添付ファイルも扱えます）、Text はテキストメッセージ、TextAttachments は添付ファイル付きのメッセージを送れることを表します。CanSendMail、CanSendText、CanSendAttachments はそれぞれ一つずつを調べます。デバイスでできない呼び出しは compose.ErrUnavailable で失敗します。

iOS シミュレーターには「メール」のアカウントも「メッセージ」もないので、作成画面は実機で試してください。

位置情報：asuka/sdk/location

asuka/sdk/location は、ユーザーの許可を得て、デバイスの現在地と移動中の位置を取得します。許可は初回に求めます。iOS と Mac では Core Location、Android では Android の位置情報マネージャー（Google Play 開発者サービスは不要）、Windows では WinRT の Geolocator、Linux では位置情報ポータル（または GeoClue）、ブラウザーでは Geolocation API を使います。求めるのはアプリの使用中の位置情報で、バックグラウンドでの位置情報ではありません。

location.Current() はデバイスの現在地を返します。ユーザーの応答を待ち、さらに測位を待つので、メインスレッド以外から呼んでください。ユーザーが許可していなければ、エラーは location.ErrDenied です。

ui.Button(ui.ButtonProps{Title: ui.Val("Where am I?"), OnPress: func() {
	go func() {
		p, err := location.Current()
		ui.Post(func() {
			switch {
			case errors.Is(err, location.ErrDenied):
				where.Set("Allow location in Settings")
			case err != nil:
				where.Set(err.Error())
			default:
				where.Set(fmt.Sprintf("%.4f, %.4f (within %.0f m)", p.Latitude, p.Longitude, p.Accuracy))
			}
		})
	}()
}})

location.Watch(f) は、stop が呼ばれるまで、デバイスが動くたびにその位置を引数に f をメインスレッドで呼びます。最初の呼び出しは現在地です。許可の求め方は Current と同じで、ユーザーが拒否すると f は呼ばれません。コンポーネントと一緒に止めてください。

func Track() ui.Node {
	here := signal.New(location.Position{})
	stop := location.Watch(func(p location.Position) { here.Set(p) })
	signal.OnCleanup(stop)
	return ui.Text(signal.Func(func() string {
		p := here.Get()
		return fmt.Sprintf("%.5f, %.5f", p.Latitude, p.Longitude)
	}))
}

location.PlaceName(lat, lon) は、その場所の名前（"Mission District, San Francisco"）を返します。プラットフォームのジオコーダーがサーバーに問い合わせるので、ユーザーが名前を求めたときだけ呼んでください。メインスレッド以外から呼びます。Windows では OpenStreetMap の Nominatim に、Linux では geocode-glib（インストールされていれば）に問い合わせます。ブラウザーにはジオコーダーがないので、失敗します。

location.Position は、Latitude、Longitude、Accuracy（メートル単位。デバイスがその半径内にいることを表します）、Altitude（海抜のメートル数。分からなければ 0）、Time を持ちます。

Android：Current は、直近 1 分以内の測位があればそれを返します。なければ新しい測位を最大 10 秒待ち、それでも得られなければ最後に分かっている位置を返すか、"no location" で失敗します。

通知：asuka/sdk/notify

asuka/sdk/notify はローカル通知を、すぐに、またはアプリが決めた時刻に表示します。その時刻にアプリが動いているかどうかは問いません。通知をタップすると、その URL でアプリが開きます。メッセージングアプリに必要な機能もそろっていて、asuka/sdk/push の通知にも使えます。通知内で入力するアクションと返信、スレッド、Android のチャンネル、会話のメッセージ、バッジ、表示中の通知、アプリを開いているあいだにどの通知を表示するか、です。

go func() {
	ok, err := notify.Request()
	if err != nil || !ok {
		return
	}
	err = notify.Schedule(notify.Notification{
		ID:    "water",
		Title: "Water the plants",
		Body:  "It's been a day.",
		URL:   "myapp://plants",
		After: 24 * time.Hour,
	})
	if err != nil {
		fmt.Println(err)
	}
}()

• notify.Request() は初回にユーザーへ通知の許可を求め、許可されているかどうかを返します。そのときのユーザーの答え、またはその後ユーザーが「設定」で変えた状態です。メインスレッド以外から呼んでください。
• notify.Schedule(n) は、今から n.After 後（1 秒以上）に n を表示するよう予約します。notify.Show(n) はすぐに表示します。待機中または表示中の通知と同じ ID を持つ通知は、それを置き換えます。メインスレッド以外から呼んでください。
• notify.Cancel(id) は、待機中か表示済みかにかかわらず通知を取り消します。メインスレッドで呼びます。

Notification の URL には、アプリのスキーム（asuka.json の scheme）の URL を指定してください。ユーザーが通知をタップすると、ui.OnOpenURL がそれを受け取ります。ほかのフィールドは次のとおりです。

iOS は、Present で別の指定をしない限り、アプリを開いているあいだも通知をバナーで表示します。Android は予約した通知を不正確なアラーム（exact alarm の権限は不要）で投稿するので、予定の時刻より少し遅れることがあります。

アクションと返信

カテゴリーは、通知の種類とそのボタンを表します。アプリのカテゴリーは起動時にルートコンポーネントで、カテゴリーを指定した通知（プッシュ通知も含みます。iOS では aps.category、Android ではデータの "category"）が届く前に設定してください。設定は起動をまたいで保持されます。

notify.SetCategories(notify.Category{ID: "message", Actions: []notify.Action{
	{ID: "reply", Title: "Reply", Icon: "arrowshape.turn.up.left",
		Reply: &notify.Reply{Button: "Send", Placeholder: "Message"}},
	{ID: "read", Title: "Mark as Read"},
	{ID: "delete", Title: "Delete", Destructive: true, Unlock: true},
	{ID: "open", Title: "Open", Open: true},
}})

notify.OnAction(func(r notify.Response) {
	switch r.Action {
	case "": // 通知そのもののタップ
		openChat(r.Notification.Thread)
	case "reply":
		_, done := r.Defer() // 送信には少し時間がかかる
		go func() {
			defer done()
			api.Send(r.Notification.Thread, r.Reply)
		}()
	case "read":
		notify.RemoveThread(r.Notification.Thread)
	}
})

• Action は、ID と Title、Icon（SF Symbol。iOS 15 と macOS 12 で表示されます。Android のアクションにはアイコンが表示されません）、Destructive（iOS では赤で表示されます）、Unlock（先にデバイスのロックを解除させます。iOS、Android 12 以降）、Open（アプリを開きます）、Reply（テキスト欄。送信ボタンのタイトルとプレースホルダーを指定します）を持ちます。
• notify.OnAction(f) は、stop を呼ぶまで、応答があるたびにそれを引数に f をメインスレッドで呼びます。応答は、タップ（Action が ""）かアクションです。Reply は入力されたテキスト、Notification は応答の対象になった通知（asuka/sdk/push の通知も含みます）です。f を設定する前に来た応答（アプリを起動した応答や、アプリを起こした応答）は最初の f を待つので、OnAction はアプリの起動時に設定してください。
• Open のないアクションはバックグラウンドで実行されます。アプリの Go のコードが動きますが（アプリが動いていなければ画面なしで起動され、main、続いてルートコンポーネントが実行されます。ルートコンポーネントは OnAction を呼ぶ必要があります）、アプリは前面に出てきません。f が戻ったあとも続く処理がある場合は、f の中で r.Defer() を呼び、処理が終わったら done を呼びます。システムはそれまで、または ctx の期限（システム自身の期限より少し前）までアプリを動かし続けます（iOS では約 30 秒、Android では約 10 秒です）。

Android は、iOS と同じく、バックグラウンドのアクションが終わるまでにアプリがその通知を（同じ ID で Show して）表示し直さなければ、通知を消します。返信のあと、Android は通知がもう一度投稿されるのを待ちます（それまでスピナーが回り続けます）。そのため Asuka は、会話の通知にはユーザーの名前で返信を加え、それ以外の通知は消します。

スレッドと表示中の通知

Thread はチャットの通知をまとめます。iOS では通知を重ねて表示し、Android ではサマリー通知の下のグループにまとめます。このサマリー通知は、通知の出入りに合わせて Asuka が管理します。

• notify.Showing() は、表示中（通知センター、通知シェード）のアプリの通知を、プッシュ通知も含めて新しい順に返します。各 Delivered は、ID、Title、Subtitle、Body、URL、Data、Category、Thread、Time、そしてプッシュ通知かどうかを示す Remote を持ちます。メインスレッド以外から呼んでください。
• notify.Remove(ids...)、notify.RemoveThread(thread)（読み終えたチャットに使います）、notify.RemoveAll() は通知を消します。メインスレッドで呼びます。

アプリを開いているあいだに表示する通知

notify.Present(func(n notify.Delivered) notify.Presentation {
	if n.Thread == openChat.Peek() {
		return notify.Hide // そのチャットが画面に出ている
	}
	return notify.Banner
})

notify.Present(f) を使うと、アプリがフォアグラウンドにあるあいだに届いた通知をどう表示するかを f で決められます。Banner（アプリを閉じているときと同じ）、Quiet（バナーも音もなしで、通知センターや通知シェードに入れる）、Hide のいずれかを返します。f は通知が届いたときにメインスレッドで呼ばれ、すぐに答えを返す必要があります。ホストは最大 1 秒待ち、それを過ぎると通知を表示します。nil を渡すと、ふたたびすべての通知を表示します。メインスレッドで呼びます。

会話のメッセージ

メッセージは、プラットフォームがメッセージを表示するのと同じ形で、送信者の写真付きで表示されます。iOS では通信通知（communication notification）、Android では会話（通知シェードの「会話」セクションに、会話のショートカット付きで表示）です。

ana := notify.Person{ID: "u7", Name: "Ana", Image: "https://example.com/ana.jpg"}
chat := notify.Conversation{ID: "climbing", Title: "Climbing", Group: true}
go notify.Show(notify.Notification{Body: "Who's in for Saturday?", Category: "message"}.From(ana, chat))

• n.From(sender, c) は n をメッセージにします。sender が c で n.Body を発言した、という意味になります。ID と Thread の既定値は会話の ID（1 対 1 の会話では送信者の ID）、Title の既定値は送信者の名前（グループではグループのタイトル）です。
• Person は、ID（毎回同じもの）、Name、Image（ソースは ui.Image と同じ）、Bot を持ちます。Conversation は、ID、グループの Title と Image、Group、Me（会話の中でのユーザーの表示。Android はユーザーの返信にこの名前を付けます。既定は "You"）、それ以前のメッセージ Earlier を持ちます。
• Android は一つの会話を一つの通知として表示し、メッセージをその中に並べます。新しいメッセージは表示中の会話の通知に加わります（または Earlier でそれより前のメッセージを設定します）。iOS はメッセージを一つずつ別の通知として、会話のスレッドの中に表示します。
• iOS では、App ID で Communication Notifications ケイパビリティを有効にする必要があります。From を呼ぶアプリにはそのエンタイトルメントと、Info.plist の NSUserActivityTypes（INSendMessageIntent）が加わります。リリースビルドのプロファイルにもこのケイパビリティが含まれていなければなりません。含まれていない場合、メッセージは普通の通知として表示されます。macOS はメッセージを普通の通知として表示します。

Android の通知チャンネル

チャンネルは通知の種類の一つで、ユーザーはアプリの設定でチャンネルごとにオフにしたり、音を消したりできます。Android は通知を、そのチャンネルの音、バイブレーション、重要度で表示します。iOS にはチャンネルがないので、無視されます。

notify.SetChannelGroups(notify.ChannelGroup{ID: "chats", Name: "Chats"})
notify.SetChannels(
	notify.Channel{ID: "messages", Name: "Messages", Importance: notify.ImportanceHigh, Group: "chats"},
	notify.Channel{ID: "digest", Name: "Daily digest", Importance: notify.ImportanceLow, NoBadge: true},
)

• notify.SetChannels(cs...) はチャンネルを作り、以前に作ったチャンネルの名前を更新し、以前に作ったもののうち cs にないチャンネルを削除します。チャンネルの Importance（ImportanceDefault、ImportanceHigh：ヘッドアップ通知、ImportanceLow：音なし、ImportanceMin）、Silent、NoVibration、NoBadge は作成時に決まり、その後はユーザーが変えるものになります。notify.SetChannelGroups(gs...) はグループに対して同じことをします（グループを削除すると、そのチャンネルも削除されます）。メインスレッドで呼びます。
• Channel を指定しない通知、または存在しないチャンネルを指定した通知は、既定のチャンネル（"Notifications"）に入ります。既定のチャンネルは削除されません。プッシュ通知では、FCM の android.notification.channel_id、またはデータメッセージの "channel" でチャンネルを指定します。

バッジ

notify.SetBadge(n) はアプリのアイコンの数字を設定します。0 を渡すと消えます。iOS と macOS（Dock）は設定したとおりに表示します。Android には独自のバッジがありません。バッジを表示するランチャーはアプリの通知を数える（またはドットを表示する）ので、通知が読まれる（Remove、RemoveThread）とバッジは消え、SetBadge は何もしません。通知の Badge は、ランチャーが表示するかもしれない数字です。NoBadge を指定したチャンネルの通知は数えられません。

プラットフォームごとの動作

macOS ではアプリのバンドルが必要です。asuka dev と asuka build はバンドルからアプリを実行します。単体で実行した実行ファイル（go run）には bundle ID がないので、呼び出しはその旨を示すエラーで失敗します。Windows はトーストを、すぐに、または予約して表示します。画像も表示でき、カテゴリーのアクションはボタン、返信はテキストボックスになります。アプリは初回に自分自身を登録します（AppUserModelID、つまり asuka.json の id を持つスタートメニューのショートカットと、COM のアクティベーター。どちらもユーザーのレジストリに、アプリの実行ファイルを指して登録します）。これにより、タップやボタンの操作がアプリに届き、アプリが動いていなければ Windows がアプリを起動します。バックグラウンドのアクションでは、アプリは見えないまま動き、OnAction が終わると終了します。バッジは、アプリのタスクバーボタンに描かれる数字です（パッケージ化されたアプリでは、システムのバッジ）。Windows は、予約したトーストを Present の答えにかかわらず表示します。Linux は、アプリにデスクトップファイルがある（またはサンドボックスで動いている）場合は GNotification として通知を送り、そうでなければデスクトップの通知サーバーに直接送ります（GNOME Shell は、デスクトップファイルのないアプリの通知を受け付けません）。タップやボタンの操作は、アプリの実行中にアプリに届きます。後で届く通知は systemd のユーザータイマー（systemd-run --user）になります。タイマーはアプリの実行ファイルをウィンドウなしで起動して通知を表示し、アプリが動いていればアプリに処理を渡し、タップされればアプリを起動します。systemd がない場合（Flatpak、asuka dev）は、アプリの実行中にしか表示されません。ブラウザーは、アプリの Service Worker を通じて通知を表示し、asuka/sdk/push には Web Push を使います。詳しくは Web を参照してください。

サウンド: asuka/sdk/audio

asuka/sdk/audio は、プラットフォームのプレイヤーで効果音や音楽を再生します。iOS と Mac では AVPlayer、Android では Media3 の ExoPlayer、Windows では MCI、Linux では GStreamer の playbin、ブラウザーでは audio 要素を使います（ブラウザーでは、ユーザーがページ内をタップかクリックするまで再生されません）。音源には、アプリの assets/ にあるファイル、アプリが書き出したファイル、http(s) の URL（ファイルでもストリームでもかまいません）を指定できます。

audio.Play(source) は、音を最初から一度だけ再生し、終わったら解放します。チャイムやクリック音に向いています。それ以上の操作が必要なら、audio.Load で *audio.Player を作ります。

func Sounds() ui.Node {
	music := audio.Load("music/theme.m4a")
	music.SetLoop(true)
	music.SetVolume(0.5)
	signal.OnCleanup(music.Release)
	return ui.Column(nil,
		ui.Button(ui.ButtonProps{Title: ui.Val("Ding"), OnPress: func() { audio.Play("sounds/ding.wav") }}),
		ui.Button(ui.ButtonProps{Title: ui.Val("Play"), OnPress: music.Play}),
		ui.Button(ui.ButtonProps{Title: ui.Val("Pause"), OnPress: music.Pause}),
		ui.Button(ui.ButtonProps{Title: ui.Val("Restart"), OnPress: func() { music.Seek(0); music.Play() }}),
	)
}

Player のメソッドは次のとおりで、どれもメインスレッドで呼びます。Play（現在の位置から再生します。最後まで再生し終えたあとは最初から）、Pause、Seek(seconds)、SetVolume（0 から 1 で、既定は 1）、SetRate（0.25 から 4 で、音程は変わりません）、SetLoop、Status(done)（Position、Duration、Playing、Ended を返します。再生の進み具合を追うには、1 秒に数回読みます）、そして Release です。Release は再生を止め、プレイヤーが確保しているものを解放します。不要になったプレイヤーは解放してください。

iOS では、音楽アプリやゲームと同じように、消音スイッチがオンでも音が鳴ります。また、ほかのアプリの音とは混ざりません。

再生中の表示とメディアキー: asuka/sdk/nowplaying

asuka/sdk/nowplaying は、アプリが再生しているものを、システムがメディアを表示する場所に表示し、そこにあるコントロールの操作をアプリに伝えます。表示される場所は、iOS ではロック画面、コントロールセンター、Dynamic Island、CarPlay、Android では通知シェード、ロック画面、Android Auto、Wear OS、Mac ではコントロールセンターとメニューバー、Windows ではメディアフライアウト、Linux では GNOME や KDE のメディアコントロール、そしてブラウザーのメディアコントロールです。キーボードやヘッドセットのメディアキーからも同じ操作が届きます。Show はコンポーネントの中で呼びます。アクセサの変化に追従し、コンポーネントのオーナーが破棄されると消えます。

func Episode(ep *Episode) ui.Node {
	state := signal.New(nowplaying.Paused)
	position := signal.New(0.0) // 秒。再生位置が飛んだときに設定する
	nowplaying.Show(nowplaying.Props{
		Title:          ui.Val(ep.Title),
		Artist:         ui.Val(ep.Show),
		Artwork:        ui.Val(ep.Cover), // アセット、ファイル、または http(s) の URL
		Duration:       ui.Val(ep.Seconds),
		State:          state,
		Position:       position,
		OnPlay:         func() { player.Play(); state.Set(nowplaying.Playing) },
		OnPause:        func() { player.Pause(); state.Set(nowplaying.Paused) },
		OnSeek:         func(at float64) { player.Seek(at); position.Set(at) },
		OnSkipForward:  func(s float64) { skip(s) },
		OnSkipBackward: func(s float64) { skip(-s) },
		SkipInterval:   30,
	})
	// ...
}

表示されるのは Title、Artist、Album、Artwork（512 ピクセル以上の正方形の画像なら、どこでもくっきり表示されます）、Duration（ライブストリームでは 0 にします。その場合はシークできません）、State（Playing、Paused、Stopped）、Position、Rate です。再生中は、システムが再生速度に合わせて位置を自動で進めます。パッケージが Position を送り直すのは、再生位置が飛んだとき（シークや途切れ）か、状態や速度が変わったときだけです。そのため、1 秒に数回読むプレイヤーの状態に Position を追従させても、コストはかかりません。

各操作は、そのハンドラーを設定すると有効になります。設定していない操作はグレー表示になるか、表示されません。OnPlay、OnPause、OnTogglePlayPause は互いの代わりになるので（ヘッドセットのボタンは一つで再生と一時停止を切り替え、ロック画面は再生か一時停止のどちらかを表示します）、どれか一つを設定すれば三つとも有効になります。OnSeek を有効にするには、Duration がわかっている必要があります。OnSkipForward と OnSkipBackward は SkipInterval（既定は 15 秒）ずつスキップします。iOS と Mac では「次へ」「前へ」の代わりに表示され、Android では OnNext や OnPrevious がないときにその位置に表示されます。

asuka/sdk/audio のプレイヤーなら、Player に渡すだけで残りを任せられます。状態、位置、長さはそのプレイヤーから取得され（状態は 1 秒に一度読まれ、プレイヤーに対して実行した操作はすぐに反映されます）、再生、一時停止、停止、シーク、そして（SkipInterval があれば）スキップは、ハンドラーを設定しない限りそのプレイヤーに対して実行されます。

music := audio.Load("music/spring.mp3")
signal.OnCleanup(music.Release)
nowplaying.Show(nowplaying.Props{
	Title:   ui.Val("Spring"),
	Artist:  ui.Val("Vivaldi"),
	Artwork: ui.Val("covers/spring.jpg"),
	Player:  music,
	OnNext:  playNext,
})

複数をマウントすることもできます。表示されるのは最後にマウントしたもので、それが消えると一つ前のものが表示されます。同じ更新の中で別のものに置き換わった場合（ある曲のコンポーネントが次の曲のコンポーネントに入れ替わるときなど）は、そのあいだもシステムのコントロールはアプリのものとして保たれます。

iOS では、アプリに audio バックグラウンドモードが付与されるので、画面をロックしても再生が続きます。また、オーディオセッションは playback カテゴリになります。iOS は、オーディオセッションが再生中のアプリを表示するためです。Android では、MediaSession とそのメディアスタイルの通知を使います（メディアセッションの通知には、通知の権限は要りません）。再生中は、Android 14 の要件どおり、メディア再生タイプのフォアグラウンドサービスがアプリを画面外でも動かし続けます。一時停止中は通知が残り、スワイプで消せます。どちらの設定も、このパッケージを使うアプリにだけ asuka build が追加します。examples/player は、このパッケージでアルバムを再生する例です。

ネットワークの状態: asuka/sdk/network

asuka/sdk/network は、デバイスのネットワークの状態を伝えます。オンラインかどうか、Wi-Fi とモバイル通信のどちらでつながっているか、通信に料金がかかるかどうかです。大きなファイルは Wi-Fi のときだけダウンロードする、オフラインであることを表示する、といった用途に使います。実装は、iOS と Mac では NWPathMonitor、Android では ConnectivityManager、Windows では Network List Manager、Linux では GNetworkMonitor と NetworkManager、ブラウザーでは navigator.onLine です。ブラウザーで通信の種類がわかるのは、それを取得できる環境（Android の Chrome）だけです。

network.Use() は、ネットワークの状態をシグナルとして返します。コンポーネントの中で使い、コンポーネントが生きているあいだ変化に追従します。

func Status() ui.Node {
	net := network.Use()
	return ui.Text(signal.Func(func() string {
		n := net.Get()
		if !n.Connected {
			return "Offline"
		}
		if n.Metered || n.Constrained {
			return n.Type.String() + ": large downloads wait for Wi-Fi"
		}
		return n.Type.String()
	}))
}

network.State は次のフィールドを持ちます。

• Connected：接続しているかどうか。
• Type：network.None、WiFi、Cellular、Ethernet、Other（VPN だけの接続、Bluetooth など）のいずれか。String は "none"、"wifi"、"cellular"、"ethernet"、"other" を返します。
• Metered：モバイルデータ通信やスマートフォンのインターネット共有のように、通信に料金がかかるか、量に制限があること。
• Constrained：ユーザーがアプリにデータ使用量を減らすよう求めていること（iOS の「省データモード」、Android の「データセーバー」、ブラウザーのデータセーバー）。Windows では、通信量がデータ制限に近づいているか、超えていることも表します。Linux では常に false です。

プラットフォームから最初の応答があるまで、Use の値は Connected で、Type は Other です。

network.Current() は現在のネットワークの状態を返します（メインスレッド以外から呼びます）。network.Watch(f) は、まず現在の状態で、その後は変わるたびに、メインスレッドで f を呼びます。返される stop を呼ぶまで続きます。

ライブラリへの保存: asuka/sdk/library

asuka/sdk/library は、ユーザーやほかのアプリから見える場所にファイルを保存します。動画はギャラリーに、曲は音楽ライブラリに、どんなファイルでも「ダウンロード」に保存できます。

library.Save(file, library.Options{Collection: library.Movies, Folder: "My App", Move: true},
	func(where string, err error) {
		if err != nil {
			status.Set("Couldn't save: " + err.Error())
			return
		}
		status.Set("Saved")
	})

library.Save(path, o, done) は、ファイルを o.Collection にメインスレッドの外でコピーし（大きな動画だと時間がかかるためです）、終わるとメインスレッドで、保存先を渡して done を呼びます。必要な権限は初回に求めます。done は nil でもかまいません。

library.Options は次のとおりです。

• Collection：library.Downloads（既定）、Movies、Music、Pictures のいずれか。
• Name：保存先でのファイル名（既定は元のファイル名）。同じ名前がすでにあれば番号が付きます。
• Folder：コレクションの中に作る、アプリのファイル用のフォルダー。空ならコレクションの直下に保存します。
• MIME：ファイルの種類（既定は拡張子から判断します）。
• Move：保存できたら元のファイルを削除します。アプリのキャッシュにダウンロードしたファイルを、コピーを二重に残さずに保存するときに使います。

各コレクションの保存先は次のとおりです。

Windows と Linux、そして Mac の ~/Downloads と ~/Music では、ファイルはユーザーのフォルダーの中の Folder に保存され、そのパスが返されます。Linux のフォルダーは XDG の規定に従います。ブラウザーでは、コレクションにかかわらずファイルをダウンロードします。保存先は、ブラウザーがダウンロードを置く場所です。

Android では、Android 10 以降は権限なしで MediaStore のコレクションを使い、content:// URI を返します。Android 10 より前は、ストレージの権限を求めてから共有フォルダーに書き込みます。

iOS では、「写真」への追加の許可を求め（追加のみで、アプリはライブラリを読めません）、アセットの識別子を返します。「写真」では Folder は使われません。それ以外のコレクションはアプリの Documents の中の Folder に保存され、ファイルのパスが返されます。Asuka は、Documents が「ファイル」App に表示されるように設定します。

バックグラウンド処理: asuka/sdk/background

asuka/sdk/background を使うと、アプリが画面に出ていないあいだも処理を続けられます。ユーザーが始めた、数分かかるダウンロード、アップロード、書き出しなどに使います。

background.Start はタスクを開始します。End を呼ぶまでアプリは動き続け、そのあいだ Options の内容を通知に表示します。ユーザーが通知のボタンをタップすると、onAction がメインスレッドでそのボタンの ID を受け取ります。task.Update は新しいオプションを表示するもので、処理が進むにつれて進み具合を更新するのに使います。タスクは、ユーザーが処理を求めたときに、アプリが画面に出ているうちに開始してください。

var cancelled atomic.Bool
task := background.Start(background.Options{
	Title:    "Exporting",
	Progress: -1,
	Actions:  []background.Action{{ID: "cancel", Title: "Cancel"}},
}, func(action string) {
	if action == "cancel" {
		cancelled.Store(true)
	}
})
go func() {
	for i := 1; i <= 10 && !cancelled.Load(); i++ {
		time.Sleep(time.Second) // 実際の処理
		p := float64(i) / 10
		ui.Post(func() {
			task.Update(background.Options{Title: ui.Val("Exporting"), Text: fmt.Sprintf("%.0f%%", p*100), Progress: p,
				Actions: []background.Action{{ID: "cancel", Title: "Cancel"}}})
		})
	}
	ui.Post(func() {
		task.End()
		if cancelled.Load() {
			status.Set("Cancelled")
		}
	})
}()

background.Options は次のとおりです。

• Title と Text。
• Progress：0 から 1。負の値は、処理中だが進み具合はわからないことを表します。
• Actions：通知のボタン。それぞれ ID と Title を持ちます。

Start、Update、End はメインスレッドで呼び、処理そのものはゴルーチンで行います。Update のたびにオプションはすべて置き換わるので、Actions も毎回指定してください。examples/downloader は、タスクの中でダウンロードし、一時停止、再開、キャンセルができる例です。

Android は、バックグラウンドに回ったアプリを数分以内に停止します。タスクがあるあいだは、（データ同期タイプの）フォアグラウンドサービスでアプリを動かし続け、CPU もスリープさせません。タスクごとに常駐する通知が表示され、進み具合と最大三つのボタンが並びます。Android 13 以降では、ユーザーがまだ通知を許可していなければ、タスクの開始時に許可を求めます。許可してもしなくても処理は続きます。バックグラウンドにいるアプリはタスクを開始できません。Android 15 では、データ同期サービスは 1 日 6 時間までに制限されます。Google Play は、アプリのデータ同期フォアグラウンドサービスを何に使うのかを Play Console で尋ねるので、アップロードの前に申告してください。

iOS では、タスクがあるあいだ、バックグラウンドに回ったアプリに 30 秒ほどの猶予が与えられます。通知は表示されないので、Update は何もせず、onAction も呼ばれません。時間切れになると iOS がタスクを終わらせ、処理が止まることがあります。

デスクトップのアプリは、画面に出ていなくても動き続けます。タスクがあるあいだは、システムがアプリを遅くしたり停止したりしないようにします（Mac の App Nap、Windows と Linux のスリープ）。通知は表示されないので、Update は何もせず、onAction も呼ばれません。ブラウザーは、タスクの有無にかかわらず、開いているあいだはページを動かします。

ほかのアプリからの共有: ui.OnShare

ui.OnShare(f) は、ほかのアプリが共有シートからこのアプリに共有したものを渡して f を呼びます。YouTube やブラウザーからのリンク、メモからのテキスト、ギャラリーからの写真、「ファイル」からの PDF などです。これは iOS と Android の機能です。デスクトップとブラウザーでは、アプリがほかのアプリの共有メニューに表示されず、f も呼ばれません。アプリが何の共有先として表示されるかは、asuka.json の shareTarget で指定します。

{ "shareTarget": true }

こう書くと、テキストとリンクを受け取ります。オブジェクトを指定すると、MIME タイプごとにファイルも受け取れます。一度に受け取れるのは max 個までです（既定は 1）。

{ "shareTarget": { "types": ["text", "image/*", "video/*"], "max": 10 } }

タイプには "text"（テキストと Web のリンク）か、MIME タイプを指定します。MIME タイプは "image/*"、"video/*"、"audio/*"、"application/pdf" などで、"*/*" はあらゆるファイルを表します。

func App() ui.Node {
	link := signal.New("")
	photos := signal.New([]string(nil))
	ui.OnShare(func(items []ui.SharedItem) {
		for _, it := range items {
			switch it.Kind {
			case ui.SharedLink:
				link.Set(it.Text)
			case ui.SharedImage:
				photos.Set(append(photos.Peek(), it.Path))
			}
		}
	})
	return ui.Text(link)
}

各 ui.SharedItem には Kind があり、SharedText、SharedLink、SharedImage、SharedVideo、SharedAudio、SharedFile のいずれかです。テキストやリンクは Text に入ります。ファイルは Path にあり、これはアプリのキャッシュにある、アプリ専用のコピーです。アプリで保管する場所に移すか、使い終わったら削除してください。ファイルには、共有元のアプリでの名前 Name（IMG_0042.HEIC など）、MIME タイプ、Size（不明なら -1）も付いてきます。項目は、共有元のアプリが渡した順に届きます。ブラウザーから共有されたページは、タイトル（テキスト）とリンクの二つの項目として届きます。

ハンドラーが設定される前に届いたもの、つまりアプリを起動した共有は、最初に設定されたハンドラーに渡されます。ハンドラーはコンポーネントのオーナーとともに止まります。アプリを開かずに、共有されたものに対してアプリの画面を表示するには、後述の共有シートを参照してください。アプリの中で画面を開くには、ナビゲーションを参照してください。

Android では、タイプごとのインテントフィルターによって、共有されたものとともにアプリ自体が開きます（ACTION_SEND。max が 1 より大きければ ACTION_SEND_MULTIPLE も）。アプリは、ファイルへのアクセス権が有効なうちに、OnShare に渡す前にファイルをキャッシュにコピーします。

iOS では、アプリに共有拡張機能（Share Extension）が入り、Android と同じように、共有されたものとともにアプリを開きます。拡張機能は独自の画面を表示しません。拡張機能のアクティベーションルールはタイプから作られます。テキスト、リンク、画像、動画、任意のファイルには Apple が用意したキーを使い、これらでは max が効きます。それ以外（オーディオや PDF）には添付ファイルのタイプに対する述語（predicate）を使い、こちらでは max は効きません。拡張機能は渡されたものを何でも受け取るので、Kind と MIME を確認してください。ファイルは App Group group.<app ID> を通じて拡張機能からアプリに渡ります。実機向けビルドのプロビジョニングプロファイルには、この App Group が含まれている必要があります（配布を参照）。

asuka dev では、アプリの shareTarget にかかわらず、開発用アプリがあらゆる共有を受け取ります。スマートフォンの実機では、共有されたファイルはスマートフォンの中にあり、Go のコードが動くコンピューターにはありません。そのため、shareTarget でファイルを受け取るアプリは、実機ではホットリロードモードではなく、アプリそのものをビルドして実行されます（iOS シミュレーターのファイルは Mac のものです）。

リンクの先が何か（ページ、画像、動画）を調べるのはアプリの役目で、net/http を使います。expo-sharing の「resolved」ペイロードに当たる処理を、Go で書くことになります。

アプリ独自の共有シート: app.ShareSheet

既定では、共有するとアプリが開きます。app.ShareSheet(screen) を使うと、代わりにアプリ独自の画面を、共有元のアプリの上に表示します。「Raindrop に保存」や「メモに追加」と同じ形で、ユーザーは保存したらすぐ元の場所に戻れます。app.Run の前に呼んでください。

func ShareSheet(s *ui.ShareSheet) ui.Node {
	note := signal.New("")
	return ui.Column(ui.Style{Grow: 1, Padding: ui.All(16), Gap: 12},
		ui.Text(signal.Static(s.Items[0].Text)),
		ui.TextField(ui.TextFieldProps{Value: note, Placeholder: ui.Val("Note"), Multiline: true}),
		ui.Row(ui.Style{Gap: 12},
			ui.Button(ui.ButtonProps{Title: ui.Val("Cancel"), OnPress: s.Cancel}),
			ui.Button(ui.ButtonProps{Title: ui.Val("Save"), Variant: ui.ButtonFilled, OnPress: func() {
				save(s.Items, note.Peek())
				s.Close()
			}}),
		),
	)
}

func main() {
	app.ShareSheet(ShareSheet)
	app.Run(App)
}

s.Items は共有されたもので、OnShare が受け取るものと同じです。シートは s.Close()（完了）、s.Cancel()、s.OpenApp() のいずれかで終わります。s.OpenApp() は、シートがない場合と同じように、項目を OnShare に渡してアプリを開きます。項目が届くまで（動画をコピーしているあいだなど）は、スピナーが表示されます。

iOS が共有拡張機能を実行するのと同じように、シートは独自のプロセスの中の、独立したルートです。iOS ではアプリの共有拡張機能で、iOS がシートとして表示します。拡張機能は、アプリと共有するフレームワークから、アプリの Go のコードとホストを実行します。Android では :share プロセスの Activity で、ほかのアプリの上に Material のボトムシートとして表示されます（下にドラッグする、外側をタップする、戻る操作をするとキャンセルされます）。プロセスはシートとともに終わります。シートが閉じるときに asuka/sdk/store の保留中の内容が書き込まれ、app.OnLifecycle には Background が届きます。ファイルの Path はシートが閉じるまでしか使えないので、アプリで残すものはコピーしてください。

アプリが保存するデータは、シートからも同じように使えます。asuka/sdk/store、store.Dir() にある SQLite のファイル（sqlite.Open("app.db")）、asuka/sdk/secure です。Android では、二つのプロセスがアプリのファイルを共有します。iOS では、シート付きで初めて起動したときに一度だけ、アプリのデータが App Group（group.<app ID>）に移され、キーチェーングループも拡張機能と共有されます。アプリが動いているあいだにシートが書き込んだ内容は、アプリには通知されません。アプリが前面に戻ったときに読み直してください（app.OnLifecycle、db.Changed()）。

CLI は、アプリの Go のコードが app.ShareSheet を呼んでいることを検出し、アプリを開く拡張機能の代わりにシートをビルドします。このとき iOS では、アプリの Go のコードとホストはアプリ内のフレームワーク Frameworks/AsukaApp.framework になり、Xcode が拡張機能とコードを共有するのと同じように、アプリと拡張機能の両方がそれを読み込みます。そのため、シートがあってもアプリのサイズは増えません。asuka dev でも、開発用アプリのシートが、Mac 上で動くアプリのシートを実行します。examples/bookmarks は Raindrop のようなシートの例で、ページのタイトル、説明、画像、メモ、コレクション、タグを扱います。

JavaScript: asuka/sdk/js

asuka/sdk/js は、プラットフォーム自身のエンジンを使い、画面に出さずに JavaScript を実行します。使うのは一度も表示されない Web ビュー（iOS と Mac では WKWebView、Android では WebView、Windows では WebView2、Linux では WebKitGTK）で、ブラウザーでは非表示でサンドボックス化されたフレームです。JavaScript でしか書かれていないコード、たとえば動画の URL に署名する関数を持つ、サイトのプレイヤーのようなコードを動かすためのものです。

js.Eval(ctx, script) は、スクリプトを専用の新しいページで、<script> の中身と同じく文の並びとして実行し、その値を JSON で返します。値は最後の文の値か、スクリプトが返す Promise の解決値です（undefined は null になります）。例外が投げられたり Promise が reject されたりすると、それが *js.Error 型のエラーになります。ページは実行後に破棄されるので、あるスクリプトが設定したものは次のスクリプトからは見えません。メインスレッド以外から呼びます。

go func() {
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()
	v, err := js.Eval(ctx, `const xs = [1, 2, 3].map(x => x * 2); xs`)
	fmt.Println(string(v), err) // [2,4,6] <nil>

	s, err := js.EvalString(ctx, `new Promise(done => setTimeout(() => done("later"), 100))`)
	fmt.Println(s, err) // later <nil>
}()

js.EvalString は、値が文字列になるスクリプト用の Eval です。スクリプトは ctx の期限まで、期限がなければ js.DefaultTimeout（1 分）のあいだ実行できます。時間切れになると "timeout" で失敗します。Android では、投げられたエラーのメッセージにスタックが含まれます。

ユーザーに見えるページの中でスクリプトを実行するには、ui.WebView を使います（Web ページ）。

プッシュ通知: asuka/sdk/push

push.Register() は、（初回は）ユーザーに通知の許可を求め、デバイスを Apple（APNs）か Google（Firebase Cloud Messaging）のサービスに登録して、Token、Service（"apns"、"fcm"）、通知が許可されているか（Allowed）を返します。トークンを自分のサーバーに送り、サーバーからそのトークン宛てに通知を送ります。トークンは変わることがあるので、起動のたびに登録してください。メインスレッド以外から呼びます。Mac も iOS と同じように APNs に登録します（プロビジョニングプロファイルが必要です。Mac の場合を参照）。Web では Web Push を使います（Service は "webpush" で、トークンはブラウザーのサブスクリプションです。Web を参照）。Windows と Linux にはアプリ向けのプッシュサービスがないため、Register は失敗します。

func App() ui.Node {
	push.OnOpen(func(m push.Message) { openThread(m.Data["thread"]) })
	go func() {
		if r, err := push.Register(); err == nil {
			api.SaveDeviceToken(r.Service, r.Token)
		}
	}()
	return home()
}

• push.OnReceive(f) は、アプリの実行中に届いた各メッセージを受け取ります。タイトルか本文があるメッセージは、フォアグラウンドでも通知として表示されます。データメッセージ（サイレントプッシュ）はここにだけ届きます。
• push.OnOpen(f) は、ユーザーがタップした各通知を受け取ります。アプリの起動時に f を設定しておけば、アプリを起動した通知も含まれます。メッセージのデータの "url" は、asuka/sdk/notify の通知と同じように ui.OnOpenURL にも渡されます。
• push.Message には ID、Title、Body、Data があります（Data は、iOS ではペイロードの aps 以外のキー、Android ではメッセージのデータです）。

iOS のリリースビルドでは、App ID に Push Notifications ケイパビリティが必要です。シミュレーターでもトークンを取得できます。Android では Firebase プロジェクトが必要です。プロジェクトに Android アプリを追加し、その google-services.json をダウンロードして、asuka.json で指定します。

{ "android": { "googleServices": "google-services.json" } }

Asuka は、Google の Gradle プラグインと同じようにこのファイルの設定をアプリに書き込みます。このファイルがないと、Register は対処方法を示すエラーで失敗します。

プッシュ通知のカテゴリ、スレッド、チャンネル

プッシュ通知でも、asuka/sdk/notify のカテゴリ（そのアクションと notify.OnAction）、スレッド、チャンネル、バッジ、Present を使えます。ペイロードで次のように指定します。

• iOS：APNs の仕様どおり、aps の category、thread-id、badge。
• Android：通知メッセージでは android.notification.channel_id と image、データメッセージでは "title"、"body"、"subtitle"、"category"、"thread"、"summary"、"channel"、"image"、"badge"、"url"。"title" か "body" を持つデータメッセージは通知として表示されます（Asuka がアクション付きで通知を組み立てます）。どちらも持たないデータメッセージはサイレントです（OnReceive にだけ届きます）。アプリがバックグラウンドにあるときに届いた通知メッセージは Firebase が表示するので、アクションもスレッドも付きません。それらが必要なら、データメッセージを送ってください。

push.Message には、これらに対応する Subtitle、Category、Thread、Channel、Image、Badge、Summary もあります。

表示前のプッシュ通知の書き換え

push.Rewrite(f) を使うと、各プッシュ通知が表示される前に、アプリの Go のコードで内容を書き換えられます。エンドツーエンドで暗号化されたペイロードを復号する、タイトルと本文を設定する、画像を添付する、送信者の写真付きの会話のメッセージにする、スレッドとカテゴリを設定する、といったことができます。main の中で、app.Run の前に呼んでください。

func main() {
	push.Rewrite(func(m *push.Message) error {
		text, from, err := decrypt(m.Data["box"]) // asuka/sdk/secure に保存した鍵で復号する
		if err != nil {
			return err // プッシュ通知を届いたまま表示する
		}
		m.Body = text
		m.Category = "message"
		m.From(notify.Person{ID: from.ID, Name: from.Name, Image: from.Avatar},
			notify.Conversation{ID: m.Data["chat"]})
		return nil
	})
	app.Run(App)
}

f はメインスレッドではなく、専用のゴルーチンで実行されます。エラーを返すかパニックすると、プッシュ通知は届いたまま表示されます。m.Image はダウンロードされて添付されます。m.From は、notify.Notification の From と同じように、通知をメッセージにします。

iOS では、Notification Service Extension の中で書き換えます。asuka build は、push.Rewrite を呼ぶアプリにこの拡張機能を作ります。拡張機能は、aps に "mutable-content": 1（と、書き換えに失敗したときに表示される alert）を持つプッシュ通知が届くたびに、専用のプロセスでアプリの Go のコードを実行します。まず main が、次に f が実行されます。ルートコンポーネントは実行されないので、main は軽くしておいてください。iOS が与えるのは 30 秒ほどの時間と 24 MB のメモリで、時間切れになるとプッシュ通知は届いたまま表示されます。アプリが保存するデータは、拡張機能からも同じように使えます。データ（asuka/sdk/store、store.Dir 内のファイル）は両者が共有する App Group に、キーチェーンの項目（asuka/sdk/secure）はアプリのグループにあります。リリースビルドには、拡張機能の bundle ID（アプリの ID に .notification を付けたもの）のプロビジョニングプロファイルが必要で、App Groups ケイパビリティとアプリのグループを含んでいなければなりません。プロファイルは asuka.json の ios.notificationProfile で指定でき、指定しなければ、インストールされているもののうち最も合うものを使います。iOS では、書き換えによってプッシュ通知を非表示にすることはできません。

Android では、FCM のデータメッセージをアプリのプロセスの中で書き換えます。アプリが動いていなければ Go のコードが画面なしで起動し、10 秒ほどのうちに書き換えて、通知が表示されます。書き換えた結果、タイトルも本文もなくなったデータメッセージは表示されません。

asuka dev の開発用アプリには拡張機能がありません（アプリの Go のコードはコンピューター上で動いています）。そのため、push.Rewrite を呼ぶアプリは、asuka dev でもホットリロードモードではなく、アプリそのものをビルドして実行されます。ビルドしたアプリには拡張機能があります。シミュレーターが拡張機能を実行するのは APNs から届いたプッシュ通知だけで、xcrun simctl push では実行されません。

Apple でサインイン: asuka/sdk/appleauth

appleauth.Button は Apple 純正のボタンで、タイトル、ロゴ、色がユーザーの言語に合わせて表示されます。appleauth.SignIn はシステムのシートを表示します。App Store は、アカウントのサインインにほかの会社のサインインを提供するアプリに、Apple でサインインも提供するよう求めています。

appleauth.Button(appleauth.ButtonProps{
	Type:  appleauth.ContinueButton,
	Style: appleauth.Automatic, // ライトモードでは黒、ダークモードでは白
	OnPress: func() {
		go func() {
			c, err := appleauth.SignIn(appleauth.Options{Scopes: appleauth.FullName | appleauth.Email, Nonce: nonce})
			if err == nil {
				api.SignInWithApple(c.IdentityToken, c.AuthorizationCode)
			}
		}()
	},
})

Credential の User は、アカウントの変わらない ID です。IdentityToken（Apple が署名した JWT）と AuthorizationCode を自分のサーバーに送り、サーバーで Apple に照会して検証します。Email、GivenName、FamilyName が届くのは、ユーザーが初めてそのアプリにサインインしたときだけなので、そのときに保存してください。ErrCanceled は、ユーザーがシートを閉じたことを表します。appleauth.CredentialState(user) は、ユーザーがそのアプリでまだ Apple でサインインを使っているかどうかを返します（Revoked ならサインアウトさせてください）。Android にはこの機能がありません。Button は何も表示せず、Available は false で、SignIn は ErrNotAvailable で失敗します。Windows、Linux、Web でも同じです。これらのプラットフォームでは、Web 経由で Apple でサインインを使ってください（asuka/sdk/webauth）。Mac では、プロビジョニングプロファイルがあれば iOS と同じように使えます（Mac の場合を参照）。

Face ID と指紋認証: asuka/sdk/biometric

biometric.Authenticate(options) はシステムのプロンプト（Face ID、Touch ID、Android の BiometricPrompt、Mac の Touch ID、Windows の Windows Hello、ブラウザーではパスキーの WebAuthn プロンプト）を表示し、デバイスの持ち主であれば nil を返します。そうでなければ ErrCanceled、ErrNotAvailable（生体認証もパスコードもないか、ロックアウトされている）、ErrFailed のいずれかを返します。メインスレッド以外から呼びます。

go func() {
	err := biometric.Authenticate(biometric.Options{Reason: "Unlock your notes"})
	ui.Post(func() { unlocked.Set(err == nil) })
}()

• Reason は認証する理由です（iOS ではサブタイトル、Android ではタイトルになります）。Cancel はキャンセルボタンのタイトルです。
• NoPasscode を指定しない限り、ユーザーは代わりにデバイスのパスコード、PIN、パターンを使えます。指定すると生体認証だけになります（Android では、強力な生体認証である Class 3 に限ります）。
• biometric.Check() は、デバイスが備えているものを返します。Kind（Face、Fingerprint、Iris、Optic）、登録済みかどうか（Enrolled）、Passcode があるかどうかです。

Linux には持ち主を確認するシステムのプロンプトがありません。Check は何もないと返し、Authenticate は ErrNotAvailable で失敗します。

録音: asuka/sdk/audio/record

record.Start(options, done) は、record.Stop を呼ぶまで（または MaxDuration に達するまで）マイクから録音し、終わるとファイルを渡して done を呼びます。ファイルは MPEG-4 コンテナーの AAC（.m4a）でアプリのキャッシュに保存され、asuka/sdk/audio で再生できます。録音には、iOS と Mac では AVAudioRecorder、Windows では Media Foundation、Linux では GStreamer、ブラウザーでは MediaRecorder を使います（AAC で録音できないブラウザーでは、WebM コンテナーの Opus になります）。初回はマイクの使用許可を求め、拒否されると done は "not allowed" を受け取ります。

record.Start(record.Options{Quality: record.Voice, MaxDuration: time.Minute}, func(path string, err error) {
	if err == nil {
		memo.Set(path)
	}
})
// あとで
record.Stop()

Voice は 64 kbit/s のモノラル、Music は 128 kbit/s のステレオです。Pause と Resume で、同じファイルへの録音を一時停止・再開できます。record.Level() は 0 から 1 の音量レベルで、ゴルーチンから 1 秒に数回呼んでレベルメーターに使います。record.CurrentStatus(done) はメインスレッドから呼び、レベル、いま音を記録しているかどうか、どれだけ記録したかを返します。タイマーに表示すべきなのはこの値です。システムが録音を一時停止することがあり（通話など）、iOS ではシステムが許可すれば、そのあと録音が再開されるためです。iOS では録音中、オーディオセッションが再生と録音の両方を行うモードになり（ほかのアプリの音は止まります）、録音が終わると元に戻ります。

Options.Stream を指定すると、ADTS ストリーム（.aac）で録音します。ADTS はフレームごとに完結しているので、アプリやスマートフォンが突然落ちても、それまでに録音した分は残ります。一方、MPEG-4 のファイルは閉じるまで読めません。クラッシュしたあとでもファイルを見つけられるよう Path を指定しておき、保存用には record.Finalize(stream, dst) で .m4a にしてください。こうして作ったファイルは正しくシークできます。停止したあとでも、クラッシュしたあとでも同じように使えます。

Options.Background を指定すると、アプリが画面に出ていないときや画面がロックされているときも録音を続けます。iOS では asuka.json に "ios": {"backgroundModes": ["audio"]} が必要です。Android では、マイクタイプのフォアグラウンドサービスを動かし、常駐する通知（BackgroundTitle）と停止ボタンを表示します。Google Play はこのサービスを何に使うのかを尋ねるので、アップロードの前に申告してください。デスクトップのアプリはもともと画面外でも録音できるので、Background を指定しても何も変わりません。

音声の文字起こし: asuka/sdk/transcribe

transcribe.File(path, options) は、録音をデバイス上でテキストに変換します。音声がデバイスの外に出ることはありません。デバイスで変換できない場合は、サーバーを使う代わりに ErrNotAvailable を返します。メインスレッド以外から呼びます。

go func() {
	r, err := transcribe.File(path, transcribe.Options{Language: "en-US"})
	ui.Post(func() {
		if err == nil {
			text.Set(r.Text)
		}
	})
}()

Result には Text と Language があり、iOS と Android 14 では Segments もあります。Segments は単語の並びで、それぞれ秒単位の Start と Duration を持ちます。発話のない録音では、Text は空になります。transcribe.Check(language) は、ユーザーに何も求めずに、デバイスで何ができるかを返します。iOS では Speech フレームワークを使います（モデルは iOS に含まれていますが、シミュレーターのランタイムによっては含まれていません）。初回は音声認識の許可を求めます。Android のオンデバイス認識には Android 13 が必要で、その言語のモデルも必要です。モデルがなければ取得するので、そのあいだは ErrDownloading が返ります（あとでもう一度試してください）。Mac でも Speech フレームワークを、デバイス上でのみ使います。Windows、Linux、Web には、アプリが使えるオンデバイスの音声認識がないため、File は ErrNotAvailable で失敗します。

画面: asuka/sdk/screen

screen.Lock(screen.Landscape) // 動画プレイヤー
screen.SetBars(screen.Bars{Style: screen.Light, HideStatus: true})
screen.PreventCapture(true) // チケットのコード
stop := screen.OnScreenshot(func() { note.Set("That screenshot shows your balance") })

• screen.Lock(o) は、アプリを o の向きに回転させ、その向きに固定します。指定できるのは Portrait、PortraitUp、Landscape、LandscapeLeft、LandscapeRight で、Any で固定を解除します。使えるのは asuka.json で許可した向きだけです。Split View やステージマネージャを使っている iPad と、Android 16 の大画面デバイスは、この指定を無視します。
• screen.SetBars(bars) はステータスバーの Style を設定します（Auto はダークモードに従い、Light は暗い画像の上に置く明るいアイコン、Dark は暗いアイコンです）。また、ステータスバー（HideStatus）や Android のナビゲーションバー（HideNavigation）を隠せます。隠したバーは、画面の端からスワイプすると一時的に表示されます。セーフエリアもそれに合わせて変わります。
• screen.PreventCapture(on) は、アプリがスクリーンショットや画面収録に写らないようにします。Android ではウィンドウをセキュアにするので、キャプチャは黒くなり、最近使ったアプリの一覧でも空白で表示されます。iOS ではスクリーンショットを防げませんが、画面収録、ミラーリング、AirPlay のあいだはアプリを覆い隠します。
• screen.OnScreenshot(f) は、ユーザーがスクリーンショットを撮ると f を呼びます（iOS、Android 14 以降）。返される stop を呼ぶまで続きます。

デスクトップのウィンドウには向きもシステムバーもないので、Lock と SetBars は何もしません。PreventCapture は、Mac と Windows では（Linux では効きません）アプリのウィンドウがスクリーンショットや画面収録に写らないようにします。OnScreenshot は、スクリーンショットが保存された時点でそれを検知します（Mac では Spotlight で、Windows と Linux では「スクリーンショット」フォルダーで検知します）。ブラウザーで向きを固定できるのは、全画面表示のときかインストールされたアプリの中だけです。バーは全画面表示にすることで隠し、PreventCapture と OnScreenshot はありません。

これらの設定は画面ごとではなく、アプリ全体のものです。ある画面で設定したら、その画面が閉じるときに元に戻してください（signal.OnCleanup）。

起動画面: asuka/sdk/splash

asuka.json の splash は起動画面です。ライトモードとダークモードそれぞれの背景色の中央に、画像（正方形の PNG、ロゴ）を size ポイントの幅（既定は 120、最大 160）で表示します。

{ "splash": { "image": "logo.png", "size": 96, "background": "#4A63B5", "darkBackground": "#1B2440" } }

起動画面は、アイコンをタップしてからアプリの最初のフレームが出るまで表示されます。iOS では起動画面（Launch Screen）を表示し、続いて最初のフレームの準備ができるまで、その複製をアプリの上に重ねます。Android 12 以降ではスプラッシュ画面（アイコンの円の中央に画像を表示）を、それより前のバージョンではウィンドウの背景を使います。デスクトップと Web には起動画面がないので、Hold と Hide は何もしません。アプリの読み込み中も起動画面を表示し続けるには、起動時に（ルートコンポーネントの中で）splash.Hold() を呼び、準備ができたら splash.Hide() を呼びます。

func App() ui.Node {
	splash.Hold()
	go func() {
		load()
		ui.Post(splash.Hide)
	}()
	return home()
}

地図: asuka/sdk/maps

maps.View は地図です。iOS と Mac では Apple マップ、Android では Google マップを表示します。Windows、ブラウザー、Linux では OpenStreetMap のタイルを使い、Windows とブラウザーではホストが、Linux では libshumate が描画します。

region := signal.New(maps.Region{Center: maps.Coordinate{Lat: 37.77, Lng: -122.42}, LatDelta: 0.05, LngDelta: 0.05})
maps.View(maps.Props{
	Region:         region,
	Markers:        ui.Val([]maps.Marker{{ID: "hq", At: maps.Coordinate{Lat: 37.79, Lng: -122.39}, Title: "HQ"}}),
	OnRegionChange: func(r maps.Region) { region.Set(r) },
	OnMarkerPress:  func(id string) { show(id) },
	Style:          ui.Style{Grow: 1},
})

• Region は表示する範囲で、中心と、その範囲が覆う緯度・経度の幅（度）で表します。設定すると、地図がその範囲に移動します。OnRegionChange は、ユーザーが地図を動かし終えたときに、その範囲を受け取ります。
• Markers はピンで、Title、Subtitle、Color を持ちます。タップされたピンの ID は OnMarkerPress が、ユーザーが地図をタップした位置は OnPress が受け取ります。
• Type は Standard、Satellite、Hybrid、Muted（iOS）のいずれかです。ShowsUser は、位置情報の権限があればユーザーの現在地を表示します（asuka/sdk/location をインポートし、先に権限を求めてください）。NoInteraction を指定すると、操作できない静止したプレビューになります。
• 地図には固有のサイズがありません。サイズを指定するか、Grow を設定してください。

Android では、Maps SDK for Android を有効にした Google Maps Platform の API キーを、asuka.json で {"android": {"mapsKey": "..."}} のように指定する必要があります。キーがないと地図にその旨が表示され、OnError が理由を受け取ります。Windows、Linux、Web では、Satellite と Hybrid も通常の地図になります（無料の航空写真がないためです）。ShowsUser は、Windows と Linux では何も表示せず、ブラウザーではページが位置情報の権限を得ると、ユーザーの現在地を表示します。Muted は、iOS と Web では落ち着いた色合いの地図になります。Linux では libshumate（libshumate-1.0-1）が必要です。タイルは、tile.openstreetmap.org の利用規約に従ってそこから取得し、地図上にクレジットを表示します。Web アプリでは、独自のサーバーからタイルを取得することもできます（Web）。

バックグラウンド更新: asuka/sdk/periodic

asuka/sdk/periodic は、アプリが画面に出ていないあいだに、ときどきアプリの Go のコードを実行します。同期や新着の取得などに使います。Handle はルートコンポーネントの中でタスクのコードを設定し、Schedule はシステムにその実行を依頼します。

func App() ui.Node {
	periodic.Handle("sync", func(ctx context.Context) error {
		return syncInbox(ctx)
	})
	periodic.Schedule("sync", periodic.Options{Every: time.Hour, Network: true})
	return home()
}

いつ実行するかは、Every（最短 15 分）、バッテリー、ネットワーク、ユーザーのアプリの使い方をもとにシステムが決めます。指定よりずっと長く待つこともあり、ユーザーがオフにすることもできます（iOS の「Appのバックグラウンド更新」）。Network を指定するとオンラインのときだけ、Charging を指定すると充電中だけ実行します。ctx はシステムの期限より前に終了します。期限は iOS では約 25 秒（Charging を指定したときに使う processing タスクでは数分）、Android（WorkManager）では 9 分です。エラーを返すと、Android はタスクを再試行します。

アプリが閉じているときにシステムがタスクを実行すると、アプリの Go のコードが画面なしで起動します。main、（Handle を呼ぶ）ルートコンポーネントの順に実行され、そのあとタスクが実行されます。そのときユーザーがアプリを開くと、アプリの画面が表示されます。Cancel(name) はタスクを止めます。

デスクトップは、タスクのためにアプリを起動しません。macOS（NSBackgroundActivityScheduler）、Windows、Linux では、アプリの実行中にタイマーでタスクを実行し、電源を必要とするタスクはバッテリー駆動中は待機します。ブラウザーは閉じているページのタスクを実行しないので、Schedule は失敗します。

ストア: asuka/sdk/review, asuka/sdk/tracking, asuka/sdk/integrity, asuka/sdk/agerange

review.Request(done) は、ストアに評価のプロンプト（App Store の評価プロンプト、Google Play のアプリ内レビュー）を表示するよう依頼します。表示するかどうかはストアが独自の回数制限に基づいて決め、表示したかどうかは知らされません。何かがうまくいったあとに依頼し、ボタンからは呼ばないでください。「評価する」ボタンには ui.OpenURL(review.AppStoreURL(id)) か review.PlayStoreURL(id) を使います。

tracking.Request() は iOS の App Tracking Transparency のプロンプトを表示し、Allowed、Denied、Restricted、NotAsked のいずれかを返します。アプリは、広告識別子を読んだり広告ネットワークとデータを共有したりする前に、このプロンプトを表示しなければなりません。tracking.Current() は、尋ねずに現在の状態を読みます。Android にはこのようなプロンプトがないので、常に Allowed です。メインスレッド以外から呼びます。

asuka/sdk/integrity は、リクエストが実機上の本物のアプリから来たことを、自分のサーバーに証明します。iOS では App Attest を使います。GenerateKey で鍵を作り（ID を保存しておきます）、AttestKey(id, challenge) でサーバーのチャレンジに対して一度だけ Apple に鍵を証明してもらい、以後は Assert(id, data) で各リクエストに署名します。Android では Play Integrity を使います。起動時に Prepare(cloudProjectNumber) を呼び、リクエストごとに Token(requestHash) を呼びます。返された値は、サーバーが Apple や Google に照会して検証します。iOS のシミュレーターでは、Supported は false です。

agerange.Request(13, 18) は、生年月日を聞かずにユーザーの年齢層を尋ねます。子どもの利用を把握するようアプリに求める法律への対応に使うもので、Apple の Declared Age Range（iOS 26）と Play の Age Signals を使います。プラットフォームが、ユーザーやその保護者に共有するかどうかを尋ねることがあります。Result は、Lower と Upper の年齢（0 は制限なし）を持つ Shared、Declined、VerificationRequired（Play）のいずれかで、Source はその年齢をどうやって知ったのかを示します。プラットフォームが答えられない場合は ErrNotAvailable になります。

スマートフォン以外では次のとおりです。Mac には App Store の評価プロンプト、トラッキングのプロンプト、App Attest があります（プロビジョニングプロファイルが必要です。Mac の場合を参照）が、Declared Age Range はありません。Windows、Linux、Web には、ストアのプロンプト（review.Request は何も表示せず、ブラウザーでは done がエラーを受け取ります）、アテステーション（integrity.Supported は false）、年齢層（ErrNotAvailable）のいずれもありません。これらのプラットフォームではトラッキングにプロンプトは不要です。Windows では「設定」で広告 ID がオンになっていれば Allowed、Linux では Allowed、ブラウザーでは Global Privacy Control か Do Not Track を送っていれば Denied を返します。

モーションとセンサー: asuka/sdk/sensors

stop := sensors.WatchMotion(50*time.Millisecond, func(m sensors.MotionReading) {
	level.Set(m.Attitude.Roll) // 水準器
})

• WatchAccelerometer、WatchGyroscope、WatchMagnetometer は、ほぼ指定した間隔ごとに Vector（x、y、z）を渡します。単位は、加速度が g、回転が毎秒のラジアン、磁場がマイクロテスラ（キャリブレーション済み）です。
• WatchMotion は、複数のセンサーを統合したデバイスの動きです。Gravity とユーザーによる Acceleration（g 単位）、Rotation、そして Attitude を渡します。Attitude は、デバイスの軸を東・北・上（East-North-Up）の座標に変換する Matrix、Heading（磁北からの角度。磁気センサーがなければ -1）、Pitch と Roll を持ちます。
• WatchPressure は気圧計（ヘクトパスカルと、高度の変化）、WatchLight は周囲の明るさ（ルクス、Android）、WatchSteps は監視を始めてからの歩数です。StepsBetween(from, to) は iOS の歩数の履歴（1 週間分）を読みます。Android には履歴がありません。
• Available(sensor) は、デバイスにそのセンサーがあるかどうかを返します。シミュレーターやエミュレーターには、センサーがほとんどありません。Mac と PC にはセンサーがありません。Linux では、2-in-1 やタブレットで光センサーと、加速度センサーによる向きが使えます（iio-sensor-proxy）。ブラウザーでは Generic Sensor API かデバイスモーションイベントが使えますが、気圧計と歩数計はありません。

値はどちらのプラットフォームでも同じです。デバイスの軸は Android と W3C の定義どおり（x は画面の右方向、y は画面の上方向、z は画面から手前の方向）で、加速度は加速度センサーが測るとおりの値です（画面を上にして置いたデバイスでは z = +1 g になります。iOS の値はこれに合うよう向きを変えています）。姿勢もどちらでも同じ方法で計算します。読み取りは 1 秒に最大 200 回で、プラットフォームが渡すまとまりごとに、メインスレッドに届きます。

画像と動画フレームの編集: asuka/sdk/imageedit

imageedit.Edit(source, actions, options) は画像（HEIC、JPEG、PNG、WebP など、カメラや写真ピッカーが返す形式）を読み込み、向きの情報に従って正立させ、アクションを順に実行して、JPEG か PNG をアプリのキャッシュに書き出します。メインスレッド以外から呼びます。

go func() {
	r, err := imageedit.Edit(photo, []imageedit.Action{
		imageedit.Resize(1080, 0), // 幅 1080。0 で縦横比を保つ
		imageedit.Crop(0, 0, 1080, 1080),
	}, imageedit.Options{Quality: 0.8})
	if err == nil {
		upload(r.Path, r.Width, r.Height)
	}
}()

アクションには Resize、Crop、Rotate（時計回り、任意の角度）、FlipHorizontal、FlipVertical、Fill、Pixelate があります。Fill(x, y, w, h, r, g, b) は矩形を単色で塗りつぶし、元の内容はファイルから消えます。Pixelate(x, y, w, h, block) は矩形をモザイクにします。各マスはその下にあるピクセルの平均色で、マスは画像全体を基準に並ぶので、隣り合う矩形も一つにつながって見えます。マスが小さいと、下にある文字を読み取れることがあります。確実に隠したいものには Fill を使ってください。書き出したファイルには、元の画像のメタデータ（位置情報やカメラの情報など）は一切含まれません。最初のアクションが Resize なら、画像をそのサイズに近い大きさでデコードするので、大きな写真ではメモリを節約できます。imageedit.Size は、画像をデコードせずにサイズを読みます。imageedit.VideoFrame(source, at, actions, options) は、動画の指定した時刻のフレームを正立させて取り出し（サムネイルやポスター用）、同じように編集します。リモートの動画は、そのフレームに必要なところまでしか読み込みません。ソースには ui.Image と同じもの、つまりパス、file:// か http(s) の URL、アセットを指定できます。

デコードには、各プラットフォームのコーデックを使います。iOS と Mac では ImageIO、Android では Android 標準のコーデック、Windows では WIC、Linux では GdkPixbuf のローダー（HEIC と WebP は、そのコーデックやローダーがインストールされている場合のみ）、ブラウザーでは canvas（JPEG か PNG。リモートの画像には CORS が必要です）です。

音声読み上げ: asuka/sdk/speech

speech.Speak(text, options, done) は、プラットフォームの音声でテキストを読み上げるよう、キューに追加します。読み終わると done が nil を受け取り、止められた場合は ErrStopped を受け取ります。

speech.Speak("Turn left in 200 meters", speech.Options{Rate: 1.1}, nil)

Options では、Language（BCP 47 タグ）、Voice（speech.Voices() が返す ID。各音声には名前、言語、品質があります）、Pitch、Rate、Volume を指定します。Stop はキューを破棄し、Pause と Resume は単語の区切りで一時停止・再開します（Android には一時停止の機能がありませんが、Asuka がその単語から読み上げを再開するので、Android でも使えます）。iOS では、読み上げ中はほかのアプリの音量が下がり、消音スイッチがオンでも読み上げます。Android でも同じように、ほかのアプリの音量を下げます。音声は、iOS と Mac では AVSpeechSynthesizer、Windows では SAPI、Linux では Speech Dispatcher、ブラウザーでは speechSynthesis のものを使います。

連絡先: asuka/sdk/contacts

• contacts.Pick(done) は、システムの連絡先ピッカーを表示します。ユーザーが一件を選び、アプリにはその連絡先だけが見えます。権限は求めません（Android では、権限がなければ名前だけを取得できます）。
• contacts.Add(contact, done) は、内容を入力済みにしたシステムの新規連絡先画面を表示し、ユーザーがそこで保存します。権限は求めません。
• contacts.Request() はアクセスの許可を求め、contacts.List(query) はアドレス帳を読みます（名前で検索し、上限の件数まで）。名前、組織、ラベル付きの電話番号とメールアドレス、誕生日を読めます。iOS 18 の限定アクセスでは、ユーザーが選んだ連絡先だけが返ります。

Mac では Contacts フレームワークを使います。Pick はシステムのピッカーで、ウィンドウの上端からポップオーバーで表示されます。Add はウィンドウの上のアラートで確認してから保存します（macOS には新規連絡先画面がないためです）。Linux では、Linux の場合で説明しているとおり、Evolution Data Server のアドレス帳を読み書きします。Windows はパッケージ化されたアプリにしか連絡先を渡さないので、Request は拒否を返し、Pick は失敗し、Add は vCard をユーザーの連絡先アプリで開きます。ブラウザーでは、Contact Picker がある環境（Android の Chrome）なら一件を選べ、Add は vCard をダウンロードします。

カレンダー: asuka/sdk/calendar

• calendar.Add(event, done) は、内容を入力済みにしたシステムのイベントエディターを表示し、ユーザーがそこでイベントを保存します。権限は求めません（iOS 17 以降）。iOS は保存されたかどうかを返しますが、Android のカレンダーアプリは返しません。
• calendar.Request() はフルアクセスの許可を求めます。許可されると、calendar.Calendars() でカレンダーの一覧を、calendar.Events(from, to, ids...) で二つの時刻のあいだのイベントを取得できます。繰り返しイベントは、発生ごとに一件ずつ返ります。
• 終日イベントの Start と End は日付を表し、それぞれ初日の UTC の午前 0 時と、最終日の翌日の UTC の午前 0 時です。

Mac では EventKit を使います。Add はウィンドウの上のアラートで確認してから保存します（macOS にはアプリ用のイベントエディターがないためです）。Linux では Evolution Data Server のカレンダーを読み書きします。Windows はパッケージ化されたアプリにしかカレンダーを渡さないので、Request は拒否を返し、Add は iCalendar ファイルをユーザーのカレンダーアプリで開きます（保存されたかどうかはわからないので、saved は false です）。ブラウザーはカレンダーを読めず、Add は .ics ファイルをダウンロードします。

ホーム画面ウィジェット: asuka/sdk/widget

アプリのウィジェットは asuka.json の widgets で宣言し、アプリの Go のコードから widget.Set で内容を設定します。

{ "widgets": [{ "kind": "today", "name": "Today", "description": "What's next", "sizes": ["small", "medium", "rectangular"] }] }

widget.Set("today", widget.Entry{
	Title: "Next", Symbol: "calendar", Value: "3 tasks", Body: "Call Ana at 4",
	Progress: 0.4, ShowProgress: true, Until: meeting, URL: "myapp://today",
})

ウィジェットは、プラットフォームのテンプレートを使い、サイズに合わせたレイアウトで Entry を表示します。表示されるのは、Title（Symbol 付きで、Tint の色）、大きな Value、Body、Progress バー、Until までリアルタイムで進むカウントダウン、Caption です。アプリが別のエントリーを設定するまで、アプリが動いているかどうかにかかわらず表示され続けます。タップすると、その URL でアプリが開きます（ui.OnOpenURL）。それぞれ At を持つ複数のエントリーはタイムラインになり、各エントリーはその時刻から表示されます。Clear でウィジェットを空にします。

サイズは small、medium、large、そして iOS の extraLarge（iPad）と、ロック画面の circular、rectangular、inline です。iOS では、CLI がアプリに組み込む WidgetKit 拡張機能になり、アプリと App Group を共有します。リリースビルドには App Groups ケイパビリティと、拡張機能の ID（アプリの ID に .widgets を付けたもの）のプロビジョニングプロファイルが必要です。Android では、種類ごとに一つの App Widget になり、Material You の色を使い、ランチャーのセルに合わせたサイズになります。デスクトップと Web にはウィジェットがないので、widget.Set は何もしません。

ライブアクティビティ: asuka/sdk/liveactivity

ライブアクティビティは、いま起きていることを、変化に合わせてアプリの外に表示します。配達中の荷物、配車、試合のスコア、タイマーなどです。iOS ではライブアクティビティ（iOS 16.2）として、ロック画面と Dynamic Island に表示され、Dynamic Island のない iPhone ではバナーで表示されます。Android では常駐する通知になり、Android 16 ではこれが Live Update に昇格して、通知シェードとロック画面の最上部に表示され、ステータスバーにチップが出ます。

a, err := liveactivity.Start(liveactivity.Content{
	Title: "Order #1042", Subtitle: "Ana is picking it up", Value: "12 min",
	Symbol: "bag.fill", Until: eta, URL: "myapp://orders/1042",
}, liveactivity.Options{})

// あとで、メインスレッドで:
a.Update(liveactivity.Content{Title: "Order #1042", Subtitle: "2 stops away", Value: "4 min", Until: eta},
	liveactivity.Alert{Title: "Almost there", Body: "Ana is 2 stops away"})
a.End(liveactivity.Content{Title: "Order #1042", Subtitle: "Delivered"}, liveactivity.Dismiss{})

アクティビティは、プラットフォームのテンプレートで Content を表示します。空の項目は表示されません。表示されるのは、Title と Subtitle、Value（横に大きく表示され、Dynamic Island のコンパクト表示や Android 16 のステータスバーのチップにも使われます）、Tint の色の Symbol、Progress バー、そしてアプリが動いていなくても進む Until までのカウントダウンです。Since、Until、ShowProgress を指定すると、バーが自動で伸びていきます。タップすると、その URL でアプリが開きます（ui.OnOpenURL）。

Start はアプリが画面に出ているあいだに、メインスレッド以外から呼びます（どちらのプラットフォームでも、バックグラウンドのアプリはアクティビティを開始できません）。Update と End はメインスレッドで呼びます。Alert を付けると、更新とともに画面が点灯します。iOS では Dynamic Island が展開され、Apple Watch にも表示されます。Android では通知をもう一度鳴らします。End は、最後の内容を、システムが取り除くまで（最大 4 時間）か Dismiss.At まで表示したままにします。Dismiss.Now を指定すると、すぐに取り除きます。Running は、まだ実行中のアクティビティ（再起動したあとなど）を、それぞれの表示内容とともに列挙します。Enabled は、ユーザーがアクティビティを許可しているかどうかを返します（Android では最初の Start で通知の許可を求めます）。

Observe は、アクティビティに起きたことを伝えます。（ユーザー、システム、サーバー、End によって）Ended になったもの、サーバーによって Started になったもの、そしてプッシュトークンです。Options.Push を指定すると、アプリが動いていないあいだも、サーバーからアクティビティを更新・終了できます。その PushToken と ID をサーバーに送ってください。iOS では、サーバーは liveactivity タイプの APNs プッシュを送り、その content-state は Content を JSON にしたものです（Go からは MarshalJSON で作れます）。Android では、asuka.liveActivity（update、end）、asuka.id、asuka.content を持つ Firebase のデータメッセージを送ります。サーバーからアクティビティを開始するには、iOS では iOS 17.2 の PushToStartToken を使い（attributes の型は AsukaActivityAttributes で、新しいアクティビティの id を含めます）、Android では asuka.liveActivity を start にします。ペイロードの詳細はパッケージのドキュメントにあります。プッシュを使うには、アプリに asuka/sdk/push が必要です。iOS では Push Notifications ケイパビリティが、Android では Firebase が要ります。

iOS のビルドは、このパッケージを呼ぶアプリにウィジェット拡張機能を追加し、アクティビティのテンプレート（ウィジェットと同じく SwiftUI 製）と NSSupportsLiveActivities を加えます。リリースには、ウィジェットと同じく、拡張機能の ID のプロビジョニングプロファイルが必要です。ユーザーは「設定」でアプリのライブアクティビティをオフにでき、Android 16 では通知の設定で Live Update への昇格をオフにできます。デスクトップと Web にはこの機能がないので、Enabled は false で、Start は ErrNotAvailable で失敗します。

ショートカット: Siri、Spotlight、ランチャー

asuka.json の shortcuts は、システムがアプリのために表示するアクションです。それぞれ、その URL でアプリを開き、ui.OnOpenURL に渡します。

{ "shortcuts": [{ "id": "newNote", "title": "New Note", "url": "notes://new", "symbol": "square.and.pencil", "phrases": ["New note in ${app}"] }] }

iOS では App Shortcuts になります。Siri がそのフレーズ（それぞれアプリ名を表す ${app} を含みます）を聞き取り、ユーザーが何も設定しなくても、Spotlight、「ショートカット」App、アクションボタンで使えます（最大 10 個）。CLI はこれらを App Intents としてコンパイルし、Xcode と同じようにメタデータを抽出します。Android ではランチャーのショートカットになり、アプリのアイコンを長押しすると、アクセントカラーのシンボル付きで表示されます。デスクトップと Web には追加されません。

シミュレーター向けのビルドは、Xcode と同じように、キーチェーンにある（asuka.json で指定したチームの）Apple Development の証明書で署名されます。App Intents は、チームのあるアプリでしか動かないためです。証明書がなければビルドはアドホック署名になり、CLI はショートカットが動かないことを知らせます。

触覚フィードバック: ui.Haptic

ui.Haptic(kind) は触覚フィードバックを再生します（iOS では UIFeedbackGenerator、Android では performHapticFeedback）。種類は ui.HapticSelection、HapticLight、HapticMedium、HapticHeavy、HapticSuccess、HapticWarning、HapticError のいずれかです。Mac ではトラックパッドのフィードバックを再生します（感圧タッチトラックパッドで、HapticSelection では整列、それ以外ではレベル変更のフィードバック）。ブラウザーでは、可能な環境（Android の Chrome）で振動します。Windows と Linux には触覚フィードバックがないので、何もしません。

ui.Haptic(ui.HapticSuccess)

アニメーションに合わせたフィードバックについては、モーションとジェスチャーを参照してください。

クラッシュレポート: asuka/sdk/crash

asuka/sdk/crash をインポートしたアプリは、クラッシュのたびにレポートを保存し、次の起動時にそれを読んで、自分のサーバー、Sentry、Crashlytics など好きな送り先に送れます。Asuka 自身は何もアップロードしません。

func App() ui.Node {
	crash.OnReport(func(r crash.Report) {
		go func() {
			if err := send(r); err == nil { // 自前のアップロード処理（r は JSON）
				crash.Delete(r.ID)
			}
		}()
	})
	crash.Set("user", userID)
	// ...
}

// ほかの場所で、アプリの動作に合わせて:
crash.Breadcrumb("opened the cart")
crash.Record(err) // 処理済みのエラーもレポートする

OnReport(f) は、保存されている各レポートを渡してメインスレッドで f を呼び、その後も新しいレポート（起動の少しあとに iOS が届ける診断情報や、記録されたエラー）が届くたびに呼びます。各レポートにつき一度だけで、返される stop を呼ぶまで続きます。Reports() は、すべてのレポートを古い順に読みます（メインスレッド以外から呼びます）。レポートは Delete(id) を呼ぶまで残り、MaxReports（50）を超えると古いものから消えます。ID は何度読んでも同じなので、サーバーは二重に送られたレポートを見分けられます。

プラットフォームごとに報告される内容（Kind）は次のとおりです。

Go のクラッシュは、すべてのゴルーチンのスタックとともに、Go のランタイム自身が保存します（runtime/debug.SetCrashOutput。アプリの起動時、main より前に設定されます）。捕捉されなかった例外は、アプリが終了するときにホストのハンドラーが書き込みます（それより前に設定されたハンドラー、たとえばクラッシュ SDK のハンドラーも、そのあとで実行されます）。それ以外は、次回以降の起動時にシステムが渡してくれます。iOS と macOS では MetricKit の診断情報、Android ではアプリのプロセスがどのように終了したかの記録です（getHistoricalProcessExitReasons、Android 11 以降。ネイティブクラッシュの tombstone は Android 12 から）。ホストのハンドラーが報告したクラッシュをシステムが改めて報告したもの（捕捉されなかった例外による iOS の SIGABRT、Android の REASON_CRASH）は除外されます。

各レポートには Context があります。アプリのバージョンとビルド番号、デバイスの機種と OS、プロセスとその実行時間、フォアグラウンドにいたかどうか、最近の Breadcrumb（MaxBreadcrumbs、100 件）、Set で設定した値です。これらは変わるたびにアプリのデータディレクトリに書き込まれます。一件ごとに一行を追記するだけで（sync はしないので、書き込み一回分のコストで済みます）、ファイルが必要な大きさの 2 倍になったら書き直します。そのため、アプリが何によって終了しても、クラッシュの前にはディスクに書かれています。ライフサイクルの変化もブレッドクラムになります（「app: background」）。

レポートの Text は、プラットフォームが渡す内容そのもの（Go のクラッシュ出力、スタックトレース、tombstone、ANR のトレース）です。Threads は、それらのスタックをフレームに分解したもので、クラッシュしたスレッドが先頭に来ます。Go のフレームは関数、ファイル、行を持ちます。ネイティブのフレームは、バイナリ、バイナリの UUID（Mach-O）またはビルド ID（ELF）、アドレス、バイナリ内のオフセットを持ちます。サービスがビルドのシンボルを使ってシンボル化するには、これらの情報が必要です（配布を参照）。

Sentry や Crashlytics への送信。 Sentry には、各レポートからイベントを作って送ります（送り先はエンベロープのエンドポイント https://<host>/api/<project>/envelope/ で、DSN のキーを付けます）。exception.values[0] の type に Kind、value に Message、stacktrace.frames にクラッシュしたスレッドのフレームを入れます。フレームは外側から順に並べ（Sentry の順序で、Thread とは逆です）、それぞれ function、filename、lineno を、ネイティブのフレームなら instruction_addr と package を持たせます。また debug_meta.images には、フレームに出てくる各バイナリを {"type": "macho", "debug_id": BinaryID, "image_addr": Address-Offset}（Android では "elf"）として入れます。こうすると、sentry-cli でアップロードした dSYM やシンボルが適用されます。Context は contexts、tags、breadcrumbs に入れます。Crashlytics には、送信先となる公開のエンドポイントがありません。レポートを自分のサーバーに送るか、独自のネイティブモジュール（ネイティブコード）から Crashlytics の SDK に致命的でないエラーとして記録してください。どちらの場合も、App Store の審査ではクラッシュデータについて尋ねられます。送信するなら、そのことを申告してください（asuka.json の ios.collected に {"type": "CrashData", "purposes": ["AppFunctionality"]}）。

プラットフォームごとの違い。 iOS では、レポートを読むアプリ（crash.Reports か crash.OnReport を使うアプリ）にだけ MetricKit をリンクし、MetricKit は診断情報を共有拡張機能ではなくアプリに届けます。独自の共有シート（app.ShareSheet）を持つアプリは、シートのクラッシュもアプリのクラッシュと一緒に両者の App Group に保存し、どちらからも読めます。MetricKit は iOS 17 以降ではクラッシュのプロセス ID を持っているので、その実行のコンテキストと結び付けられます。それより前のバージョンでは、クラッシュの直前の実行と結び付けます。シミュレーターでは MetricKit は診断情報を届けません。Android では追加の設定は要りませんが、Android 11 より前にはネイティブクラッシュと ANR の記録がありません。macOS では、MetricKit は macOS 12 から使えます。アプリを終了させた、捕捉されない Objective-C の例外は、MetricKit のクラッシュとして報告されます（メインスレッドの例外は AppKit が捕捉してログに出力します）。Windows では、プロセスが処理しなかった例外はすべて Go のランタイムが（最後のハンドラーとして）処理します。ランタイムは例外とゴルーチンを出力して終了します。コンソールがない場合（GUI 向けにビルドしたリリース）、Asuka はランタイムの出力をその実行用のファイルに送り、次の起動時にそれを読んで Native レポートにします。Asuka は独自の未処理例外フィルターを設定しません。Go のハンドラーが先に実行されるので、これを置き換えると Go の処理が壊れるためです。Windows エラー報告は、これまでどおり記録を残します。ブラウザーでは、Go のランタイムはクラッシュ出力をファイルに書けない（SetCrashOutput には dup が必要です）ので、Go の実行中はホストがランタイムの出力を保持します。そしてプログラムがパニックや致命的なエラーで終了するときに、それをアプリのファイル（IndexedDB）の中にある、その実行の記録に書き込み、次の起動時にそれが読まれます。捕捉されなかった JavaScript のエラー（ホストのものでも、アプリの web/*.js のものでも）は、その場で Exception レポートになります。致命的なエラーとしては扱われず（ページは動き続けます）、その実行のコンテキストが付きます。1 回の実行につき最大 20 件で、同じエラーは一度だけです。ページはオリジンの localStorage に自分の実行が生きていることを記録するので、同じアプリのほかの開いているページがその記録に手を出すことはありません。

asuka dev では、Go のコードは Mac（または PC）上で動きます。そのクラッシュはこれまでどおりターミナルに表示され、そこに保存されるので、次の実行の crash.Reports で読めます。開発用アプリ自身のネイティブクラッシュはアプリのものではないので、アプリには報告されません。アプリのビルド（asuka dev --once、asuka build）では、すべてが報告されます。