Scroll Video Website

使用時機

當使用者想要以下功能時，可使用此技能：

從影片建立 Apple 風格的捲動動畫；
建立由捲動控制或擦洗（scroll-scrubbed）的影片網站；
將產品影片轉換為電影級登陸頁面；
建立由影片驅動的捲動敘事（scrollytelling）體驗；
將影片轉換為最佳化的圖片序列以用於捲動動畫；
建立由捲動控制的 Canvas 產品展示；
最佳化現有已產生的捲動影片影格序列。

請勿將其用於普通的自動播放背景影片或不相關的捲動效果。

建立一個精簡的全頁體驗，類似產品動畫檢視器：頁面本身提供捲動距離，而固定位置的 Canvas 填滿視埠，並根據使用者的影片擦洗影格序列。動畫本身就是介面，而非傳統登陸頁面背後的背景。

調用方式

此技能有兩種模式：從影片建立捲動影片網站，或最佳化現有的影格序列。如果第一個引數是 optimize，則請遵循 references/optimize.md 的指示，且不要執行下方所述的建置工作流程。

將此精簡形式視為完整的建置請求：

$scroll-video-website <path/to/video.mp4>

影片路徑必須是技能名稱之後的第一個引數。路徑之後的所有內容都是可選的使用者指示，用於設定樣式、版面配置、文案或行為：

$scroll-video-website ./media/product-reveal.mp4
$scroll-video-website ./media/product-reveal.mp4 使用黑色背景和緊湊字型

第一個範例表示：從影片衍生影格序列，並建置下方所述的完整預設捲動動畫網站。第二個範例則是在保留相同影片驅動的動畫架構的同時，遵循附加的視覺指示。讓使用此技能的代理程式（agent）來解讀並實作其餘提示；此技能未定義用於樣式選項的獨立命令語法。

將影片路徑解讀為相對於當前工作目錄，除非它是絕對路徑。如果路徑包含空格，使用者應將其加上引號。首先檢查確切路徑。如果裸檔名不存在，則在當前專案中搜尋完全相符的檔名，同時排除依賴項、建置目錄、快取目錄和版本控制目錄。當完全匹配到一個結果時，自動繼續。如果沒有匹配或多個匹配，則詢問使用者精確的路徑。<path/to/video.mp4> 或 {video_path} 中的大括號表示佔位符，不是實際路徑的一部分。不要要求或解讀 use 關鍵字。

使用以下精確命令來最佳化現有序列：

$scroll-video-website optimize

最佳化命令不接受路徑或其他引數。檢查當前專案中是否有已產生的影格序列。當可以明確識別出一個序列時，繼續執行。如果可以識別出多個序列，則顯示它們並詢問要最佳化哪一個。如果找不到序列或無法自信地識別，請告訴使用者未找到影格資料夾並停止。

建立專案與來源影片

在編輯之前：

檢查專案結構、腳本、框架、樣式、路由、資源慣例和本地指示。
使用上述調用規則找到使用者提供的影片。如果未提供影片或路徑，且無法自信地識別，請在實作之前要求提供。
重用現有的有效技術棧。當一個專案已經能正常運行時，不要重頭搭建一個替代專案。
在可用時，使用 ffprobe 檢查影片的尺寸、時長、影格率、影格數量和檔案大小。
保留不相關的行為，並進行最小範圍內的一組連貫變更。

不要建立替代素材或替換提供的影片。除非建置過程需要，否則避免複製來源影片。

將影片轉換為影格序列

預設的渲染路徑是編號的 WebP 影格序列，而非 video.currentTime。將影格提取到專案的公開/靜態資源區域，並使用零填充的名稱，例如 frames/frame_0001.webp。

最多保留 30 fps 的來源節奏。對於較長的剪輯，將其取樣至大約 240–300 個總影格，使負載保持在合理範圍內。
保留來源的長寬比。使用大約 78–82 的合理 WebP 品質，並檢查結果，不要假設設定是足夠的。
在實作中記錄實際提取的影格數量；不要留下猜測的常數。
優先使用 ffmpeg 進行提取。一個代表性的命令是 ffmpeg -i input.mp4 -vf fps=30 -c:v libwebp -quality 80 frames/frame_%04d.webp；請根據輸入、fps、輸出路徑和現有專案工具進行調整。
不要刪除或覆蓋不相關的資源。如果目標位置已包含一個序列，請在替換之前確認它屬於此動畫。

