hypershots

HyperShots — App Store 仕様に準拠したスクリーンショット

準拠が必須の要素（HTML/CSS：デバイスフレーム、フォント、文言、正確なキャンバス、ロケール）は決定論的に処理し、役立つ場合に限って生成を活用します（切り抜きステッカー、任意のスタイルグレード）。アプリごとに独自のパネル HTML を作成し、仕様への準拠はスクリプトで保証します。

使用する場合／しない場合

使用する用途：App Store スクリーンショットセットの作成、既存セットのローカライズ、パネルの修正、「スクリーンショットをもっとクールにして」といった依頼、Apple のスクリーンショット仕様に関する質問、完成したセットの ASC への提出。使用しない用途：一般的な画像生成、ソーシャルメディア用／OG 画像、シミュレーターのスクリーンショット撮影（→ fastlane snapshot）。

意図ルーター

ユーザーの要望	最初に読むもの	次に行うこと
新しいスクリーンショットセット	references/create.md	スキャフォールド → ブリーフ → テーマ → 作成 → レンダリング → セルフレビュー → 検証
アプリ用のフォントを選ぶ	references/typography.md	ブランドに合わせるか、メニューから選択 → scripts/fetch-fonts.sh で同梱
見出し／ステッカー／テーマを調整する	references/revise.md	編集 → 再レンダリング → 再検証
既存セットをローカライズする	references/translate.md + references/i18n.md	キーを抽出 → strings..json → 挿入 → レンダリング → 検証
スタイライズ／グレーディングされた見た目	references/edit-filter.md	パネルごとに edit-pass.sh、セット全体で一貫した処理には grade-set.sh（genmedia + ImageMagick が必要）
生成ステッカー／背景	references/asset-recipes.md	固定済みの genmedia レシピ + 簡易モード
キャプチャ／ジェスチャー途中のフレームが必要	references/capture-recipes.md	simctl のステータスバー／外観／連写レシピ
セットを App Store Connect に提出する	references/fastlane-deliver.md	検証 → out/ をコピー → fastlane/screenshots/<asc-locale>/ → deliver レーン
Apple のサイズ／仕様に関する質問	references/store-specs.md	キャンバス表、アセットのルール
hypershots.dev でセットを紹介する	references/gallery-submission.md	同意を条件とする GitHub issue
何かがおかしい	references/gotchas.md	症状 → 原因 → 対処

前提条件（毎回）

bash <skill>/scripts/preflight.sh

常に 0 を返します。これはゲートではなく、レポートです。chrome と node は必須です。どちらか一方でも見つからない場合は、処理を止め、ユーザーのインストールを支援してください（または export CHROME=/path/to/chrome を実行してください）。imagemagick は任意です（アルファのフラット化、スタイル編集の合成に使用）。genmedia も任意です。生成アセットまたはスタイルグレードが必要な場合に限り使用します。見つからず、その作業で必要な場合は、インストールする前にユーザーに確認してください：npm i -g genmedia && genmedia setup（ユーザーの FAL_KEY が必要です）、続けて genmedia skills install genmedia && genmedia skills install fal-models-catalog を実行します。インストールを希望しない場合は、簡易モードを使用してください（references/asset-recipes.md）。

フレームの契約

create.mdを読まなくても、すべてのエージェントが把握しておく必要がある事項です。

• ジオメトリクラス（.panel .stage .device .screen .di .statusbar）は変更不可です。プロファイルの CSS 変数（--panel-w／--panel-h）でサイズが決まります。パネルの px 値をハードコードしたり、.device のスタイルを変更したりしないでください。画面のアスペクト比は約 0.460（幅／高さ）です。タイプクラス（.headline .sub .eyebrow）は theme.css でスタイルを変更できます。これはブランドレイヤーの役割です（fit.js は実際のボックスを測定するため、サイズやウェイトの変更は安全です）。
• .stage は必須の絶対配置レイヤー（inset:0）で、デバイスとステッカーを兄弟要素として保持します。省略すると、デバイスは配置コンテキストを失います（誤りですが、検証は通ります）。
• 実際のシミュレーターキャプチャの上に .di／.statusbar を絶対に追加しないでください（<img class="shot"> にはステータスバーとアイランドがすでに含まれています）。二重 DI バグの原因になります。
• すべてのパネルに必須のマーカーがあります。翻訳可能なすべてのノードに data-i18n="pN.key"（二重引用符で囲み、1 行に記述。テキストと <br> のみを含め、ほかのネストされたマークアップは不可）、見出し／サブブロックに data-fit、.wrap と .device に data-protect="name" を指定します。
• fit.js は <body> 内の最後の要素にする必要があります。document.fonts.ready を待機し、render.sh に必要なフィット／保護ボックスをダンプします。
• パネルは時間、乱数、アニメーションに依存してはいけません。render.sh は Chrome で 2 回（スクリーンショットと DOM ダンプ）処理し、結果が一致する必要があります。
• オーサリング用の完全なひな形、ステッカーのプリミティブ、ナラティブアークのガイダンスについては、references/create.md を参照してください。

