page-swarm-rebuild

page-swarm-rebuild は何をしますか？

バージョン 1.3.0（モジュール、アドオン、スタイルシートおよびこのファイル。リポジトリ内の CHANGELOG.md を参照。SwarmRebuild.version）。

プレゼンテーション専用のイントロエフェクト。ページの実際の DOM は変更されません。レイヤーは <head> 内のカスケードレイヤースタイルシートで非表示/表示され、すべてのアニメーションは <html> に追加されたオーバーレイで行われ、最後に両方とも削除されます。依存関係なし、ネットワークリクエストなし（GDPRフレンドリー）、レイアウトシフトなし、サウンドなし、ページが半分非表示のままになることはありません（保護を参照）。

元のエフェクトの仕様（タイムライン、ビジュアル、HUD、スクロールカーブ）： references/effekt-leiras.md（ハンガリー語）。このファイルと矛盾する場合は、このファイルが優先されます（製品決定は説明の作成後に行われました）。

ファイル

ファイル	目的
assets/swarm-rebuild.js	モジュール、読み取り可能なソース（クラシックスクリプト、window.SwarmRebuild を設定。バンドラーからインポートも可能）。
assets/swarm-rebuild.min.js、swarm-rebuild-debug.min.js、swarm-rebuild.min.css	プレーンHTMLサイト用の minify ビルド（scripts/build-min.cjs。インストーラーがこれらを使用。バンドラーはソース自体を minify）。
assets/swarm-rebuild.css	オーバーレイスタイル。すべて #swarm-rebuild-root の下にスコープされます。
assets/swarm-rebuild-debug.js	デバッグアドオン：コントロールバー、自動スクロールツアー、テストフック。訪問者には決して読み込まれません。?rebuild-debug=1 / debug: true でのみフェッチされます。とにかくモジュールの隣にインストールしてください（それが本番サイトでテストする方法です）。
assets/react/SwarmRebuild.jsx	React / Next.js クライアントラッパー + <SwarmRebuildHead />（ペイント前スニペット）。デバッグアドオンは別の遅延チャンクです。
assets/demo/	架空のダークポートフォリオデモ（assets/demo/index.html、214 レイヤー（デスクトップ）、6.6 ビューポート高、スティッキーヘッダー）。
tests/index.html	すべてのテストページへのリンク（全モード）。GitHub Pages のスタートページでもあります。
tests/pages/dental/	架空の歯科医院：ライトテーマ、電話リンク、固定の「お電話ください」+ 予約バー（モバイル）、固定のお知らせ（デスクトップ）。
tests/pages/lang-*/	ハンガリー語、アラビア語（右から左）、日本語、および絵文字が多いページ（任意の言語でタイピング）。
tests/pages/law/、accounting/、bootstrap/、spa/	架空の実世界パターン：Web フォント、スティッキーヘッダー、同意バナー、iframe、遅延画像、ダークモード、長いページ、スクロールリビール、Bootstrap (npm)、シングルページアプリ、動画。
tests/pages/nextjs/	架空の Next.js 15 App Router アプリ：React カウンター（ハイドレーションチェック）、固定のヘルプボタン。
scripts/verify.cjs	1 ページの Playwright チェック（ステップ 4 を参照）。
scripts/run-tests.cjs	3 つのテストページで verify.cjs を実行（デスクトップとモバイル）。サマリーテーブルを出力。
scripts/bench-fps.cjs	旧モジュールバージョンと現行バージョンのフレームレートを同一マシンでインタリーブ実行。
scripts/build-site.cjs	3 つのテストページを 1 つの静的サイト（GitHub Pages）としてビルドするか、ローカルネットワークで提供します。
scripts/next-app.cjs	ヘルパー：Next.js テストアプリを一時フォルダに準備/ビルドします。
scripts/build-min.cjs	.min ファイルをビルドし、サイズ予算をチェックします（npm の terser と csso が必要）。
scripts/perf.cjs	エフェクトあり/なしの Lighthouse メトリクス（LCP、CLS、TBT、Speed Index、アクセシビリティ、SEO）。
scripts/sync-snippet.cjs	モジュールの head スニペットを React ラッパー、SKILL.md、およびテストページにコピーします。
scripts/record-video.cjs	ポートフォリオ用にエフェクトを .mp4 / .webm で録画します（デバッグツアー、コントロールバー非表示）。
scripts/project.cjs	エフェクトをプロジェクトにインストールし（legacy/ にバックアップ）、削除し、オリジナルを復元します。
scripts/test-project.cjs	インストーラーをテスト：バックアップ、破損プロジェクト後の復元（ハッシュ同一）、アンインストール。

