# iPhoneウィジェット（Scriptable + Gist）の作り方メモ

## 概要

iPhoneのホーム画面ウィジェットを、アプリ「Scriptable」とGitHub Gistの組み合わせで作る方法。Scriptableのスクリプトが表示を担当し、データはGistに置いた小さなJSONをraw URLで読むだけ。データの更新はエージェント側がcronでGistを書き換える。サーバー不要で、ウィジェット側は読み取り専用に徹するのが要点。

## 構成

- **表示**: Scriptableスクリプト。`config.widgetFamily` で小/中サイズを分岐し、`ListWidget` を組み立てて `Script.setWidget`。アプリ内で実行したときは `presentSmall()` / `presentMedium()` でプレビューになるよう分岐させる。
- **データ**: Secret Gistに `usage.json` のような小さなJSONを置く。画像を持たせたい場合は、幅800px・JPEG品質80程度に縮小してbase64でJSONに埋め込む。
- **更新**: エージェントがcronでデータを生成し、GitHub APIでGistを更新する。認証は **gistスコープのみのclassic PAT** をエージェントが持ち、GitHubアカウントのパスワード自体は持たない。
- **配布**: 本体スクリプトもGistに置き、短い「取り込み用スクリプト」がraw URLから本体を取得して `FileManager` のドキュメントフォルダへ `.js` として書き込む。本人を介するのは、この短いローダーのコピペ1回だけ。

## 実例（3種）

1. **使用量ウィジェット**: 週間使用率のJSON（残り%、リセット日時、残りトークン概算）を読む。小=顔アイコン+大きな「残りN%」とバー、中=リングゲージ+キャラ絵。`args.widgetParameter` でデザイン切替（長押し→ウィジェットを編集→パラメータ欄。例: 空欄=標準、2=ガラス風、3=ダーク）。
2. **居場所ログ**: cronが数時間ごとに画像を生成し、JSON（時刻・場所・一言・画像base64）を更新。スクリプト側は写真を全面表示し、時計は `addDate` + `applyTimeStyle()` でライブ表示にする（データ側の時刻を固定表示しない）。
3. **サインウィジェット**: 画像をbase64で埋め込んだ静的スクリプト。通信なしで完結するタイプ。

## ハマりどころ

- **チャット添付の表示名が、そのまま保存ファイル名になる。** `.js` で終わらない名前（例: 説明文を付け足した名前）だと、iOSが形式不明としてプレビューもScriptableへの取り込みも失敗する（"The UTI of the file is not supported"）。添付名はファイル名ちょうどにする。
- **画像base64入りのスクリプトは数百KBになり、iPhoneのプレビューでは開けない・真っ白になる。** 構文チェックはPC側で `node --check`（.mjsとして）済ませ、配布はローダー方式にする。
- **ユーザーのScriptableには同種スクリプトの複製が名前違いで増えがち**で、ウィジェットがどれを参照しているか不定。更新ローダーはファイル名でなく「中身の目印文字列（例: データURLの一部）を含む .js を全部上書き」すると確実。
- **ホーム画面の再描画はiOS任せで遅れる。** `refreshAfterDate` は目安にすぎない。変更確認はScriptable内のプレビューで行う。
- **Secret Gistは非公開だが、raw URLを知れば誰でも読める。** 個人情報は入れず、ウィジェット表示用のデータだけに限定する。
- Scriptable小ネタ: テキストの影オフセットは `Size` でなく `Point`。リングやバーは `DrawContext` で描ける。`Color` は第2引数で透明度を指定できる。