ワークスペース

bash <skill>/scripts/scaffold.sh [dir=.shots]

ユーザーのリポジトリ内で実行します。インストールされたスキルのディレクトリは参照専用であり、そこでオーサリングしてはいけません。<ws>/brief.md がすでに存在する場合（修正の段階に入っている場合）は、実行を拒否します。パネルは、ワークスペースと同階層にあるコピーを相対パス（../frame.css、../theme.css など）で参照します。スキルのコピー内に examples/spotless/panels/panel-1.html があれば、最初のパネルを作成する前に、注釈付きの例として読んでください。

出力品質を高めるループ — 必須

render.sh → Read every rendered PNG yourself → fix → re-render → validate.sh → review page (make-review.mjs) + contact sheet → show the user

各 PNG を読み、コピーのはみ出しや不自然な改行、ステッカーの切れや重なり、.di／.statusbar によるアイランドの二重表示、読みやすさ（文字色と背景色のコントラスト、アクセント色がちらついて見えないこと）、キャプチャの引き伸ばしや不適切なトリミングを確認します。Read を絶対に省略しないでください。バリデーターが確認するのは仕様であり、見た目ではありません。切れたステッカーに気づけるのは、あなたの目だけです。

render.sh <ws> [profile=iphone-6.9] [locale=en] の終了コード：1 汎用エラー（Chrome がない、パネルがない、Chrome のクラッシュ、不明なプロファイル。profiles.json を確認してください）；2 フィットエラー（コピーが限界まで達してもデバイスに重なる場合は、限界を変えるのではなくコピーを書き直してください）；3 パネルの寸法がプロファイルと一致しない（ほとんどの場合、パネルの <head> に ../profile.css がありません）。

よくある間違い

実際のキャプチャの上に .di／.statusbar を重ねること、パネルの px 値をハードコードしたり .device のスタイルを変更したりすること（プロファイル → ガター → アルファ → 却下が破綻します）、theme.css でリモートフォントを @import すること（フォントは同梱し、font-display:block にする必要があります）、out/ や panels-<locale>/ を手作業で編集すること（どちらも生成物です。レンダリング時に out/ は消去され、inject が成功すると古い panels-<locale>/*.html は消去されます）、「見た目は問題ない」からと validate.sh を省略すること、iPhone パネルを ipad-13 で再レンダリングすること（ipad は別途オーサリングする必要があり、アスペクト比は 0.75 です）、data-i18n に一重引用符を使うこと（injector が認識できず、英語のまま出荷され、後に未使用キーの致命的なエラーとして表面化します）。

レビュー用チェックリスト（ユーザーに見せる前に）

• 出荷するすべてのプロファイルとロケールで validate.sh が VALIDATED を出力する
• 最後の編集後に、すべての PNG を Read で確認した
• パネルは 10 枚以下。最初の 3 枚でインストールするかどうかが決まる（「Show All」より前に表示されるのは約 3 枚のみ）
• すべてのパネルにマーカー（data-i18n、data-fit、data-protect）がある
• テーマは、ひな形のプレースホルダートークンではなく、アプリの実際のブランドに基づいている

検証

• 上記のコマンド／フラグ／終了コードに関する記述は、利用する前にすべて実際のスクリプトと照合してください。このファイルは概要をまとめたものであり、スクリプトが正しい情報源です。
• スキルの変更を完了とみなす前に、npm run validate（リポジトリのルートで実行。SKILL.md のフロントマターを検証します）と bash tests/run-tests.sh（フィクスチャのレンダリング／検証／翻訳スイート）の両方が成功することを確認してください。