製品決定（リファレンスビデオより優先）

• メインモードは scroll（デフォルト）：構築は訪問者のスクロールに追従し、表示されているものだけが構築されます。要素の 60% 以上が画面に表示されると開始されます（buildVisible）。ビューの下または上にあるものは構築されず、作業中のエージェントが画面外に出ることはありません。
• 訪問者はコントロールバーを目にすることはなく、自動スクロールも行われません。 バーとツアーはデバッグアドオンに含まれており、?rebuild-debug=1 または debug: true の場合にのみ読み込まれます。アドオンなしで mode: 'tour' を使用すると、scroll にフォールバックします。
• 常に目に見えないコントロールなしで終了する方法があります。 Esc、Tab、Enter、その他のキー（単独の Shift/Ctrl/Alt/Meta は除く）、および任意のクリック/タップで、アニメーションやレイアウトシフトなしで、すぐに完成したページが表示されます。prefers-reduced-motion の場合はエフェクトはまったく発生しません（WCAG 2.2.2）。
• スクロールキーはスクロールします。 Space、矢印キー、Page Up / Down、Home / End（フォーカスがページ自体にあり、Ctrl / Alt / Meta がない場合）は、マウスホイールとまったく同じように構築をドライブします。フォーカスされたリンク、ボタン、フィールド上、または修飾キーと共に使用された場合は、他のキーと同様にエフェクトを終了します。Tab、Enter、Esc は常にエフェクトを終了するため、キーボードユーザーは最初の Tab で実際のコンテンツ（とそのフォーカス順序）に到達できます。
• エフェクトを終了するクリックが、訪問者が見ていないことを引き起こすことはありません。 まだ完了していないコンテンツ（非表示、または構築中）に着地した場合、そのクリックは飲み込まれます（preventDefault + stopPropagation、マウスは pointerdown ですでに行われているため、フォーカス、リンク、ボタンアクションは発生しません）。完了したコンテンツ（表示されており、内部またはそれを明らかにするものが進行中でない — 例：最初から表示されている電話リンク、または構築済みのボタン）に着地した場合、通常のクリックとして通過し、同時にエフェクトが終了します。理由：すべてのクリックを飲み込むと、表示されている「お電話ください」リンクが最初のタップで機能しなくなります。すべてのクリックを通過させると、訪問者が見たことのないリンクをたどることになります。タッチスクロールとスクロールバーはエフェクトを終了しません（スクロールが構築の駆動方法であるため）。
• サウンドはありません。 モジュールにはオーディオコードは含まれていません。

モード

モード	速度	動作
scroll（デフォルト）	3x	自動スクロールなし。エージェントは表示されているものだけを構築します。要素は、その高さの少なくとも buildVisible（60%）が画面に表示されているときに開始されます。画面より高い要素は、画面の 60% を占めるときに開始され、画面上部から下部に向かって構築されます。ビューの外側には何も構築されず、作業中のエージェントが画面外に出ることはありません（画面より高いフレームは画面端から引き出されます）。高速スクロール（ホイール、キー、Home / End）後、表示部分は約 1〜2 秒で埋まります。これらのレイヤーが最初に開始され、より多くのエージェントが参加し（計画より最大 8 台追加）、タスクの実行が速くなります。ビューから外れたものはすぐに確定します（保護を参照）。
fast	6x	scroll と同じですが、2 倍の速度です。
tour（デバッグのみ）	1x	リファレンスビデオのように自動スクロール：約 layers/7 秒、カメラは作業進行に追従し、カーソルのリングで下部で終了します。録画や比較チェック用。?rebuild-speed=6 は古い「高速」になります（6 倍の自動スクロール、デモで約 9 秒）。手動スクロールは訪問者に引き継がれます。バーの「ツアー」ボタンで再開します。

