@plotdb/lotion 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## v0.2.0
+
+ - breaking:
+   - remove audio generators ( `audio/`, `lotion bgm | sfx | mix | beats` ); the commands now only print a notice.
+     they moved to the authoring toolkit `@plotdb/lotitor` ( not public yet )
+   - move `prompt/explainer.md` and `prompt/ui-loop.md` to `@plotdb/lotitor`
+ - features:
+   - `prompt/lotion.md`: how to write a lotion animation, independent of form and style
+     ( split from `prompt/explainer.md` )
+ - tweaks:
+   - cli: when `playwright` is missing, print how to install it instead of a node stack trace
+
+
 ## v0.1.0
 
  - features:

package/README.md

@@ -8,8 +8,11 @@ play, scrub, embed, or render them frame by frame into video.
  - block player ( `dist/block/player.js` ): package an animation as a `@plotdb/block` and embed it anywhere.
  - cli ( `lotion` ): render any page following the render protocol into png frames, contact sheets or mp4,
    and bundle blocks.
- - audio tools ( `audio/` ): beat detection, ui sound effects, a simple bassline bgm synthesizer and a cue mixer.
- - prompts ( `prompt/` ): workflow notes for producing motion designs and explainer animations with an AI agent.
+ - prompt ( `prompt/lotion.md` ): how to write a lotion animation correctly, for people and AI agents.
+
+lotion is self-contained for writing, playing and rendering animations. Authoring aids ( guides for specific forms,
+a style library, asset and audio generation ) are kept in a separate toolkit, `@plotdb/lotitor`, which is not public
+yet; nothing in lotion depends on it.
 
 
 ## Install
