@plotdb/lotion 0.1.0

package/prompt/explainer.md

@@ -0,0 +1,71 @@
+# 解說動畫 ( Explainer ) 的做法
+
+`ui-loop.md` 針對的是短、循環、以單一物件變形為主的 UI motion。解說動畫的需求不同：
+較長、要講清楚一個概念、通常不循環、會嵌進網頁也可能輸出成影片。以下是從
+「舒爾茲投票法」解說動畫整理出的做法，可與 `ui-loop.md` 並用。
+
+
+## 流程
+
+ 1. 先寫故事線：一句話一個段落 ( chapter )，每段只推進一個概念。
+    概念之間若有缺口 ( 例如要證明「一定有贏家」之前，得先介紹「路徑強度」)，主動補段並告知。
+ 2. 準備資料：用真正的函式庫計算，畫面上的數字一律取自計算結果，旁白再依資料撰寫。
+    需要特定性質的資料 ( 例如出現循環、但最後能排出完整順序 ) 時，用程式搜尋，不要手湊。
+ 3. 排時間軸：以段落起點加相對時間描述所有事件，方便整段平移或調整長度。
+ 4. 實作 `seek(t)`，再用 `lotion sheet` 輸出各段代表畫面檢查版面，修正後再輸出影片。
+
+
+## 原則
+
+ - 畫面是時間的純函數：`seek(t)` 只依 `t` 計算，不保留跨影格狀態。
+   播放、拖曳、跳段與逐格輸出都只是用不同的 `t` 呼叫它。
+ - 元素連續：同一個東西在不同段落中應是同一個元素在移動 ( 票上的數字飛進表格、節點飛上頒獎台 )，
+   而不是淡出後換一個新的。
+ - 旁白分兩層：段落標籤 ( 如「第三步 · 兩兩對決」) 與一句旁白。同段的標籤共用一個元素，避免閃爍。
+   旁白進出場用淡入淡出加輕微模糊，舊的出場與新的進場不可重疊在同一位置。
+ - 強調只用一種語彙：凸顯 = 加粗變深，其它變淡；錯誤 / 矛盾 = 紅色。避免同時有多種強調方式。
+ - 圖的配置要先避開交錯：例如四個節點的完全圖，把「輸給所有人」的節點放在三角形中央即可平面化。
+ - 標籤不要壓在連線上：名字預設放右側，遇到連線時個別調整，移動時以彈簧插值切換位置。
+
+
+## 嵌入網頁時
+
+ - 舞台用固定的設計尺寸 ( 如 1920×1080 )，依容器等比縮放；不要對被縮放的元素用 `will-change`，文字會糊。
+ - 網頁裡常有 bootstrap 等全域樣式：class 加前綴 ( 或用 `@plotdb/block` 讓 csscope 處理 )，
+   並把 css 限定在播放器根元素下。
+ - 以 pug 的 `:lsc` filter 內嵌時會以 bare 模式編譯，頂層變數會變成全域：整段包進函式。
+   若依賴以 defer 載入，inline script 要等到 `DOMContentLoaded` 才能使用它們。
+ - 鍵盤操作只在播放器取得焦點時作用，避免空白鍵捲動頁面時誤觸。
+ - 預設不要自動播放；停在一個有內容的畫面 ( 例如開場標題 )。
+ - 內容需要非同步準備時 ( 字型載入、依版面量測元素位置 )，準備完成後才呼叫 `player.start()`。
+   在那之前播放器會顯示載入畫面、隱藏舞台並停用控制列，避免讀者看到尚未就緒的錯亂畫面。
+   以 block 封裝時，interface 要帶上 `ready: player.ready`，render 協定才會等它就緒。
+
+
+## 配樂與音效
+
+ - 先決定節奏再排時間軸：`lotion bgm --bpm 120 --grid grid.json` 產生配樂與節拍格線，段落起點與重要轉場對齊拍點。
+   使用現成音樂時以 `lotion beats` 分析，並確認第一拍是否偏了半拍。
+ - 音效以 cue 描述 ( `[{t, sfx, gain}]` )，由頁面的 `cues()` 提供，與畫面共用同一份時間軸；
+   混音時對齊的是音效量測到的 transient peak，而不是檔案開頭。
+
+
+## 可攜的封裝
+
+ - 要放進其它網站時，把動畫包成 `@plotdb/block`：依賴 ( 包含 lotion ) 以 `pkg.dependencies` 宣告，
+   樣式自動限定範圍。`lotion bundle` 產出單一 bundle 檔，配合 `player.js` 即可在任何網站播放。
+ - csscope 限定的是 root 的子孫：樣式的目標元素要放在 root 之下 ( 或用 `:scope` )。
+ - block 內不要寫 `body.xxx` 這類外層規則，會被 scope 掉；需要時改由 js 設定。
+
+
+## 常見錯誤
+
+ - 子元素設定 `visibility: visible` 會蓋過父元素的 `hidden`：只對最外層元素切換 visibility，
+   子元素只調 opacity ( `lotion.put` 的 `hide: false` )。
+ - 依賴「目前選中哪個」決定的樣式 ( 如分頁文字顏色 ) 在動畫過程中會出錯；
+   改為依當下的幾何狀態計算 ( 文字是否被指示器蓋住 )。
+ - 載入時看到錯亂的畫面：舞台內容在準備完成前就顯示了。把非同步準備 ( 字型、量測 ) 放在 `start()` 之前，
+   不要先 `start()` 再補；逐格輸出也會因此在就緒前就開始錄。
+ - 某個時間之前資料尚未存在 ( 例如 `filter(...).pop!` 回傳 undefined )：`seek` 必須對任何 `t` 都成立，
+   包含 0 與總長之後。用 `lotion sheet` 掃過頭尾與每段交界。
+ - LiveScript：`.5` 這類小數會被當成八進位錯誤，寫 `0.5`；`by`、`to`、`on` 等是保留字，不能當變數名。