構築後、群れはフォーカス要素の周りに集まり、autoExit 秒後（3 秒。デバッグアドオンがある場合は 6 秒、ツアーモードでは決してない）にオーバーレイが消えます。

モーション

デフォルトではすべて控えめで、motion で設定されます（設定を参照）。?rebuild-motion=arc:0,... で一部をオフにして A/B テストが可能です（デバッグアドオン）。

• フォーカス要素（focus）：開始とフィナーレで群れがその周りを回ります。開発者に尋ねます（ステップ 1）。各フェーズで、次のうち少なくとも半分がビューに表示されている最初のものが使用されます：設定された要素、[data-swarm-focus]、h1、メインボタン（a.btn、.button、.cta、button[type=submit] ...）、ロゴ。次にビュー内で最大の画像。次にビュー内のスポット。したがって、ページの下の方にあるフォーカス（例：最後の行動喚起）はフィナーレに機能し、開始はメイン見出しを使用します。
• 群れ： フリーエージェントは、サイズが明らかに異なる 2〜4 の群れで飛行します（スマートフォン：2）。各エージェントは、減衰バネによって群れ内の自分の場所に引き寄せられます。群れの中心は、フォーカス要素の周りの楕円上を移動し、その半径は呼吸し、ペースは変化するため、エージェントは自力で加速・減速し、完全な円を描くことは決してありません。開始はすでに群れで始まります（訪問者にとっては 1 秒未満続きます）。
• 休憩中のエージェント（構築中、作業のないエージェント）：群れを離れ、ビュー内の自分の場所（他の休憩中のエージェントから少なくとも 72 px 離れている。重なり合うカーソルのクラスターは決して発生しない）に移動し、ゆっくりとドリフトし、1.4 秒後にフェードアウトします。次のタスクを受け取ると、休憩していた場所にフェードインします。フィナーレでは、すべてのエージェントが戻り、フォーカスの周りの群れに集まります。測定値：フレームの 99.6〜100% で最大 2 つの重なり合う休憩カーソル（1.2：デモで中央値 6、最大 20）。
• フィナーレ： 硬く、減衰不足のバネ（ダンピング 0.63、motion.spring）がすべてのエージェントをフォーカスに引き寄せます。開始時が最も速く、自分の場所を約 5〜20% 過ぎてから戻ります。約 1 秒後、バネは柔らかくなり、群れはゆっくりと旋回します。
• マウス（開始とフィナーレ、デスクトップのみ。タッチでは決してなく、モーション減少時もなし）：ポインターの近くのエージェントはポインターの邪魔にならないように移動します（ポインターが速く来るほど強く）。その後、最大 3 つの好奇心旺盛なエージェントが小さな円を描いてポインターを追跡します。ポインターが止まっているときは 1.3〜2 秒、遠ざかる速度が速いほど短くなります（関心は (1 + speed / 220 px/s) 倍の基本レートで減少）。36 px より近づくことは決してありません（ハードリミット。アイコンが重なることはありません）。オーバーレイはポインターイベントを無視するため、クリックが妨げられることはありません。
• 重力： エージェントは作業中の要素を運ぶため、そこへの経路（および運ばれたクローンコピー）は下向きに曲がります。たわみ = 0.2 x 水平距離 x 重み x 水平度²、重み = sqrt(面積) / 320 px で 0.2..1 にクランプ、最大 56 px かつ水平距離の 5 分の 1。垂直移動はほとんど曲がりません。タスクへの経路は、エージェントの現在の速度（3 次エルミート曲線）でも始まるため、突然の停止や方向転換はありません。
• 難易度： 各タスクの作業（そこへの経路ではない）は、要素の面積（タイピングの場合：入力されるボックス）に基づく難易度でスケーリングされます。ページ平均付近で面積の 2 倍〜時間の 1.6〜1.8 倍、圧縮（tanh）され、最も難しいタスクは最も簡単なタスクの最大約 4 倍かかります。正規化（タスクの長さと難易度で重み付け。並列タスクは長いタスクがペースを設定するため）されるため、全体の構築時間は以前と同じになります。小さなタスクと大きなタスクの分割のみが変更されます。
• ライト（motion.lite: 'auto'）：スマートフォンでは 2 つの群れとマウスプレイなし。構築中にフレームレートが 2 秒間 38 fps 未満を維持した場合、3 つのトレイルゴーストの代わりに 1 つになります。