@@ -125,7 +128,7 @@ targets under the root ( or use `:scope` ). A block sample is in `web/src/pug/bl
     lotion video  <src> <out.mp4>            render to mp4
     lotion cues   <src> <out.json>           dump window.cues()
     lotion bundle <base-url> <block> <out>   pack a block and its dependencies into one file
-    lotion bgm | sfx | mix | beats ...       audio tools, see below
+    lotion bgm | sfx | mix | beats           removed, see Audio
 
 `<src>` is an http(s) url, or a local html file / directory served by a built-in static server.
 
@@ -143,36 +146,21 @@ options:
 
 ## Audio
 
-Each command forwards its arguments to the python script of the same name in `audio/`; pass `-h` for all options.
-All times are aligned so that `t = 0` matches the start of the animation.
-
- - `lotion bgm out.wav --bpm 120 --bars 16 --key A --scale minor --prog 1,6,3,7 --bass drive --drums four --pad`:
-   synthesize a track around a repeating bassline. bass presets: `pulse`, `octave`, `house`, `drive`, `walk`,
-   or 16 custom steps ( semitones from the chord root, `.` rest, `-` hold ). drum presets: `four`, `half`, `broken`,
-   `none`. `--loop` makes it loop seamlessly; `--grid grid.json` writes its beat grid.
- - `lotion beats music.mp3 --start 64.11 --dur 30 --out grid.json`: estimate bpm and the beat grid
-   ( `{bpm, offset, beats, downbeats}` ). with an off-beat bassline and syncopated kicks the grid may be half a beat
-   off; correct it with `--shift 0.5`.
- - `lotion sfx sfx/`: synthesize ui sound effects ( click, tick, scrub, pop, toggle, success, notify, type, whoosh )
-   and measure each transient peak into `sfx/peaks.json`.
- - `lotion mix cues.json out.wav --dur 30 --music bgm.wav --sfx sfx/ [--loop | --fade 2]`: mix music with sound
-   effects placed at cue times ( `[{t, sfx, gain}]`, e.g. from `lotion cues` ), aligning each effect's measured
-   peak rather than its file start.
-
-A typical flow:
-
-    lotion bgm bgm.wav --bpm 120 --bars 16 --grid grid.json   # time the animation on this grid
-    lotion sfx sfx/
+The audio generators ( `bgm`, `sfx`, `mix`, `beats` ) are no longer part of lotion; `lotion bgm ...` and the like
+only print a notice. Sound stays aligned through cues: the page's `cues()` lists `[{t, ...}]`, `lotion cues` exports
+it, and any audio tool can place sounds at those times. Then add the track to the rendered video:
+
     lotion cues page.html cues.json
-    lotion mix cues.json audio.wav --dur 32 --music bgm.wav --sfx sfx/ --fade 2
     lotion video page.html silent.mp4
     ffmpeg -i silent.mp4 -i audio.wav -c:v copy -c:a aac -shortest out.mp4
 
 
 ## Prompts
 
- - `prompt/ui-loop.md`: a phased workflow for short, looping, single-object UI motion with music.
- - `prompt/explainer.md`: practices for longer explainer animations, embedding them into pages, and common pitfalls.
+ - `prompt/lotion.md`: writing `seek(t)`, embedding into pages, block packaging, and common pitfalls.
+
+Guides for specific forms ( explainers, UI loops ) and for choosing a style moved to the authoring toolkit
+`@plotdb/lotitor` ( not public yet ). `prompt/lotion.md` covers everything needed to write a lotion animation.
 
 
 ## Development

package/cli.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-var fs, path, http, child_process, usage, parse, types, serve, open, shot, frames, sheet, video, cues, bundle, audioDir, audio, argv, ref$, pos, opt, cmd, src, out, rest, times, p, slice$ = [].slice;
+var fs, path, http, child_process, usage, parse, types, serve, playwright, open, shot, frames, sheet, video, cues, bundle, moved, argv, ref$, pos, opt, cmd, src, out, rest, times, p, slice$ = [].slice;
 fs = require('fs');
 path = require('path');
 http = require('http');
 child_process = require('child_process');
-usage = 'usage:\n  lotion <frames|sheet|video|cues> <src> <out> [t...] [options]\n  lotion bundle <base-url> <block-name> <out> [options]\n  lotion <bgm|sfx|mix|beats> ... ( -h for help )\nsee README for options.';
+usage = 'usage:\n  lotion <frames|sheet|video|cues> <src> <out> [t...] [options]\n  lotion bundle <base-url> <block-name> <out> [options]\n  audio generators ( bgm | sfx | mix | beats ) were removed, see README > Audio\nsee README for options.';
 parse = function(argv){
   var ref$, pos, opt, i, a;
   ref$ = [[], {}], pos = ref$[0], opt = ref$[1];
@@ -75,9 +75,22 @@ serve = function(src){
     });
   });
 };
+playwright = function(){
+  var e;
+  try {
+    return require('playwright');
+  } catch (e$) {
+    e = e$;
+    if (e.code !== 'MODULE_NOT_FOUND' || !/playwright/.test(e.message)) {
+      throw e;
+    }
+    console.error('lotion: this command needs playwright, which is not installed. install it with:\n\n    npm i -D playwright\n    npx playwright install chromium');
+    return process.exit(1);
+  }
+};
 open = function(src, opt){
   var chromium, p;
-  chromium = require('playwright').chromium;
+  chromium = playwright().chromium;
   p = /^https?:/.test(src)
     ? Promise.resolve({
       url: src,
@@ -260,7 +273,7 @@ cues = function(src, out, opt){
 };
 bundle = function(base, name, out, opt){
   var chromium, m;
-  chromium = require('playwright').chromium;
+  chromium = playwright().chromium;
   base = base.replace(/\/$/, '');
   m = function(f){
     return require.resolve(f);
@@ -322,37 +335,13 @@ bundle = function(base, name, out, opt){
     });
   });
 };
-audioDir = function(){
-  return [path.join(__dirname, 'audio'), path.join(__dirname, '..', 'audio')].find(function(d){
-    return fs.existsSync(d);
-  });
-};
-audio = function(cmd, args){
-  return new Promise(function(res, rej){
-    var d, f, py;
-    if (!(d = audioDir())) {
-      return rej(new Error("audio scripts not found"));
-    }
-    f = path.join(d, cmd + ".py");
-    py = child_process.spawn(process.env.PYTHON || 'python3', [f].concat(args), {
-      stdio: 'inherit'
-    });
-    py.on('error', rej);
-    return py.on('close', function(c){
-      if (c) {
-        return rej(new Error(cmd + ".py exited with " + c));
-      } else {
-        return res();
-      }
-    });
-  });
+moved = function(cmd){
+  console.error("lotion " + cmd + ": audio generators are no longer part of lotion ( moved to @plotdb/lotitor, not public yet ).\nto align any audio with the animation, export cue times with `lotion cues <src> cues.json`. see README > Audio.");
+  return process.exit(1);
 };
 argv = process.argv.slice(2);
 if ((ref$ = argv[0]) === 'bgm' || ref$ === 'sfx' || ref$ === 'mix' || ref$ === 'beats') {
-  audio(argv[0], argv.slice(1))['catch'](function(e){
-    console.error(e.message);
-    return process.exit(1);
-  });
+  moved(argv[0]);
 } else {
   ref$ = parse(argv), pos = ref$.pos, opt = ref$.opt;
   cmd = pos[0], src = pos[1], out = pos[2], rest = slice$.call(pos, 3);

package/package.json

@@ -1 +1 @@
-{"author":"zbryikt","name":"@plotdb/lotion","version":"0.1.0","description":"deterministic motion toolkit: animation as a pure function of time, with player, frame renderer, block packaging and audio tools","license":"MIT","main":"index.min.js","browser":"index.min.js","bin":{"lotion":"./cli.js"},"homepage":"https://github.com/plotdb/lotion","repository":{"type":"git","url":"git+https://github.com/plotdb/lotion.git"},"scripts":{"start":"npx server -r web -o true"},"engines":{"node":">=14"},"keywords":["motion","animation","video","playwright","block"],"dependencies":{"@plotdb/block":"^5.7.3","@plotdb/csscope":"^5.0.4","@plotdb/rescope":"^5.1.0","@plotdb/semver":"^0.0.4","proxise":"^1.0.1"},"peerDependencies":{"playwright":">=1.40"},"peerDependenciesMeta":{"playwright":{"optional":true}},"devDependencies":{"@plotdb/guides":"github:plotdb/guides","@zbryikt/template":"^2.5.0","fedep":"^1.9.0","livescript":"^1.6.0","playwright":"^1.63.0","stylus":"^0.64.0","uglify-js":"^3.19.3"},"frontendDependencies":{"root":"web/static/assets/lib","modules":[]}}
+{"author":"zbryikt","name":"@plotdb/lotion","version":"0.2.0","description":"deterministic motion toolkit: animation as a pure function of time, with player, frame renderer and block packaging","license":"MIT","main":"index.min.js","browser":"index.min.js","bin":{"lotion":"./cli.js"},"homepage":"https://github.com/plotdb/lotion","repository":{"type":"git","url":"git+https://github.com/plotdb/lotion.git"},"scripts":{"start":"npx server -r web -o true"},"engines":{"node":">=14"},"keywords":["motion","animation","video","playwright","block"],"dependencies":{"@plotdb/block":"^5.7.3","@plotdb/csscope":"^5.0.4","@plotdb/rescope":"^5.1.0","@plotdb/semver":"^0.0.4","proxise":"^1.0.1"},"peerDependencies":{"playwright":">=1.40"},"peerDependenciesMeta":{"playwright":{"optional":true}},"devDependencies":{"@plotdb/guides":"github:plotdb/guides","@zbryikt/template":"^2.5.0","fedep":"^1.9.0","livescript":"^1.6.0","playwright":"^1.63.0","stylus":"^0.64.0","uglify-js":"^3.19.3"},"frontendDependencies":{"root":"web/static/assets/lib","modules":[]}}

package/prompt/{explainer.md → lotion.md}

@@ -1,31 +1,17 @@
-# 解說動畫 ( Explainer ) 的做法
+# 寫 lotion 動畫
 
-`ui-loop.md` 針對的是短、循環、以單一物件變形為主的 UI motion。解說動畫的需求不同：
-較長、要講清楚一個概念、通常不循環、會嵌進網頁也可能輸出成影片。以下是從
-「舒爾茲投票法」解說動畫整理出的做法，可與 `ui-loop.md` 並用。
-
-
-## 流程
-
- 1. 先寫故事線：一句話一個段落 ( chapter )，每段只推進一個概念。
-    概念之間若有缺口 ( 例如要證明「一定有贏家」之前，得先介紹「路徑強度」)，主動補段並告知。
- 2. 準備資料：用真正的函式庫計算，畫面上的數字一律取自計算結果，旁白再依資料撰寫。
-    需要特定性質的資料 ( 例如出現循環、但最後能排出完整順序 ) 時，用程式搜尋，不要手湊。
- 3. 排時間軸：以段落起點加相對時間描述所有事件，方便整段平移或調整長度。
- 4. 實作 `seek(t)`，再用 `lotion sheet` 輸出各段代表畫面檢查版面，修正後再輸出影片。
+所有 lotion 動畫都適用的寫法與陷阱，與動畫的形式、風格無關。
+寫 lotion 動畫只需要這份文件。特定形式 ( 解說片、UI loop ) 的做法、風格庫、素材與音訊生成，
+另有製作工具 `@plotdb/lotitor` ( 目前未公開 )；沒有它不影響這裡的任何內容。
 
 
 ## 原則
 
  - 畫面是時間的純函數：`seek(t)` 只依 `t` 計算，不保留跨影格狀態。
    播放、拖曳、跳段與逐格輸出都只是用不同的 `t` 呼叫它。
- - 元素連續：同一個東西在不同段落中應是同一個元素在移動 ( 票上的數字飛進表格、節點飛上頒獎台 )，
-   而不是淡出後換一個新的。
- - 旁白分兩層：段落標籤 ( 如「第三步 · 兩兩對決」) 與一句旁白。同段的標籤共用一個元素，避免閃爍。
-   旁白進出場用淡入淡出加輕微模糊，舊的出場與新的進場不可重疊在同一位置。
- - 強調只用一種語彙：凸顯 = 加粗變深，其它變淡；錯誤 / 矛盾 = 紅色。避免同時有多種強調方式。
- - 圖的配置要先避開交錯：例如四個節點的完全圖，把「輸給所有人」的節點放在三角形中央即可平面化。
- - 標籤不要壓在連線上：名字預設放右側，遇到連線時個別調整，移動時以彈簧插值切換位置。
+ - `seek` 必須對任何 `t` 都成立，包含 0 與總長之後。
+ - 寫完先用 `lotion sheet` 輸出各段頭、尾、交界與轉場中間點的畫面檢查，再輸出影片。
+ - 音效時間點由頁面的 `cues()` 提供，與畫面共用同一組時間函數，`lotion cues` 可匯出。
 
 
 ## 嵌入網頁時
@@ -42,14 +28,6 @@
    以 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` 宣告，

