await-widget

スキルをインストールする

このドキュメントは、AI コーディングエージェントで Await ウィジェットを作成するための await-widget スキルに付属しています。作業を始める前に、スキルをインストールしてください。

npx skills add await-widget/skills

使用時の更新

このスキルを npx skills add でインストールした場合は、実行のたびに最初に更新を確認してください。グローバルインストールの場合は npx skills update await-widget -g を実行し、プロジェクトへのインストールの場合は、インストール先プロジェクトのルートで npx skills update await-widget -p を実行してください。コマンドの完了後、インストール済みの SKILL.md を再度読み込み、タスクの残りの作業では最新の指示に従ってください。

ルーティング

このスキルは、完全なリファレンスではなく、ルーティングレイヤーとして扱ってください。

ユーザーがインストールした @await-widget/runtime の宣言と、このスキルの docs-source/ ディレクトリにあるタスク固有のドキュメントを併用してください。これらのパスは、ユーザーのワークスペースではなく、この SKILL.md ファイルを基準に解決してください。ガイドのディレクトリについては docs-source/index.md を参照し、現在のタスクに必要なガイドだけを読んでください。

docs-source/guides/design.md では、ウィジェットのサイズ、レイアウトのルール、読みやすさとコンテンツ、アニメーションの安定性、ボタンについて説明しています。docs-source/guides/resources.md では、ローカルの SVG、画像、音声アセットについて説明しています。

概要

Await ウィジェットは SwiftUI 風の命名を使った TSX 構文で記述しますが、React、DOM、SwiftUI ではありません。構文と命名は借用していますが、API の仕様は @await-widget/runtime の型によって全面的に定義されています。

Await は iOS に 2 つのコールバック関数を提供します。widgetTimeline() は日時付きのエントリーを返し、widget(entry) は iOS が指定したエントリーのビューを返します。これらの関数をいつ呼び出すかは iOS が決定し、バッテリー効率を保つため、タイムラインの更新要求が頻繁すぎる場合は拒否されることがあります。

[1] iOS decides when to update the widget
     │
     ▼ calls
[2] widgetTimeline()
     │
     ▼ returns Entry[]
[3] { entry@09:00, entry@09:01, entry@09:02, ... }
     │
     ▼ iOS specifies entry@09:01, calls
[4] widget(entry)
     │
     ▼ returns the widget view

コアとなるルール

• 利用可能なすべての API と型は、node_modules/@await-widget/runtime/types/*.d.ts で定義されています。これらのファイルを信頼できる唯一の情報源として扱ってください。HTML DOM、ブラウザーおよび Node の API（fetch を含む）、CSS、React 風のフックや状態管理など、これらの宣言に含まれない API や機能は使用しないでください。
• TSX コンポーネントは await モジュールからインポートします（例：import {Text, ZStack} from 'await';）。コンポーネント、プロパティ、モディファイアの定義は node_modules/@await-widget/runtime/types/await.d.ts にあります。
• ブリッジ API はホストが提供するグローバル（Await、AwaitStore、AwaitNetwork、AwaitMusic など）です。これらは直接使用し、インポートしないでください。シグネチャは node_modules/@await-widget/runtime/types/bridge.d.ts にあります。
• コンポーネント属性は、初期化属性またはモディファイアのいずれかです。モディファイアは同じコンポーネントで繰り返し使用でき、その順序も SwiftUI のモディファイアと同様に重要です。TSX 要素で同じモディファイアを複数回使う必要がある場合は、属性名に一意のサフィックス（例：frame_ や frame_1）を付け、TSX の構文エラーを避けてください。
• ウィジェットのビューツリーは、必要以上に増やさず、最小限に保ってください。iOS ウィジェットは厳しいメモリー制限のもとで動作します。ウィジェットのコストはおおむね「タイムラインエントリー数 × ビューツリーのノード数」に比例するため、時間の経過に伴って明らかに異なる状態を表示する必要がない限り、タイムラインエントリーは 1 つにしてください。