言語と書記方向

モジュールは言語を想定していません。タイピングはユーザー知覚文字（書記素クラスター、Intl.Segmenter。結合マーク、ZWJ シーケンス、肌の色調、異体字セレクタ、国旗ペアを結合するフォールバックあり）で行われます。アクセント付き文字、絵文字ファミリー、国旗、またはアラビア語/ヘブライ語のマークが付いた文字が分割されることはありません。未入力のテキストは隠しテキストとしてその場に残り、ブラウザはその境界を越えてシェーピングするため、アラビア語の文字は結合された形状を維持し、リフローは発生しません。右から左の要素（direction: rtl、例：<html dir="rtl">）：フレームは右端から成長し、線は右から左に描画され、エージェントは左側に入力し、キャレットは最後に入力された文字の左にあります。右から左のテキスト内の左から右の実行（数字、電子メールアドレス、ラテン語の名前）は、貼り付けられた単語のように全体として入力されます。CJK テキスト（スペースなし）と長い単語は、ページ上とまったく同じように折り返されます。オーバーレイ自体は常に左から右にレイアウトされるため（ルートで direction: ltr）、右から左のページがオーバーレイをミラーリングすることはありません。任意のスクリプトの数字（\p{Nd}）は数字としてカウントされます。テストページ：tests/pages/lang-hu（ő / ŭ、非常に長い単語）、lang-ar（右から左、アラビア・インド数字、ヘブライ語の引用）、lang-ja（日本語）、lang-emoji。既知の制限：垂直書きモード（writing-mode: vertical-rl）では入力は行われますが、フレームは依然として左から右に成長します。

パフォーマンス、検索エンジン、アクセシビリティ

• サイズ（訪問者がダウンロードするもの。デバッグアドオンは決してダウンロードされません）：モジュール 70 KB minified / 27.5 KB gzip、スタイルシート 6 KB / 1.6 KB。予算 30 KB + 2 KB gzip（node scripts/build-min.cjs --check）。モジュールを変更するたびに .min ファイルを再ビルドします（--modules <terser と csso のあるフォルダ>）。