package/audio/beats.py

@@ -1,93 +0,0 @@
-# 節拍分析: 估計 BPM 與第一拍位置, 輸出節拍格線 ( 整理自 0926-motion 的 bpm / grid / refine ).
-#  python audio/beats.py <music> [--start s] [--dur s] [--min 70] [--max 180] [--out grid.json]
-#  - BPM: onset 包絡的自相關, 同時考慮 1 / 2 / 4 倍拍長, 再以相位一致性細調到 0.005 BPM
-#  - 第一拍: 在一個週期內掃描起點, 取節拍位置上包絡總和最大者 ( 以低頻為主 ); 並補償分析窗的延遲
-#  - 小節起點: 比較 4 個相位上低頻 ( kick ) 的強度, 取最強者
-#  - 限制: bassline 落在反拍、kick 又是切分時, 拍點可能偏半拍; 以 --shift 0.5 ( 單位: 拍 ) 校正
-#  - 輸出: {bpm, offset, beats, downbeats}; 時間皆相對於 --start
-import numpy as np, argparse, json
-from common import load
-
-SR = 22050
-HOP = 256
-FPS = SR / HOP
-
-def frames(x, n=1024):
-  m = (len(x) - n) // HOP
-  return np.lib.stride_tricks.as_strided(x, (m, n), (x.strides[0] * HOP, x.strides[0])) * np.hanning(n)
-
-def onset_env(x):
-  S = np.log1p(100 * np.abs(np.fft.rfft(frames(x), axis=1)))
-  fl = np.maximum(0, np.diff(S, axis=0)).sum(1)
-  fl = fl - np.convolve(fl, np.ones(32) / 32, 'same')
-  return np.maximum(fl, 0)
-
-def low_env(x, cut=150):
-  S = np.abs(np.fft.rfft(frames(x), axis=1))
-  f = np.fft.rfftfreq(1024, 1 / SR)
-  return np.maximum(0, np.diff(np.log1p(100 * S[:, f < cut]).sum(1)))
-
-def coarse_tempo(env, lo, hi):
-  e = env - env.mean()
-  ac = np.correlate(e, e, 'full')[len(e) - 1:]
-  bpms = np.arange(lo, hi + 0.01, 0.1)
-  def score(b):
-    lag, s = 60 * FPS / b, 0
-    for k in (1, 2, 4):
-      L = lag * k; i = int(L); f = L - i
-      if i + 1 < len(ac): s += (ac[i] * (1 - f) + ac[i + 1] * f) / k
-    return s
-  sc = np.array([score(b) for b in bpms])
-  return bpms[sc.argmax()], sc.max() / ac[0]
-
-def fine_tempo(env, b0):
-  t = np.arange(len(env)) / FPS
-  bs = np.arange(b0 - 1, b0 + 1, 0.005)
-  sc = [abs(sum(np.sum(env * np.exp(-2j * np.pi * (b / 60) * k * t)) for k in (1, 2, 4))) for b in bs]
-  return bs[int(np.argmax(sc))]
-
-# 分析窗的延遲: diff 後第 i 個值反映的是第 i + 1 個窗, 窗的中心再晚半個窗長
-LAG = (HOP + 512) / SR
-
-def norm(v): return v / (v.max() + 1e-9)
-
-def grid(x, bpm):
-  env = onset_env(x); low = low_env(x)
-  m = min(len(env), len(low))
-  # 拍點以低頻 ( kick / bass 起音 ) 為主, 避免被反拍的 hat 或 16 分音符拉偏
-  e = norm(low[:m]) * 2 + norm(env[:m])
-  t = np.arange(m) / FPS
-  period = 60 / bpm
-  idx = np.arange(m)
-  def score(o): return np.interp(np.arange(o, t[-1] - 0.1, period) * FPS, idx, e).sum()
-  cands = np.arange(0, period, 0.001)
-  off = cands[int(np.argmax([score(o) for o in cands]))]
-  beats = np.arange(off, t[-1] - 0.1, period)
-  lb = np.interp(beats * FPS, np.arange(len(low)), low)
-  phase = int(np.argmax([lb[i::4].mean() for i in range(4)]))
-  beats = beats + LAG
-  return beats, beats[phase::4]
-
-if __name__ == '__main__':
-  ap = argparse.ArgumentParser(description='estimate bpm and beat grid of a music file')
-  ap.add_argument('music')
-  ap.add_argument('--start', type=float, default=0)
-  ap.add_argument('--dur', type=float, default=None)
-  ap.add_argument('--min', type=float, default=70)
-  ap.add_argument('--max', type=float, default=180)
-  ap.add_argument('--out', default=None, help='write grid json here')
-  ap.add_argument('--shift', type=float, default=0, help='shift the grid by this many beats')
-  a = ap.parse_args()
-  x = load(a.music, sr=SR, start=a.start, dur=a.dur)
-  b0, conf = coarse_tempo(onset_env(x), a.min, a.max)
-  bpm = fine_tempo(onset_env(x), b0)
-  beats, downbeats = grid(x, bpm)
-  if a.shift:
-    d = a.shift * 60 / bpm
-    beats, downbeats = beats + d, downbeats + d
-  print('bpm %.3f ( coarse %.1f, confidence %.2f )  first beat %.4fs  first downbeat %.4fs  beats %d'
-    % (bpm, b0, conf, beats[0], downbeats[0], len(beats)))
-  if a.out:
-    json.dump({'bpm': round(float(bpm), 3), 'offset': round(float(beats[0]), 4),
-      'beats': [round(float(v), 4) for v in beats], 'downbeats': [round(float(v), 4) for v in downbeats]},
-      open(a.out, 'w'), indent=1)

