@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/motion-video-maker/reference/components.md

@@ -0,0 +1,451 @@
+# Component Reference
+
+Detailed prop tables and authoring notes for every built-in animation
+component. The runtime (`runtime/components.js`) is fully introspectable;
+extend it with `window.__mvm.register('your-anim', fn)`.
+
+---
+
+## Text Animations (`[data-text-animation]`)
+
+All text components receive their progress from the global timeline; no
+JavaScript is needed in author HTML. They share these common attributes:
+
+- `data-start` — when the animation begins (seconds).
+- `data-anim-duration` — animation length (overrides `data-duration`).
+- `data-easing` — see SKILL.md easing list (default varies per component).
+
+### split-text
+
+Per-character (or per-word) staggered enter with optional translate.
+
+| Attribute | Default | Notes |
+|---|---|---|
+| `data-stagger` | `0.04` | Delay between characters in seconds |
+| `data-char-duration` | `0.7` | Per-character animation length |
+| `data-split-mode` | `char` | `char` or `word` |
+| `data-travel` | `50` | Y-translate distance (px) |
+| `data-easing` | `easeOutQuart` | Per-char easing |
+
+When the parent uses gradient text (`-webkit-text-fill-color: transparent`
+with a `background-image: linear-gradient(...)`), the splitter automatically
+copies the gradient onto each character span — so `text-fire`, `text-gold`,
+`text-aurora`, `text-silver` all combine seamlessly with `split-text`.
+
+### blur-text
+
+Per-character blur → focus with subtle translate.
+
+| Attribute | Default |
+|---|---|
+| `data-stagger` | `0.06` |
+| `data-char-duration` | `0.9` |
+| `data-split-mode` | `char` |
+
+### shiny-text
+
+Sweeping metallic highlight across the text.
+
+| Attribute | Default |
+|---|---|
+| `data-speed` | `3` | Higher = faster sweep |
+
+The text becomes transparent with a `linear-gradient` background; works on
+any plain text.
+
+### gradient-text
+
+Animated color-shift gradient.
+
+| Attribute | Default |
+|---|---|
+| `data-colors` | `'#ff7e5f,#feb47b,...'` | Comma-separated colors |
+| `data-speed` | `0.6` | Cycles per second |
+
+### glitch-text
+
+RGB split and jitter, deterministic.
+
+| Attribute | Default |
+|---|---|
+| `data-intensity` | `4` | RGB-split distance (px) |
+
+### decrypted-text
+
+Hacker-style character scramble that progressively settles into the target
+string from left to right.
+
+| Attribute | Default |
+|---|---|
+| `data-anim-duration` | `2.5` | How long the decryption takes |
+
+The internal glyph alphabet covers ASCII symbols, katakana, and selected
+CJK glyphs (`漢字文测试时间永恒`), so the scramble looks visually rich for
+Chinese text too.
+
+### type-text
+
+Typewriter effect with blinking cursor.
+
+| Attribute | Default |
+|---|---|
+| `data-cps` | `14` | Characters per second |
+
+### rotating-text
+
+Cycle through phrases.
+
+| Attribute | Default |
+|---|---|
+| `data-phrases` | _required_ | Pipe-separated list `phrase1\|phrase2\|...` |
+| `data-each` | `1.5` | Seconds per phrase |
+
+Embed inside a containing element with a fixed `min-width` so the layout
+doesn't jump as phrases change length.
+
+### mask-text
+
+Whole-element clip-path reveal — the text wipes in along an axis.
+
+| Attribute | Default | Notes |
+|---|---|---|
+| `data-mask-from` | `left` | `left` / `right` / `top` / `bottom` / `center` |
+| `data-anim-duration` | `1.0` | |
+| `data-easing` | `easeInOutQuart` | |
+
+> **Important:** `mask-text` uses CSS `clip-path: inset(...)`.  In
+> Chromium (including headless), `clip-path` interacts poorly with
+> `-webkit-text-fill-color: transparent` + `background-clip: text` — the
+> gradient fill is hidden under the clip.  Use `mask-text` only on
+> solid-color text, OR fall back to `split-text` for gradient titles.
+
+### wave-text
+
+Per-character vertical sine wave. Characters animate in by riding the
+wave crest, then continue with a gentle sustained oscillation.
+
+| Attribute | Default | Notes |
+|---|---|---|
+| `data-stagger` | `0.04` | |
+| `data-char-duration` | `0.6` | |
+| `data-amplitude` | `40` | Peak Y travel (px) |
+| `data-wave` | `1.2` | Wave frequency |
+| `data-easing` | `easeOutQuart` | |
+
+Great for poetic phrases, marketing taglines, motion-graphics quotes.
+
+### scramble-text
+
+Like `shuffle-text` but with a wider symbol palette
+(`!@#$%&*+={}[]\|01101001`) and a sharper left-to-right resolve.  Use
+for technical labels (`init_payload()`, `cargo run --release`,
+`hash:0xdeadbeef`).
+
+| Attribute | Default |
+|---|---|
+| `data-anim-duration` | `1.6` |
+
+### count-up
+
+Animated numeric counter with formatting.
+
+| Attribute | Default | Notes |
+|---|---|---|
+| `data-from` | `0` | Start value |
+| `data-to` | `100` | End value |
+| `data-anim-duration` | `2` | Counter duration |
+| `data-decimals` | `0` | Decimal places (text mode only) |
+| `data-prefix` | `''` | Prepended string (`$`, `~`, etc.) |
+| `data-suffix` | `''` | Appended string (`%`, `x`, ...) |
+| `data-separator` | `''` | Thousands separator (`','`, `' '`) — works in both modes |
+| `data-easing` | `easeOutCubic` | |
+| `data-odometer` | `false` | When `true`, renders one DOM column per digit so each digit can flip mechanically as it carries (perspective + opacity dip when `sub-digit > 0.82`).  Use a solid color — gradient-text classes won't propagate through the inner per-digit divs. |
+
+### shuffle-text
+
+Reveals the target string from left to right, scrambling unset characters.
+
+| Attribute | Default |
+|---|---|
+| `data-anim-duration` | `1.4` |
+
+---
+
+## Backgrounds (`[data-background]`)
+
+Each background mounts a `<canvas>` and re-renders on every `mvm-seek`
+event. Performance scales with stage resolution; for 4K you may want to
+reduce `data-count` parameters by ~50%.
+
+### aurora
+
+Soft moving radial gradients combined with lighter blending.
+
+| Attribute | Default |
+|---|---|
+| `data-colors` | `'#3a1c71,#d76d77,#ffaf7b,#3a1c71'` | Comma-separated |
+
+### particles
+
+Deterministic drifting field of glowing dots.
+
+| Attribute | Default |
+|---|---|
+| `data-count` | `90` | Number of particles |
+| `data-color` | `'rgba(255,255,255,0.9)'` | Particle fill |
+| `data-size` | `2.2` | Base radius multiplier |
+| `data-seed` | `1337` | PRNG seed for reproducibility |
+
+### starfield
+
+Galaxy-style parallax stars warping outward from the screen center.
+
+| Attribute | Default |
+|---|---|
+| `data-count` | `240` |
+| `data-speed` | `0.6` |
+| `data-seed` | `7331` |
+| `data-bg` | `'rgba(5,7,18,0.4)'` | Per-frame background tint |
+
+### threads
+
+Sinusoidal lines forming a fabric-like texture.
+
+| Attribute | Default |
+|---|---|
+| `data-lines` | `60` |
+| `data-color` | `'rgba(180,200,255,0.18)'` |
+| `data-bg` | `'#0a0a14'` |
+
+### waves
+
+Three stacked sinusoidal layers in different colors.
+
+| Attribute | Default |
+|---|---|
+| `data-colors` | `'#7F7FD5,#86A8E7,#91EAE4'` |
+| `data-bg` | `'#070716'` |
+
+### dot-grid
+
+Pulsing dots forming concentric ripples.
+
+| Attribute | Default |
+|---|---|
+| `data-gap` | `28` | Pixels between dot centers |
+| `data-color` | `'#5b86e5'` | |
+| `data-bg` | `'#0a0c14'` | |
+
+### hyperspeed
+
+Radial speed-line streaks like a Star Wars jump.
+
+| Attribute | Default |
+|---|---|
+| `data-count` | `220` |
+| `data-colors` | `'#ffffff,#ffd8a8,#ffe2b3'` |
+| `data-seed` | `9001` |
+
+### letter-glitch
+
+Matrix-style scrolling glyph cells.
+
+| Attribute | Default |
+|---|---|
+| `data-cell` | `22` | Cell size in px |
+| `data-colors` | `'#00ff9c,#2af598,#009efd,#5b86e5'` |
+| `data-bg` | `'#04060a'` |
+
+### noise
+
+Film-grain overlay; use `mix-blend-mode: overlay` and a low opacity (~0.2).
+
+| Attribute | Default |
+|---|---|
+| `data-strength` | `18` | Noise amplitude |
+
+### magnet-lines
+
+A grid of short line segments that align with a time-varying vector field
+produced by multiple orbiting "magnetic poles".  Great for systems /
+architecture scenes, or as a subtle decoration that suggests "structure".
+
+| Attribute | Default |
+|---|---|
+| `data-gap` | `60` | Grid cell size (px) |
+| `data-length` | `26` | Line length (px) |
+| `data-colors` | `'#5BC0EB,#9d8df1'` | Comma-separated palette cycled per cell |
+| `data-poles` | `3` | Number of moving attractors |
+| `data-bg` | `'#0a0a14'` | |
+
+### ribbons
+
+N parametric flowing ribbons painted with multiple stroke widths to build
+a glow.  Each ribbon is a smooth multi-harmonic sine path animated over
+time.  Nice for music / hype intros.
+
+| Attribute | Default |
+|---|---|
+| `data-count` | `5` | Number of ribbons |
+| `data-colors` | `'#FF6363,#5BC0EB,#9d8df1,#FFD400,#2af598'` | One color per ribbon (cycled) |
+| `data-bg` | `'#08081a'` | |
+
+### WebGL shader backgrounds
+
+These are mounted from `runtime/shaders.js` (must be loaded after
+`components.js`).  All six accept `data-colors` as 4 hex stops, plus
+`data-intensity`, `data-scale`, `data-seed`.
+
+| `data-background` | Notes |
+|---|---|
+| `liquid-ether` | Domain-warped fbm fluid with iridescent rim. |
+| `iridescence` | Curved rainbow interference bands radiating from a moving focal point. |
+| `prismatic-burst` | Center-radiating volumetric light with chromatic split. |
+| `lightning` | Procedural lightning bolts with flicker + bloom. |
+| `plasma` | Classic organic plasma noise turbulence. |
+| `beams` | Crossing rotating light beams + hot spot. |
+| `meta-balls` | N orbiting isosurface meta-balls with gradient interior + chromatic edge highlight. |
+
+---
+
+## Effects (`[data-fx]`)
+
+### clock
+
+Analog clock with hour, minute, second hands.
+
+| Attribute | Default |
+|---|---|
+| `data-speed` | `1` | Time multiplier (`60` = 1 sec real ≈ 1 minute of clock motion) |
+
+Use a square container so the clock face stays circular.
+
+---
+
+## Element-level effects (`[data-effect]`)
+
+Decorations that attach to **an existing host element** and animate around
+it.  They overlay a `<canvas>` inside the host (which is auto-set to
+`position: relative` if it isn't already) — so they coexist with the
+element's own `data-animation` / `data-text-animation`.
+
+### electric-border
+
+Three RGB-shifted noise-perturbed arcs flow around the host's rounded
+perimeter.  Renders 4 stacked stroke widths per arc to build a glow.
+
+| Attribute | Default | Notes |
+|---|---|---|
+| `data-color` | `#FF6363` | Arc 1 (R) |
+| `data-color2` | `#FFD400` | Arc 2 (G) |
+| `data-color3` | `#5BC0EB` | Arc 3 (B) |
+| `data-intensity` | `1.0` | Arc displacement amplitude multiplier |
+| `data-speed` | `1.5` | How fast arcs slide around (cycles/sec) |
+| `data-padding` | `24` | Outset padding (px) — bigger gives more glow room |
+| `data-border-radius` | `18` (or host CSS) | Corner radius of the perimeter path |
+
+### star-border
+
+N small 4-point stars orbit the host's perimeter with comet-like trails.
+
+| Attribute | Default | Notes |
+|---|---|---|
+| `data-color` | `#FFFFFF` | Star color (single hex) |
+| `data-count` | `6` | Number of orbiting stars |
+| `data-tail` | `14` | Trail sample count behind each star |
+| `data-speed` | `0.25` | Orbit speed (revolutions/sec) |
+| `data-size` | `4` | Star radius (px) — glow scales 5× |
+| `data-padding` | `30` | Outset padding (px) |
+
+### image-trail
+
+While the host's `data-clip` is in its **in-animation window** (defined by
+`data-start` + `data-in-duration`), draws N ghost copies positioned at
+progressively-earlier points in the same animation.  Each ghost has its
+opacity multiplied by `decay^(i+1)` so the trail fades cleanly.
+
+| Attribute | Default | Notes |
+|---|---|---|
+| `data-trail-count` | `5` | Number of ghosts |
+| `data-trail-stride` | `0.06` | Time offset between successive ghosts (sec) |
+| `data-trail-decay` | `0.55` | Opacity multiplier per ghost index (geometric) |
+
+The ghost reuses the host's `data-animation` (or `data-animation-in`) name
+to compute its style — so trails work with `fadeInLeft`, `pop`, `slideUp`,
+etc.  Ghosts are inserted as siblings **before** the host in DOM order, so
+the main element stays on top.
+
+---
+
+## Outer Animations (`[data-animation]`)
+
+Available presets for `data-animation` / `data-animation-out` (apply to any
+`data-clip` element):
+
+### Core (always there)
+
+| Name | Notes |
+|---|---|
+| `fadeIn` / `fadeOut` | Pure opacity |
+| `fadeInUp` / `fadeInDown` / `fadeInLeft` / `fadeInRight` | Opacity + translate |
+| `slideUp` / `slideDown` | Translate only |
+| `zoomIn` / `zoomOut` | Opacity + scale |
+| `pop` | Overshoot scale (back-out feel) |
+| `blurIn` / `blurOut` | Opacity + 24px blur |
+| `rotateIn` | Opacity + rotate -180° + scale |
+| `swing3D` | 3D rotateX from -90° (top hinge) |
+| `floatIn` | Opacity + translate + sine bounce |
+
+### Diversification pack (added so parallel elements can use different presets)
+
+| Name | Visual feel | Best for |
+|---|---|---|
+| `unmaskUp` / `unmaskDown` / `unmaskLeft` / `unmaskRight` | Pure clip-path reveal (no opacity transition) — feels cinematic, "curtain pull" | Titles, headlines, hero quotes |
+| `flipInX` | 3D rotateX from 92° (bottom hinge) | Cards flipping face-up |
+| `flipInY` | 3D rotateY from -92° (left hinge) | Side panels, comparison cards |
+| `cubeIn` | rotateX-50° + translateY-100px (top hinge) | "A face of a cube tumbling into place" |
+| `magneticIn` | Tangent slide + small overshoot landing | Buttons / interactive elements being "pulled" |
+| `glitchIn` | RGB-split drop-shadow + jitter that lands cleanly | Technical / hacker / chaotic moments |
+| `skewIn` | Sheared landing (skewY/skewX → 0) | Editorial subhead, asymmetric layouts |
+| `kenBurnsIn` | Slow zoom (1.18 → 1.0) + horizontal drift | Photos, video plates, calm reveals |
+| `slideBlurIn` | translateX-60 + blur-12 → 0 | Editorial body text |
+| `dropIn` | Falls from above (~260px) with a small bounce settle | Statements, "drops the mic" moments |
+| `irisIn` | clip-path circle-reveal + scale | Spotlight moments, "the eye opens" |
+
+### Picking presets to maximize variety
+
+When you have N parallel siblings, draw one preset from each of these
+buckets in rotation:
+
+- Mask: `unmaskUp/Down/Left/Right`
+- 3D:   `flipInX`, `flipInY`, `cubeIn`, `swing3D`
+- Blur: `blurIn`, `slideBlurIn`
+- Phys: `magneticIn`, `dropIn`, `floatIn`
+- Glitch/skew: `glitchIn`, `skewIn`
+- Iris/Ken: `irisIn`, `kenBurnsIn`
+
+Register custom presets at composition load time:
+
+```html
+<script>
+  window.__mvm.register('myCustomEnter', t => ({
+    opacity: t,
+    transform: `translateY(${(1-t)*120}px) scale(${0.8 + t*0.2})`,
+  }));
+</script>
+```
+
+---
+
+## Easing Functions
+
+All available via `data-easing` / `data-easing-out`:
+
+`linear`, `easeIn`, `easeOut`, `easeInOut`,
+`easeOutCubic`, `easeInOutCubic`,
+`easeOutQuart`, `easeInOutQuart`,
+`easeOutQuint`,
+`easeOutExpo`, `easeInOutExpo`,
+`easeOutBack` (overshoot),
+`easeOutElastic` (springy),
+`easeOutBounce` (decaying bounce).