• Lighthouse（scripts/perf.cjs、中央値 3、モバイル/デスクトッププリセット、GPU なしのテストマシン）：

  ページ	LCP ms オフ→オン	CLS オフ→オン	TBT ms オフ→オン	Speed Index ms オフ→オン	パフォーマンススコア
  デモ、モバイル	2106 -> 2207	0 -> 0	12 -> 10	968 -> 1669	99 -> 99
  デモ、デスクトップ	483 -> 573	0 -> 0	0 -> 0	266 -> 681	100 -> 100
  歯科、モバイル	1956 -> 2035	0 -> 0	0 -> 0	754 -> 1763	99 -> 99
  歯科、デスクトップ	442 -> 490	0 -> 0	0 -> 0	201 -> 767	100 -> 100
  法律（Web フォント）、モバイル	2094 -> 2222	0.030 -> 0	0 -> 0	1895 -> 2386	98 -> 97
  会計（長いページ）、モバイル	1707 -> 1973	0 -> 0	0 -> 0	1652 -> 1697	99 -> 98

  ブロッキングタイムとレイアウトシフトはありません（法律ページ独自のフォントスワップシフトも非表示になります）。LCP は 50〜270 ms 増加し、Speed Index は最大約 1 秒増加します。最初のビューが訪問者の前で構築されるため、視覚的に完了するのが遅くなります。これはエフェクト自体です。初回訪問者（セッションごとに 1 回）のみがこの影響を受けます。再訪問者とクローラーはページをすぐに受け取ります。アクセシビリティ/SEO スコアは、Lighthouse がページの一部（非表示中）をあまり認識しないためにのみ、1 ポイント上下します。

• 検索エンジンとリンクプレビュー： クローラー（ボット / クロール / スパイダー、Googlebot、Bingbot、facebookexternalhit、リンクプレビュー ... のユーザーエージェント）は、head スニペットでもモジュールでもエフェクトを受け取ることはありません。完成したページを同一の DOM で表示します（a11y チェック）。JavaScript がない場合、ページが非表示になることはなく、エフェクトがコンテンツを削除することもありません（visibility のみを使用します）。

• アクセシビリティ（a11y）：キーボード操作の終了（Tab で実際のコンテンツへ）、prefers-reduced-motion（エフェクトなし）、サイズ変更/ズームへの応答（vw と vh の単位、固定要素の調整）、マウスプレイのないタッチ、スクリーンリーダー向けの aria-hidden オーバーレイ、終了トリガー時のフォーカス管理、ランタイムエラーとブラウザ機能の欠如の処理、クローラー向けの即時完全なページ。

保護

• タイムアウト：最初の要素の開始から 30 秒後にアニメーションがトリガーされなかった場合、エフェクトは終了します。これにより、CSS の読み込みに失敗した場合、または IntersectionObserver がない場合でも、ページが表示されたままになります。
• 破損：requestAnimationFrame ループが 5000 ms を超えてフリーズした場合（タブがバックグラウンドにある場合など）、エフェクトは終了し、影響を受けた要素を即座に確定します。
• ビューから外れた要素：60% 以上がビューから外れた要素はすぐに確定します。スクロールを元に戻すと、前の要素は非表示のままですが、新しい要素が再開します（シームレスな動作）。
• スクロール終了（scrollend）：スクロールが 300 ms 以上停止すると、それ以上構築されないため、すべての表示要素が確定します。
• リサイズ：resize イベントが発生してもリセットは行われません。エフェクトは、新しいビューポート内の要素の構築を続行します。

設定

モジュールは、<head> 内のインライン <script> で構成されます。例：

<script>
window.swarmRebuildConfig = {
  focus: '#main-cta',
  buildVisible: 0.5,
  motion: {
    spring: 0.8,
    gravity: 0.3
  }
};
</script>

設定オプション：

オプション	型	デフォルト	説明
focus	string または string[]	自動検出	フォーカス要素の CSS セレクター。
buildVisible	number	0.6	要素の構築を開始するために必要な可視部分の割合。
autoExit	number	3	構築後、オーバーレイが消えるまでの秒数。
mode	'scroll' または 'fast'	'scroll'	構築モード。
motion.spring	number	0.63	フィナーレバネの減衰。
motion.gravity	number	0.2	重力の強さ。
motion.lite	boolean または 'auto'	'auto'	ライトモード。true は強制、false は無効。

このスキルの使用タイミング

ユーザーが以下のいずれかを依頼した場合に使用します。

• カーソルの群れ / エージェントがページを再構築する効果
• 「Figma でマルチプレイヤーがサイトを構築している」ようなイントロ
• 「ページが自動構築される」効果
• 「再構築アニメーション」効果
• page-swarm-rebuild への言及