package/audio/bgm.py

@@ -1,181 +0,0 @@
-# 簡易背景音樂合成: 以重複的 bassline 為骨幹, 加上鼓組與和弦墊音. 只依賴 numpy.
-#  python audio/bgm.py <out.wav> [--bpm 120] [--bars 16] [--key A] [--scale minor] [--prog 1,6,3,7]
-#                      [--bass pulse] [--drums four] [--pad] [--intro 2] [--outro 2] [--loop] [--grid grid.json]
-#
-#  設計:
-#  - 和弦進行以音階級數表示 ( --prog 1,6,3,7 ), 每小節一個和弦, 循環使用
-#  - bassline 是一小節 16 格的樣式 ( --bass ), 每格為相對於和弦根音的半音數, '.' 為休止; 每小節重複, 隨和弦移調
-#  - 鼓組樣式 ( --drums ): kick / hat / clap 各 16 格
-#  - 編排: 前 --intro 小節只有 bass 與 hat, 最後 --outro 小節逐漸收掉; --loop 時不做 intro / outro,
-#    並把超出尾端的音尾繞回開頭, 可無縫循環
-#  - t = 0 即第一小節的第一拍, 方便與動畫時間軸對齊; --grid 會輸出節拍格線 ( 與 beats.py 格式相同 )
-import numpy as np, argparse, json
-from common import SR, write, normalize
-
-NOTE = {'C': 0, 'C#': 1, 'Db': 1, 'D': 2, 'D#': 3, 'Eb': 3, 'E': 4, 'F': 5, 'F#': 6, 'Gb': 6,
-  'G': 7, 'G#': 8, 'Ab': 8, 'A': 9, 'A#': 10, 'Bb': 10, 'B': 11}
-SCALE = {
-  'major': [0, 2, 4, 5, 7, 9, 11], 'minor': [0, 2, 3, 5, 7, 8, 10],
-  'dorian': [0, 2, 3, 5, 7, 9, 10], 'mixolydian': [0, 2, 4, 5, 7, 9, 10]
-}
-# bassline 樣式: 16 格, 數字為相對和弦根音的半音數, '.' 休止, '-' 延續前一音
-BASS = {
-  'pulse':  '0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0',
-  'octave': '0 . 12 . 0 . 12 . 0 . 12 . 0 . 12 .',
-  'house':  '. . 0 . . . 0 . . . 0 . . . 0 12',
-  'drive':  '0 . 0 12 . 0 7 . 0 . 0 12 . 7 5 .',
-  'walk':   '0 - - - 7 - - - 12 - - - 7 - 5 -',
-}
-DRUMS = {
-  'four':   {'kick': 'x...x...x...x...', 'hat': '..x...x...x...x.', 'clap': '....x.......x...'},
-  'half':   {'kick': 'x.......x.......', 'hat': 'x.x.x.x.x.x.x.x.', 'clap': '........x.......'},
-  'broken': {'kick': 'x.....x...x.....', 'hat': '..x...x...x...xx', 'clap': '....x.......x..x'},
-  'none':   {'kick': '................', 'hat': '................', 'clap': '................'},
-}
-
-rng = np.random.default_rng(3)
-
-def hz(midi): return 440 * 2 ** ((midi - 69) / 12)
-
-def env(n, a, d, sustain=0.0, r=0.0):
-  """attack / 指數衰減至 sustain; 結尾 r 秒線性釋放"""
-  t = np.arange(n) / SR
-  e = (1 - np.exp(-t / max(a, 1e-4))) * (sustain + (1 - sustain) * np.exp(-t / d))
-  if r > 0:
-    k = min(n, int(r * SR)); e[n - k:] *= np.linspace(1, 0, k)
-  return e
-
-def saw(f, n, detune=0.0):
-  t = np.arange(n) / SR
-  x = 2 * ((f * t) % 1) - 1
-  if detune: x = 0.5 * x + 0.5 * (2 * ((f * (1 + detune) * t + 0.37) % 1) - 1)
-  return x
-
-def lowpass(x, cutoff, q=0.9):
-  """時變截止頻率的 state variable filter. cutoff 可為陣列 ( 每個 sample 一個值 )"""
-  cutoff = np.broadcast_to(cutoff, x.shape)
-  f = 2 * np.sin(np.pi * np.clip(cutoff, 20, SR / 6) / SR)
-  low = band = 0.0
-  y = np.empty_like(x)
-  damp = 1 / q
-  for i in range(len(x)):
-    low += f[i] * band
-    high = x[i] - low - damp * band
-    band += f[i] * high
-    y[i] = low
-  return y
-
-def bass_note(midi, dur, accent=1.0):
-  n = int(dur * SR)
-  x = saw(hz(midi), n, detune=0.004) + 0.5 * np.sin(2 * np.pi * hz(midi - 12) * np.arange(n) / SR)
-  cut = 180 + 1400 * accent * np.exp(-np.arange(n) / SR / 0.09)
-  return lowpass(x, cut, q=1.4) * env(n, 0.003, 0.25, 0.55, 0.02) * 0.5
-
-def kick():
-  n = int(0.35 * SR); t = np.arange(n) / SR
-  f = 48 + 110 * np.exp(-t / 0.035)
-  return np.sin(2 * np.pi * np.cumsum(f) / SR) * env(n, 0.001, 0.16) * 0.95
-
-def noise_hp(n, cut):
-  X = np.fft.rfft(rng.standard_normal(n)); fq = np.fft.rfftfreq(n, 1 / SR)
-  X[fq < cut] = 0
-  y = np.fft.irfft(X, n); return y / (np.abs(y).max() + 1e-9)
-
-def hat(open_=False):
-  n = int((0.18 if open_ else 0.05) * SR)
-  return noise_hp(n, 7000) * env(n, 0.0005, 0.06 if open_ else 0.012) * 0.22
-
-def clap():
-  n = int(0.22 * SR)
-  x = noise_hp(n, 1200) * env(n, 0.001, 0.06)
-  for d in (0.011, 0.022):  # 拍手的多重起音
-    k = int(d * SR); x[k:] += noise_hp(n - k, 1200) * env(n - k, 0.001, 0.012) * 0.6
-  return x * 0.28
-
-def pad_chord(midis, dur):
-  n = int(dur * SR)
-  x = sum(saw(hz(m), n, detune=0.006) for m in midis) / len(midis)
-  return lowpass(x, 900, q=0.7) * env(n, 0.35, 10, 0.9, 0.4) * 0.16
-
-def parse_steps(s):
-  tok = s.split() if ' ' in s.strip() else list(s)
-  if len(tok) != 16: raise SystemExit('pattern must have 16 steps: %r' % s)
-  return tok
-
-if __name__ == '__main__':
-  ap = argparse.ArgumentParser(description='synthesize a simple looping bassline track')
-  ap.add_argument('out')
-  ap.add_argument('--bpm', type=float, default=120)
-  ap.add_argument('--bars', type=int, default=16)
-  ap.add_argument('--key', default='A', help='tonic, e.g. A, C#, Eb')
-  ap.add_argument('--octave', type=int, default=2, help='octave of the bass tonic')
-  ap.add_argument('--scale', default='minor', choices=list(SCALE))
-  ap.add_argument('--prog', default='1,6,3,7', help='chord degrees, one per bar, cycled')
-  ap.add_argument('--bass', default='drive', help='preset (%s) or 16 custom steps' % ', '.join(BASS))
-  ap.add_argument('--drums', default='four', choices=list(DRUMS))
-  ap.add_argument('--pad', action='store_true', help='add sustained chord pad')
-  ap.add_argument('--intro', type=int, default=2, help='bars with bass and hat only')
-  ap.add_argument('--outro', type=int, default=2, help='bars fading out at the end')
-  ap.add_argument('--loop', action='store_true', help='seamless loop: no intro / outro, tails wrap around')
-  ap.add_argument('--swing', type=float, default=0, help='0 ~ 0.3, delays every second 16th')
-  ap.add_argument('--grid', default=None, help='write beat grid json here')
-  a = ap.parse_args()
-
-  scale = SCALE[a.scale]
-  tonic = 12 * (a.octave + 1) + NOTE[a.key]
-  prog = [int(v) for v in a.prog.split(',')]
-  bass = parse_steps(BASS.get(a.bass, a.bass))
-  drums = {k: parse_steps(v) for k, v in DRUMS[a.drums].items()}
-  intro, outro = (0, 0) if a.loop else (a.intro, a.outro)
-
-  step = 60 / a.bpm / 4
-  total = a.bars * 16 * step
-  n = int(round(total * SR))
-  out = np.zeros((n + int(SR * 2), 2), np.float32)  # 多留 2 秒放音尾
-
-  def place(x, t, gain=1.0, pan=0.0):
-    s = int(round(t * SR)); e = s + len(x)
-    l, r = np.cos((pan + 1) * np.pi / 4), np.sin((pan + 1) * np.pi / 4)
-    out[s:e, 0] += x * gain * l * 1.414
-    out[s:e, 1] += x * gain * r * 1.414
-
-  def degree(d, shift=0):
-    i = d - 1 + shift
-    return scale[i % 7] + 12 * (i // 7)
-
-  K, C = kick(), clap()
-  for bar in range(a.bars):
-    root = tonic + degree(prog[bar % len(prog)])
-    t0 = bar * 16 * step
-    # 編排: intro 只有 bass + hat; outro 逐小節降低音量
-    level = 1.0 if bar < a.bars - outro else (a.bars - bar) / (outro + 1)
-    full = bar >= intro
-    if a.pad and full:
-      d = prog[bar % len(prog)]
-      chord = [tonic + 12 + degree(d), tonic + 12 + degree(d, 2), tonic + 12 + degree(d, 4)]
-      place(pad_chord(chord, 16 * step), t0, level)
-    for i in range(16):
-      t = t0 + i * step + (a.swing * step if i % 2 else 0)
-      s = bass[i]
-      if s not in ('.', '-'):
-        length = 1
-        while i + length < 16 and bass[i + length] == '-': length += 1
-        place(bass_note(root + int(s), length * step * 0.92, 1.0 if i % 4 == 0 else 0.6), t, level)
-      if full and drums['kick'][i] == 'x': place(K, t, level)
-      if full and drums['clap'][i] == 'x': place(C, t, level * 0.9, 0.15)
-      if drums['hat'][i] == 'x': place(hat(), t, level * (1 if full else 0.7), -0.25)
-
-  if a.loop:
-    tail = out[n:].copy()
-    out = out[:n]
-    k = min(len(tail), n)
-    out[:k] += tail[:k]
-  else:
-    tail = int(SR * 1.5)
-    out = out[:n + tail]
-    out[n:] *= np.linspace(1, 0, tail)[:, None]
-  write(a.out, normalize(out * 0.9, 0.95))
-  beats = [round(i * 4 * step, 4) for i in range(a.bars * 4)]
-  print('%s  %.1f bpm  %d bars  %.2fs  key %s %s  prog %s' % (a.out, a.bpm, a.bars, total, a.key, a.scale, a.prog))
-  if a.grid:
-    json.dump({'bpm': a.bpm, 'offset': 0, 'beats': beats, 'downbeats': beats[::4]}, open(a.grid, 'w'), indent=1)

package/audio/common.py

@@ -1,30 +0,0 @@
-# 音訊工具共用: 讀檔 ( 經 ffmpeg ) 與寫 wav. 只依賴 numpy.
-import numpy as np, subprocess, wave
-
-SR = 48000
-
-def load(path, sr=SR, start=0, dur=None, channels=1):
-  """以 ffmpeg 解碼任意音訊檔, 回傳 float32 陣列 ( channels > 1 時為 (n, channels) )"""
-  cmd = ['ffmpeg', '-v', 'quiet', '-ss', str(start)] + (['-t', str(dur)] if dur else []) + \
-    ['-i', path, '-ac', str(channels), '-ar', str(sr), '-f', 'f32le', '-']
-  x = np.frombuffer(subprocess.run(cmd, capture_output=True, check=True).stdout, dtype=np.float32)
-  return x.reshape(-1, channels).copy() if channels > 1 else x.copy()
-
-def write(path, x, sr=SR):
-  """寫入 16-bit wav. x 為 (n,) 或 (n, channels), 數值範圍 -1 ~ 1"""
-  x = np.clip(np.asarray(x, dtype=np.float32), -1, 1)
-  ch = 1 if x.ndim == 1 else x.shape[1]
-  with wave.open(path, 'wb') as w:
-    w.setnchannels(ch); w.setsampwidth(2); w.setframerate(sr)
-    w.writeframes((x * 32767).astype('<i2').tobytes())
-
-def read_wav(path):
-  """讀取 16-bit wav, 回傳 (資料, sr). 多聲道時為 (n, channels)"""
-  with wave.open(path) as w:
-    ch, sr = w.getnchannels(), w.getframerate()
-    x = np.frombuffer(w.readframes(w.getnframes()), '<i2').astype(np.float32) / 32767
-  return (x.reshape(-1, ch) if ch > 1 else x), sr
-
-def normalize(x, peak=0.98):
-  m = np.abs(x).max()
-  return x * (peak / m) if m > peak else x

package/audio/mix.py

@@ -1,51 +0,0 @@
-# 混音: 背景音樂 + 依 cue 放置的音效 ( 整理自 0926-motion ).
-#  python audio/mix.py <cues.json> <out.wav> --dur s [--music f] [--start s] [--sfx dir] [--fade s] [--loop]
-#  - cues.json: [{t, sfx, gain?}, ...], 通常由 `lotion cues` 從頁面匯出
-#  - 音效以 sfx 目錄裡 peaks.json 量到的 transient peak 對齊 cue 時間, 而非檔案開頭 ( 見 sfx.py )
-#  - --music: 任意音訊檔 ( 例如 bgm.py 的輸出 ); --start 為音樂中對齊 t = 0 的位置
-#  - --loop: 超出尾端的音效回繞到開頭, 音訊可無縫循環; 否則尾端以 --fade 秒淡出
-import numpy as np, json, os, argparse
-from common import SR, load, read_wav, write, normalize
-
-ap = argparse.ArgumentParser(description='mix background music and cue-aligned sound effects')
-ap.add_argument('cues')
-ap.add_argument('out')
-ap.add_argument('--dur', type=float, required=True, help='length of the output in seconds')
-ap.add_argument('--music', default=None)
-ap.add_argument('--start', type=float, default=0, help='position in music aligned to t = 0')
-ap.add_argument('--sfx', default='sfx', help='directory of sfx wav files and peaks.json')
-ap.add_argument('--fade', type=float, default=0)
-ap.add_argument('--loop', action='store_true')
-ap.add_argument('--sfx-gain', type=float, default=0.55)
-ap.add_argument('--music-gain', type=float, default=0.8)
-a = ap.parse_args()
-
-n = int(SR * a.dur)
-mix = np.zeros((n, 2), np.float32)
-if a.music:
-  music = load(a.music, start=a.start, dur=a.dur, channels=2)[:n]
-  mix[:len(music)] = music * a.music_gain
-
-cues = json.load(open(a.cues))
-peaks = json.load(open(os.path.join(a.sfx, 'peaks.json'))) if cues else {}
-cache = {}
-for c in cues:
-  name = c['sfx']
-  if name not in cache:
-    x, _ = read_wav(os.path.join(a.sfx, name + '.wav'))
-    cache[name] = x if x.ndim == 1 else x.mean(1)
-  x = cache[name] * c.get('gain', 1) * a.sfx_gain
-  s = int(round((c['t'] - peaks.get(name, 0)) * SR))
-  idx = s + np.arange(len(x))
-  if a.loop: idx %= n
-  else:
-    m = (idx >= 0) & (idx < n); idx, x = idx[m], x[m]
-  np.add.at(mix[:, 0], idx, x)
-  np.add.at(mix[:, 1], idx, x)
-
-if a.fade > 0 and not a.loop:
-  f = int(SR * a.fade)
-  mix[n - f:] *= np.linspace(1, 0, f)[:, None]
-pk = float(np.abs(mix).max())
-write(a.out, normalize(mix))
-print('%s  cues %d  peak %.3f' % (a.out, len(cues), pk))

package/audio/sfx.py

@@ -1,93 +0,0 @@
-# UI 音效合成 ( 整理自 0926-motion ). 輸出 <outdir>/*.wav, 並量測每個檔的 transient peak 寫入 <outdir>/peaks.json
-#  python audio/sfx.py <outdir> [--list]
-#  peak 定義: 3ms RMS 包絡第一次達到全域最大 80% 的位置
-#   - 多音符音效 ( chime / toggle ) 取第一個音的擊點, 而非較晚但較響的音
-#   - 混音時以 peak 而非檔案開頭對齊 cue 時間 ( 見 mix.py )
-import numpy as np, json, os, argparse
-from common import SR, write
-
-rng = np.random.default_rng(7)
-
-def t_(dur): return np.arange(int(SR * dur)) / SR
-def env(t, a, d): return (1 - np.exp(-t / max(a, 1e-4))) * np.exp(-t / d)
-def bandnoise(n, lo, hi):
-  x = rng.standard_normal(n)
-  X = np.fft.rfft(x); f = np.fft.rfftfreq(n, 1 / SR)
-  X[(f < lo) | (f > hi)] = 0
-  y = np.fft.irfft(X, n); return y / (np.abs(y).max() + 1e-9)
-def sine(t, f, ph=0): return np.sin(2 * np.pi * f * t + ph)
-def pad(x, pre=0.0, post=0.0): return np.concatenate([np.zeros(int(SR * pre)), x, np.zeros(int(SR * post))])
-
-def click():
-  t = t_(0.06)
-  body = sine(t, 1850) * env(t, 0.0004, 0.006) * 0.7 + sine(t, 520) * env(t, 0.0008, 0.012) * 0.5
-  return body + bandnoise(len(t), 2500, 9000) * env(t, 0.0002, 0.003) * 0.5
-
-def tick():
-  t = t_(0.03)
-  return sine(t, 3400) * env(t, 0.0003, 0.004) * 0.6 + bandnoise(len(t), 4000, 12000) * env(t, 0.0002, 0.0015) * 0.3
-
-def scrub():
-  t = t_(0.015)
-  return bandnoise(len(t), 5000, 12000) * env(t, 0.0002, 0.0012) * 0.5
-
-def pop():
-  t = t_(0.14)
-  f = 380 + 520 * np.exp(-t / 0.018)
-  return np.sin(2 * np.pi * np.cumsum(f) / SR) * env(t, 0.001, 0.035) * 0.9
-
-def toggle():
-  a = click() * 0.6
-  t = t_(0.05)
-  b = sine(t, 2600) * env(t, 0.0004, 0.005) * 0.6 + sine(t, 780) * env(t, 0.0006, 0.01) * 0.4
-  out = np.zeros(int(SR * 0.12)); out[:len(a)] += a
-  o = int(SR * 0.028); out[o:o + len(b)] += b
-  return out
-
-def chime(notes, gap, dur=0.5):
-  out = np.zeros(int(SR * (gap * len(notes) + dur)))
-  for i, f in enumerate(notes):
-    t = t_(dur)
-    x = (sine(t, f) + 0.25 * sine(t, f * 2.01) + 0.08 * sine(t, f * 3.02)) * env(t, 0.002, 0.16)
-    o = int(SR * gap * i); out[o:o + len(x)] += x * (0.8 if i == 0 else 0.65)
-  return out * 0.45
-
-def success(): return chime([1318.5, 1975.5], 0.07)
-def notify(): return chime([1567.98, 2093.0, 2637.0], 0.06, 0.45)
-
-def typing():
-  t = t_(0.05)
-  return bandnoise(len(t), 1200, 6000) * env(t, 0.0003, 0.005) * 0.55 + sine(t, 210) * env(t, 0.001, 0.01) * 0.35
-
-def whoosh():
-  t = t_(0.32)
-  n = bandnoise(len(t), 300, 4000)
-  e = np.sin(np.pi * np.clip(t / 0.32, 0, 1)) ** 2.5
-  return n * e * 0.18
-
-SFX = dict(click=click, tick=tick, scrub=scrub, pop=pop, toggle=toggle, success=success, notify=notify,
-  type=typing, whoosh=whoosh)
-
-def peak(x):
-  win = int(SR * 0.003)
-  e = np.sqrt(np.convolve(x * x, np.ones(win) / win, 'same'))
-  i = int(np.argmax(e >= 0.8 * e.max()))
-  # 往後找到該段的局部最大
-  while i + 1 < len(e) and e[i + 1] >= e[i]: i += 1
-  return i
-
-if __name__ == '__main__':
-  ap = argparse.ArgumentParser(description='synthesize ui sound effects')
-  ap.add_argument('outdir')
-  ap.add_argument('--list', action='store_true', help='only list available effects')
-  a = ap.parse_args()
-  if a.list:
-    print(' '.join(SFX)); raise SystemExit
-  os.makedirs(a.outdir, exist_ok=True)
-  peaks = {}
-  for name, fn in SFX.items():
-    x = pad(fn(), 0.005, 0.02)
-    write(os.path.join(a.outdir, name + '.wav'), x)
-    peaks[name] = round(peak(x) / SR, 5)
-  json.dump(peaks, open(os.path.join(a.outdir, 'peaks.json'), 'w'), indent=1)
-  print(json.dumps(peaks, indent=1))

package/prompt/ui-loop.md

@@ -1,497 +0,0 @@
-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.