package/skills/motion-video-maker/reference/workflow.md

@@ -0,0 +1,190 @@
+# Authoring Workflow Recipes
+
+Step-by-step recipes for common composition types.
+
+---
+
+## Recipe 1 · Kinetic Title (5s, hook)
+
+A 5-second opener that fades in a big bilingual title.
+
+```bash
+node scripts/new-video.mjs hook --duration 5 --fps 30 --bg aurora
+```
+
+Edit `examples/hook/index.html`:
+
+```html
+<div id="stage" data-composition-id="hook"
+     data-width="1920" data-height="1080"
+     data-fps="30" data-duration="5">
+
+  <div data-background="aurora"
+       data-colors="#0f3460,#16537e,#e94560,#0f3460"></div>
+
+  <div class="scene center"
+       data-clip data-hide-mode="visibility"
+       data-start="0" data-duration="5">
+
+    <h1 class="title text-aurora"
+        data-clip data-start="0.3" data-duration="4.5"
+        data-text-animation="split-text"
+        data-stagger="0.08" data-char-duration="1.0">未来已来</h1>
+
+    <p class="subtitle"
+       data-clip data-start="1.6" data-duration="3.2"
+       data-animation="fadeInUp" data-in-duration="0.8"
+       data-animation-out="fadeOut" data-out-duration="0.5">THE FUTURE IS NOW</p>
+  </div>
+</div>
+```
+
+Render: `node scripts/render.mjs examples/hook/index.html`.
+
+---
+
+## Recipe 2 · Data Stat Reveal (12s)
+
+Hero number with supporting metric and animated background.
+
+```html
+<div id="stage" data-composition-id="stat"
+     data-width="1920" data-height="1080" data-fps="30" data-duration="12">
+
+  <div data-background="dot-grid" data-color="#3b82f6" data-bg="#040814"></div>
+
+  <div class="scene center" data-clip data-hide-mode="visibility"
+       data-start="0" data-duration="12">
+
+    <p class="caption"
+       data-clip data-start="0.5" data-duration="11"
+       data-animation="fadeInDown" data-in-duration="0.7">2026 · 全年新增用户</p>
+
+    <span class="huge text-gold"
+          data-clip data-start="1.2" data-duration="10"
+          data-text-animation="count-up"
+          data-from="0" data-to="1284690"
+          data-anim-duration="4.5" data-separator=","
+          data-easing="easeOutExpo">0</span>
+
+    <p class="subtitle wenkai"
+       data-clip data-start="6.0" data-duration="5.5"
+       data-animation="blurIn" data-in-duration="1.1">
+       较去年 <span class="text-fire">同比增长 312%</span></p>
+  </div>
+</div>
+```
+
+---
+
+## Recipe 3 · Multi-Scene Story (30s)
+
+Six scenes, each with its own background cross-fade. The reference
+`examples/time-flies/index.html` is the canonical example — copy it as a
+starting point for any narrative video.
+
+Skeleton:
+
+```html
+<div id="stage" data-fps="30" data-duration="30">
+
+  <!-- backgrounds, each cross-fading -->
+  <div data-clip data-start="0"    data-duration="6"
+       data-animation="fadeIn" data-animation-out="fadeOut"
+       data-background="aurora"></div>
+  <div data-clip data-start="5.5"  data-duration="6"
+       data-animation="fadeIn" data-animation-out="fadeOut"
+       data-background="threads"></div>
+  <div data-clip data-start="11"   data-duration="6"
+       data-animation="fadeIn" data-animation-out="fadeOut"
+       data-background="dot-grid"></div>
+  <div data-clip data-start="16.5" data-duration="7"
+       data-animation="fadeIn" data-animation-out="fadeOut"
+       data-background="waves"></div>
+  <div data-clip data-start="23"   data-duration="7"
+       data-animation="fadeIn"
+       data-background="hyperspeed"></div>
+
+  <!-- scenes -->
+  <div class="scene center" data-clip data-hide-mode="visibility"
+       data-start="0" data-duration="5"> ... opener ... </div>
+  <div class="scene center" data-clip data-hide-mode="visibility"
+       data-start="5" data-duration="6"> ... point 1 ... </div>
+  <!-- etc -->
+
+</div>
+```
+
+**Rule of thumb:** start each new scene's background 0.5s before the previous
+ends so the cross-fade overlaps; start each scene container right when its
+background hits full opacity.
+
+---
+
+## Recipe 4 · Social Vertical (1080×1920, 15s)
+
+Same authoring approach, just swap dimensions:
+
+```bash
+node scripts/new-video.mjs vertical --width 1080 --height 1920 --duration 15 --fps 30 --bg hyperspeed
+```
+
+For TikTok-style "bouncy caption" text, stack split-text + outer pop animation:
+
+```html
+<h1 class="title" style="font-size: 200px;"
+    data-clip data-start="0.4" data-duration="2"
+    data-animation="pop" data-in-duration="0.6"
+    data-text-animation="split-text"
+    data-stagger="0.05" data-char-duration="0.5"
+    data-easing="easeOutBack">炸裂！</h1>
+```
+
+---
+
+## Recipe 5 · Square Loop (1080×1080, 6s, seamless)
+
+For an OG-image-style loop, simply ensure the first and last frames have
+identical state (e.g. use only background animations and a steady text overlay
+with no in/out animations):
+
+```html
+<div id="stage" data-width="1080" data-height="1080"
+     data-fps="30" data-duration="6">
+  <div data-background="aurora"></div>
+  <div class="scene center">
+    <h1 class="title text-aurora glow" style="font-size: 140px;">永恒</h1>
+  </div>
+</div>
+```
+
+The aurora background uses sinusoidal motion so it visibly loops every ~12s;
+choose `data-duration` to align with that cycle (3, 6, 9, 12, ...) for a near-
+seamless loop. Use ffmpeg `-stream_loop` post-render if you need a longer asset.
+
+---
+
+## Performance Tips
+
+| Setting | Effect |
+|---|---|
+| `fps=15` + `preset=ultrafast` + `crf=24` | Quick draft, ~4× faster |
+| `fps=30` + `preset=medium` + `crf=18` | Default web/archive quality |
+| `fps=60` + `preset=slow` + `crf=14` | Cinematic / motion-heavy content |
+
+Backgrounds with `data-count` parameters (particles, starfield, hyperspeed,
+letter-glitch) dominate render time. For a hot loop where you keep tweaking
+text, swap to `data-background="aurora"` (pure radial-gradient blending) while
+iterating, then restore your chosen background for the final render.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+|---|---|
+| Element invisible despite `data-clip` window being active | Inline `style="opacity:0;"` was used as a "fallback" but the element has no `data-animation` to lift it. Either remove the inline style or add `data-animation="fadeIn"`. |
+| Gradient text becomes pure transparent after `split-text` | Confirm parent has both `background-image: linear-gradient(...)` _and_ `background-clip: text` (the `.text-aurora`/`.text-fire`/etc. presets handle this). |
+| Layout collapses below the stage | A child of `#stage` is `position: static` (default) and pushes itself out of the viewport. Make scene containers `position: absolute; inset: 0;` (or use the `.scene` preset class). |
+| Chinese characters render as blocks (□) | Run `node scripts/install-fonts.mjs`. The CSS preset chain falls back to system Chinese fonts but having `Noto Sans SC` local makes builds reproducible across machines. |
+| Render hangs after "loading" message | Browser failed to fire `__mvm.ready`. Open the HTML in a regular browser and check DevTools for JS errors. |