Pryne フロントエンドアーキテクチャ契約
Pryne のバニラ JS ビルドにおける構造上の重要な決定、その存在理由、そして絶対に破ってはいけない不変条件。リファレンス実装：Portfolio（テスト）リポジトリ（~/Documents/Coding Folder/Portfolio (test)）の design-demos/、アクティブビルド v4-d-hybrid.html + js/roll-*.js（2026-07-22 時点）。
専門用語（一度だけ定義）： IIFE = 即時実行関数式、(function () { ... })(); — ファイルスコープのクロージャで、ファイルが明示的に共有名前空間に配置したもの以外は何もリークしません。プログレッシブエンハンスメント = ページは JavaScript による拡張がまったくなくても完全に使用可能。よりリッチな動作は、その依存関係が実際にロードされた場合にのみ追加されます。Develop-plate = このプロジェクトのキャンバスアートワークで、ユーザーが操作するにつれて「展開」（ノイズから解決）します。
このスキルを使用しない場合
- アニメーションのタイミング、イージング、振付理論 → pryne-motion-reference
- 変更が許可されているかどうか、およびそのゲート方法 → pryne-change-control
- 何かが壊れていて診断中 → pryne-frontend-debugging
- 変更が機能することを証明する（スクリーンショット、Lighthouse、ルーブリック） → pryne-validation-and-qa
- React/Next.js またはバンドラープロジェクト — この契約はビルドなしのバニラサイト専用です。
モジュール契約
懸念事項はファイルごとに 1 つ。IIFE はファイルごとに 1 つ。バンドラなし、インポートなし。
すべてのモジュール間の状態は、単一のグローバル名前空間オブジェクト — ここでは window.Roll — 上に存在します。roll-core.js がこれを作成し、最初にロードされます。他のすべてのモジュールは const Roll = window.Roll; で始まり、そのプロパティを読み書きします（roll-core.js:1-7 で明示的に記述）。相互に認識する必要のないモジュールは、代わりに DOM イベントを介して通信します（例：roll-scroll.js は roll:launch をディスパッチし、roll-contact-sheet.js がリッスン — roll-scroll.js:35-37 参照）。
HTML 内のスクリプトの順序が依存関係グラフです。 v4-d-hybrid.html:429-437 より：
roll-core.js → roll-shader.js → roll-field.js → roll-audio.js → roll-cursor.js
→ vendor/lenis.min.js → roll-scroll.js → roll-contact-sheet.js → roll-eggs.js
不変条件：<script> の順序を変更したり挿入したりする前に、必ずモジュールが Roll から何を読み取っているかを grep し、すべてのプロデューサーがより前にロードされていることを確認してください。 あなたを救う import システムはありません。順序を変更すると、静かに失敗するか、ロード時にスローされます。
grep -n "Roll\.\w*" design-demos/js/<module>.js # 読み取り/書き込み内容
GSAP は意図的にそのチェーン内にありません — 不変条件 2 を参照。
モジュールマップ（2026-07-22 時点）
| ファイル | 1 つの懸念事項 | 行数 |
|---|---|---|
roll-core.js | 名前空間、共有状態、develop-plate エンジン、upgradeMotion | 192 |
roll-scroll.js | 背骨：エントリー、スクロール振付、HUD、メイン rAF（requestAnimationFrame）ループ、Lenis | 226 |
roll-field.js | 背景キャンバスフィールド | 136 |
roll-shader.js | WebGL グレイン/ライトシェーダー + canvas-2D フォールバック | 133 |
roll-eggs.js | 隠されたパーソナリティトリガー（ささやきレベル限定） | 83 |
roll-audio.js | スクロール速度に連動した静かなアンビエントサウンド | 79 |
roll-contact-sheet.js | 起動時のコンタクトシート表示 | 55 |
roll-cursor.js | カスタムカーソル（デスクトップのみ、GSAP ゲート付き） | 36 |
新しいインタラクティブ機能？それは新しい roll-*.js ファイル（またはその懸念事項を所有するモジュールの明確に区切られたセクション）であり、依存関係の位置でスクリプトチェーンに追加されます — HTML 内のインライン <script> ではありません。
不変条件（コードで検証済み — これらを true に保つこと）
- 動きの抑制はすべてのモーション モジュールをゲートします。
Roll.reduced = matchMedia('(prefers-reduced-motion: reduce)').matches（roll-core.js:9）。すべてのモジュールがこれを参照します。シェーダーは WebGL をスキップ（roll-shader.js:90,124）、フィールドは rAF ループをスキップ（roll-field.js:125,135）、コンタクトシートは早期 return（roll-contact-sheet.js:12）、スクロールは hold-to-develop エントリーと Lenis をスキップ（roll-scroll.js:39-40,152）、CSS は clip-path トランジションを解除（v4-d-hybrid.html:293-295）。新しいモーションは、Roll.reduced（JS）をチェックするか、動きの抑制メディアクエリ（CSS）の下に配置する必要があります。 - GSAP はプログレッシブエンハンスメントであり、依存関係ではありません。 CDN から SRI ハッシュ付きで
asyncロードされます（v4-d-hybrid.html:440）。ロード時にRoll.upgradeMotion()を呼び出し、Roll.enhancedを true に切り替え、Roll.onMotionReadyを介して登録されたコールバックをフラッシュします（roll-core.js:10-15,186-191）。GSAP が到着しなくても、サイトは完全に機能し続ける必要があります。カーソル、ヒーロータイプ、スキューはベースラインのままです（roll-cursor.js:34-35、roll-scroll.js:32-33,89,196）。GSAP 依存のコードはRoll.onMotionReady(fn)で登録してください。gsap.*を無条件に呼び出さないでください。 - 危険なビジュアルテイクオーバーは防御的にラップされています — セットアップ時だけでなく、繰り返し発生するパスでも。 カスタムカーソルは 3 つのレイヤーでガードされています。各レイヤーにはリストアキャッチがあり、
Roll.cursorUpdateを null に設定し、.custom-cursor（OS カーソルを非表示にする）を削除します。セットアップ（roll-cursor.js:9-32、32 でキャッチ）、イベントハンドラー本体ごと（roll-cursor.js:17-20）、pointermoveコールサイト（roll-core.js:26-29）。任意の時点での失敗 — セットアップ時またはその後の mousemove — で OS カーソルが復元されます（2026-07-22 修正；ファイルヘッダー、roll-cursor.js:1-5のフェイルセーフ契約）。ネイティブアフォーダンスを非表示/置換するものにこのパターンを適用する場合は、セットアップ時だけでなく、繰り返し発生するパスもガードしてください。 - clip-path の表示は内部ラッパー上にあり、IntersectionObserver が監視する要素上には決してありません（「concept-C 修正」 — v4 コンセプト C、
v4-c-ch001.htmlにちなんで命名。v4-d に引き継がれる前にそこで発生）。IO は.panelを監視し、clip-path は.panel-innerをアニメーション化します（v4-d-hybrid.html:121-122,185-186）。根拠：監視対象の要素をクリッピングすると、その交差ジオメトリが変更され、表示がトリガーと競合します。 - エンゲージメント駆動型のビジュアルは、ページのロードではなく、自身の可視性にゲートされます。 フィーチャープレートは、そのパネルが
.inを持っている間のみ展開します（roll-scroll.js:204-219）。コードコメントには元のバグが記録されています。誰もスクロールする前にプレートが解決を完了し、「操作しながら展開する」インタラクションを静かに無効にしていました。v4-d-hybrid.htmlの先頭コメントは、この修正をテクニカル監査からの最も優先度の高いものと呼んでいます。 - WebGL は明示的で、フォールバックに対して安全です。 コンテキスト作成時の非プリマルチプライドアルファ（
roll-shader.js:17）、毎フレームの明示的なgl.clear（roll-shader.js:95）、WebGL がチャンスを得た後にのみ 2D コンテキストを取得 — キャンバスは常に 1 つのコンテキストタイプのみを持つことができます（roll-shader.js:9-12）。webglcontextlostは、レンダリングループをスローさせる代わりに静かに失敗します（roll-shader.js:129-132）。呼び出し元は単一のRoll.shader.render(t)エントリポイントを使用し、GL と 2D を認識しません。 - スクロールは Lenis の下でもネイティブのままです。 Lenis はベンダリングされています（
js/vendor/lenis.min.js、CDN ではない）、!Roll.reducedの場合のみインスタンス化され、window.scrollYを有効に保ちます — これはフィールのアップグレードであり、スクロールのハイジャックではありません（roll-scroll.js:148-152,167）。レンダリングループは以前と同様にscrollYを読み取ります。
単一ファイルデモの哲学 + デザイントークン
各デザインバリアントは 1 つの自己完結型 HTML ファイルです（インライン CSS、共有 js/ モジュール）。これにより、バリアントをアーティファクト全体として差分比較、スクリーンショット、A/B テストできます — pryne-design-direction-decision を参照。各ファイルの長い先頭コメントには、そのバリアントが何であるか、およびどの監査結果を保持しているかが記録されています（編集前に読んでください。これはファイルのローカルな変更履歴です）。
すべての色、スペーシング、イージングは :root 内の CSS カスタムプロパティです（v4-d-hybrid.html:50-63）：
:root {
--bg: #0a0a0b; --accent: #d2232e; --ink: #f4f3f1; --dim: #86868c;
--pad-x: clamp(1.25rem, 6vw, 6rem);
--ease-out: cubic-bezier(0.22, 1, 0.36, 1);
--ease-snap: cubic-bezier(0.16, 1, 0.3, 1);
}
Pryne のグローバルルールに従ってください。トークンが存在する場合に色/サイズをハードコードしないでください。流動的な値には clamp() を使用します。新しいモーションは、pryne-motion-reference が別途指示しない限り、--ease-out/--ease-snap を再利用する必要があります — ビルドごとに 1 つのイージング言語。
チェックリスト：モジュールの追加
- 新しい
roll-*.js（または正しい既存の所有モジュール）、トップレベルの IIFE、const Roll = window.Roll; -
Rollから読み取るすべてのものの後、それを読み取るすべてのものの前に<script>が挿入されている -
Roll.reducedをチェック。GSAP の使用はRoll.onMotionReady内のみ - ネイティブアフォーダンスを非表示にするものは、リストアキャッチ付きの try/catch でラップされている
- エンゲージメント駆動型の場合は可視性ゲート付き。IO ターゲット ≠ clip-path ターゲット
- トークンを使用し、ハードコードされた値は使用しない
- その後、pryne-validation-and-qa に従って検証する
既知の弱点（オープン、明確に記述）
- ビルドステップなし：ミニファイなし、バンドルなし。デモには問題ないが、プロダクションデプロイには未解決。
- フォントは Google Fonts CDN からロード（
v4-d-hybrid.html:47-48）、プロジェクトのベンダーファーストの意図と矛盾（セルフホスティングはdesign-demos/DECISIONS.mdで Lenis のエントリ内で簡単に言及されているのみ。決定記録自体はファイルよりも前。まだ完了していない）。GSAP もまだ CDN（ピン留め + SRI）。いずれかを「修正」する前に pryne-change-control を参照。 - 自動テストなし — 検証はブラウザベースの証拠のみ（pryne-validation-and-qa）。
- プレースホルダーコンテンツ：ケーススタディ/経歴は最終版ではない。コピーを完成形のように磨かないでください。
来歴とメンテナンス
scripts/verify.sh（このスキルのディレクトリ内）を実行して、以下のすべてを一度に確認します。
Portfolio（テスト）リポジトリのコミット 457868a（2026-07-22）に基づく。揮発性の事実を信頼する前に再確認：
- スクリプトの順序：
grep -n "<script" design-demos/v4-d-hybrid.html - 行数 / モジュールリスト：
wc -l design-demos/js/*.js - 動きの抑制カバレッジ：
grep -rn "Roll.reduced\|prefers-reduced-motion" design-demos/ - GSAP がまだ CDN+SRI、フォントがまだ CDN：
grep -n "cdn.jsdelivr\|fonts.googleapis" design-demos/v4-d-hybrid.html - Lenis がまだベンダリングされている：
ls design-demos/js/vendor/ - アクティブビルドがまだ v4-d である：
design-demos/DECISIONS.mdと最新のgit log --onelineを確認