僅當影格提取不可用或產生的影格負載明顯不合適時，才使用直接的暫停影片搜寻（paused-video seeking）。如果採用此備用方案，請解釋其權衡取捨，並保留相同的固定階段、雙向、平滑捲動行為。

匹配參考體驗

當使用者未提供額外的版面或文案指示時，產生一個僅包含 Canvas 的頁面：

白色頁面和固定、溢出隱藏（overflow-hidden）的舞台，覆蓋 100vw 乘 100vh；
足夠的不可見文件高度，以實現有意的擦洗，對於 8 秒或大約 240 個影格的來源，大約為 400vh；
無導航欄、卡片、標題、行動呼籲、漸層或虛構的行銷文案；
一個填滿舞台的 Canvas，以 cover 幾何繪製每個影格，並在兩個軸上居中；
僅在第一個影格準備好之後進行短暫的不透明度顯現，以防止空白影格閃現；
僅在適合影片素材時使用節制的圖片處理，例如白色背景、輕微的對比度調整，或對白色背景的產品渲染使用 mix-blend-mode: multiply。

如果使用者要求內容，則保持內容簡潔，並將其放置在動畫中刻意時刻的上方或之間，而不降低 Canvas 的視覺主導地位。當原生 Canvas 和瀏覽器 API 足夠時，不要引入動畫依賴項。

實作 Canvas 擦洗

使用包含 aria-hidden Canvas 的固定或黏性（sticky）舞台。為裝置像素比率調整其後備緩衝區大小，上限約為 2，同時保持以 CSS 像素為單位的繪製尺寸。在套用新的 DPR 縮放之前，先重置 Canvas 變換，以防止縮放在調整大小時累積。

將限制後的總頁面進度映射到完整的序列：

const range = document.documentElement.scrollHeight - innerHeight
const progress = range > 0 ? Math.min(1, Math.max(0, scrollY / range)) : 0
targetFrame = progress * (frameCount - 1)

向前捲動必須推進動畫，反向捲動必須反向動畫。滾動和調整大小處理器應僅更新輕量的測量值或目標。執行單一 requestAnimationFrame 迴圈，並使用與影格率無關的指數插值來平滑浮點數播放頭：

const dt = Math.min((now - lastTime) / 1000, 0.1)
const alpha = 1 - Math.exp(-dt * 9)
currentFrame += (targetFrame - currentFrame) * alpha

在播放頭的每一側繪製整數影格，並透過小數餘數交叉淡入下一影格。首先清除或繪製 Canvas 背景，在繪製後重置 globalAlpha，並在調整大小時重新繪製。

漸進式載入影格

不要為了等待整個序列而阻塞首次繪製：

首先載入影格 1，繪製它，並顯示 Canvas。
在時間軸上均勻分佈排隊的影格，例如每隔八個影格，以便早期搜寻時有一個近似的備用影格。
為其餘每個影格排隊。

分別追蹤已請求的影格和已載入的影格，以便優先級和剩餘影格的傳遞永遠不會重複請求同一個圖片。當請求的影格仍在載入時，繪製最近已載入的影格。處理失敗的圖片載入，而不阻塞序列的其餘部分。

使用能與專案的基礎路徑和部署目標配合的資源 URL 策略。當所屬元件卸載時，清理滾動、調整大小、媒體查詢監聽器、觀察器和動畫影格。

響應式行為與無障礙

在狹窄螢幕上保持 cover 渲染，並接受有意的裁切；不要扭曲影像。在桌面和行動尺寸下檢查重要的主體位置。如果新增了可見內容，請考慮行動視埠的變化和安全區域。

對於 prefers-reduced-motion: reduce，停止擦洗並保持第一個合適的影格。保持任何頁面內容可存取，且不要劫持捲動。裝飾性的 Canvas 不應產生冗餘的螢幕閱讀器內容。

驗證結果

運行專案的檢查，並在可用時在瀏覽器中檢查結果。確認：

第一個和最後一個捲動位置已到達第一個和最後一個提取的影格；
向前和反向捲動感覺連續，沒有突然的跳躍、播放、閃爍或可見的空白 Canvas；
影格請求沒有重複，且遺失或緩慢的影格使用附近已載入的備用影格；
cover 裁切、DPR 調整大小和 Canvas 縮放在桌面和行動尺寸下正常運作；
減少動畫（reduced motion）保持靜態影格，且元件清理完整；
產生的序列具有預期的數量、尺寸、順序和可接受的總大小；
不相關的專案行為仍然有效。

最後，總結體驗、提取的影格數量和負載、已執行的檢查，以及任何剩餘的來源媒體限制。

滾動影片站