package/prompt/ui-loop.md

@@ -0,0 +1,497 @@
+You are a senior motion designer and creative frontend engineer.
+
+Your task is to create a premium, Dribbble-level UI motion design entirely with code.
+
+Do NOT start coding immediately.
+
+PHASE 1 — ASK FOR INPUTS
+
+First ask me for:
+
+1. 8–12 UI states that the main shape should transform into.
+Examples:
+
+- Button
+- Loader
+- Success check
+- Dynamic Island
+- Music player
+- Progress scrubber
+- Volume slider
+- Toggle
+- Tabs
+- Chart
+- Command palette
+- Toast
+
+2. Visual palette:
+
+- Pure black + white
+- OR black + white + one accent color
+
+3. A royalty-free music track around 120 BPM.
+
+Prefer music that can legally be used commercially, such as tracks from Mixkit or similar royalty-free libraries.
+
+After I answer, DO NOT code yet.
+
+---
+
+PHASE 2 — BUILD THE MOTION SCORE
+
+Create a beat-by-beat animation plan.
+
+Target:
+
+120 BPM
+7 bars
+4 beats per bar
+28 primary beats
+
+Something meaningful should happen on nearly every beat.
+
+Show the timeline before writing code.
+
+For every beat, define:
+
+- beat number
+- timestamp
+- current UI state
+- transformation
+- cursor action
+- camera action
+- sound effect
+- spring / easing behavior
+
+Example flow:
+
+Button
+→ Loader
+→ Check
+→ Dynamic Island
+→ Music Player
+→ Play/Pause morph
+→ Progress scrub
+→ Volume slider
+→ Overscroll/stretch
+→ Toggle
+→ Liquid tabs
+→ Chart
+→ Tooltip
+→ Command palette
+→ Search typing
+→ Enter
+→ Toast
+→ Original button
+
+The final state must transition perfectly into the first frame.
+
+---
+
+VISUAL DIRECTION
+
+Aim for premium contemporary product motion design.
+
+Reference quality:
+
+- high-end Dribbble motion
+- Linear
+- Arc
+- Raycast
+- Apple system UI
+- Stripe
+- modern Vercel-style interfaces
+
+Canvas:
+
+1440 × 1440 square.
+
+Background:
+
+Light warm gray.
+
+UI:
+
+Mostly black and white.
+
+Optionally one accent color.
+
+Typography:
+
+Geist or another clean modern UI sans-serif.
+
+Icons:
+
+Consistent stroke weight.
+
+No mismatched icon families.
+
+---
+
+CORE MOTION RULE
+
+There is ONE primary shape throughout the entire animation.
+
+Never cut between unrelated objects.
+
+Every interface state must feel like the SAME physical object transforming.
+
+Transformation properties may include:
+
+- width
+- height
+- border radius
+- position
+- fill
+- stroke
+- internal layout
+- content
+- clipping mask
+
+Content may change during a morph using a very short blur/fade transition.
+
+The object itself must remain visually continuous.
+
+---
+
+INTERACTION
+
+A visible cursor drives the animation.
+
+The cursor should:
+
+- move intentionally
+- click real controls
+- drag sliders
+- hover charts
+- type into inputs
+- trigger state changes
+
+Avoid arbitrary cursor movement.
+
+Every cursor action must have a visible cause and effect.
+
+Clicks should feel tactile.
+
+Drags must use direct manipulation.
+
+While dragging:
+
+value = function(cursor position)
+
+Do not fake the slider movement independently of the pointer.
+
+When released, the element may continue using a spring from its release position.
+
+---
+
+SPRINGS
+
+Use springs extensively.
+
+Do NOT use generic CSS easing curves for the primary motion.
+
+Springs must be implemented as closed-form mathematical step responses.
+
+Avoid exaggerated bouncing.
+
+Desired character:
+
+fast
+precise
+slightly physical
+tiny overshoot at most
+
+If a property changes target multiple times, compute it as the sum of independent spring responses for each target change.
+
+The animation must remain a pure function of time.
+
+---
+
+LIQUID MOTION
+
+For elements such as:
+
+- tabs
+- toggles
+- sliders
+- pills
+
+animate the leading and trailing edges independently.
+
+Example:
+
+When a tab indicator moves right:
+
+leading edge spring → faster
+
+trailing edge spring → slightly slower
+
+This creates temporary stretching.
+
+Then both edges converge.
+
+Apply the same principle to the toggle knob.
+
+The effect should feel elastic but restrained.
+
+Never cartoonishly bouncy.
+
+---
+
+CAMERA
+
+The virtual camera should subtly reframe each state.
+
+Every important UI state should comfortably fill the composition.
+
+Use:
+
+- scale
+- translation
+
+Avoid unnecessary rotation.
+
+Camera movement must also be driven entirely by time.
+
+Avoid blurry text.
+
+CRITICAL:
+
+Do NOT apply "will-change" to elements that the camera scales.
+
+It can cause browser text rasterization and make typography blurry.
+
+---
+
+TEXT TRANSITIONS
+
+When content changes inside a morphing container:
+
+old content must have a defined EXIT window.
+
+new content must have a defined ENTER window.
+
+Never allow both text states to occupy the same visual space unintentionally.
+
+Suggested transition:
+
+old text
+→ fade + blur + slight movement
+→ container morph
+→ new text unblur + fade in
+
+Keep transitions short.
+
+---
+
+AUDIO
+
+Analyze the selected music using Python + NumPy.
+
+Determine:
+
+- BPM
+- beat timestamps
+- downbeats
+- useful transients
+
+Start the motion sequence on a strong downbeat.
+
+Align important transitions to musical beats.
+
+UI sound effects may include:
+
+- click
+- toggle
+- pop
+- scrub
+- typing
+- success
+- notification
+
+Measure each sound effect's actual transient peak.
+
+Align the measured peak—not merely the start of the audio file—to the visual action.
+
+---
+
+IMPLEMENTATION ARCHITECTURE
+
+Create ONE HTML file.
+
+Resolution:
+
+1440 × 1440
+
+The entire animation must be controlled through:
+
+seek(t)
+
+where:
+
+t = animation time in seconds
+
+Every visual property must be derived from "t".
+
+NO:
+
+- CSS transitions
+- setTimeout
+- request-driven state machines
+- persistent animation state
+- frame-to-frame dependency
+
+Given the same time value, "seek(t)" must always produce exactly the same frame.
+
+This is essential for deterministic rendering.
+
+---
+
+RENDERING
+
+Use Playwright to render frames.
+
+Target final output:
+
+60 FPS
+
+For motion blur:
+
+render 4 temporal subframes for every final frame.
+
+Example:
+
+frame t
+
+samples:
+
+t - 1.5Δ
+t - 0.5Δ
+t + 0.5Δ
+t + 1.5Δ
+
+Blend these using FFmpeg "tmix" or equivalent temporal averaging.
+
+The motion blur must remain subtle.
+
+UI must stay sharp enough to read.
+
+---
+
+PREVIEW VALIDATION
+
+Before doing the full render:
+
+render exactly ONE representative frame per beat.
+
+Create a contact sheet or preview sequence.
+
+Inspect:
+
+- beat synchronization
+- spacing
+- typography
+- clipping
+- visual hierarchy
+- cursor placement
+- morph continuity
+- camera framing
+
+If anything is:
+
+- off-grid
+- cramped
+- unreadable
+- awkward
+- visually discontinuous
+
+fix it before the full render.
+
+---
+
+LOOP REQUIREMENT
+
+The animation must loop perfectly.
+
+The final frame must mathematically match the first frame.
+
+Match:
+
+- shape
+- dimensions
+- radius
+- color
+- internal content
+- camera position
+- camera scale
+- cursor position
+- cursor velocity
+- animation velocity
+
+Do not merely make the positions equal.
+
+The velocity around the loop boundary must also feel continuous.
+
+There should be no perceptible stutter when playback restarts.
+
+---
+
+BANNED
+
+Do not use:
+
+- exaggerated bouncy easing
+- particle explosions
+- random decorative particles
+- glow-heavy interfaces
+- gradients on UI chrome
+- inconsistent icon strokes
+- generic template animations
+- excessive glassmorphism
+- meaningless floating objects
+- dead time
+- unnecessary 3D transforms
+- random camera movement
+
+Every movement must communicate state, interaction, or rhythm.
+
+---
+
+DESIGN PRINCIPLE
+
+The viewer should feel like they are watching ONE intelligent interface object continuously transform.
+
+Not:
+
+"a collection of UI animations."
+
+But:
+
+"one object performing a choreographed sequence."
+
+Every transformation must answer:
+
+Why did this object become the next thing?
+
+The cursor, music, interaction, and physical motion should provide that answer.
+
+---
+
+EXECUTION ORDER
+
+Follow this exact workflow:
+
+1. Ask for my UI states, palette, and song.
+2. Create the complete beat grid.
+3. Show me the proposed state sequence.
+4. Identify difficult morph transitions.
+5. Design the spring / interaction strategy.
+6. Only then write the HTML animation.
+7. Render one frame per beat.
+8. Visually inspect the preview.
+9. Correct layout and timing problems.
+10. Render the final 60 FPS video with motion blur.
+11. Verify that the final frame loops seamlessly into the first.
+
+Do not skip directly to implementation.