primocode 10.17.1 → 10.19.0

package/vendor/motioncraft/references/phase1-planning-and-preview.md

@@ -0,0 +1,74 @@
+# Phase 1: board, stills, and reusable 3D frames
+
+The board is a scaffold, not an AI script generator. The agent still writes the hook, checks facts, chooses licensed assets, and gets copy approved. Use one plain sentence per scene. A new `brief.json` can start like this:
+
+```json
+{
+  "topic":"MotionCraft intro",
+  "audience":"orang baru kenal motion graphics",
+  "goal":"jelaskan hasil dan cara pasang",
+  "language":"id", "duration":60, "format":"16:9", "handle":"@pensourceid",
+  "cta":"Coba skill-nya",
+  "scenes":[
+    {"role":"hook","headline":"Cukup ketik satu kalimat","visual":"chat prompt"},
+    {"role":"proof","headline":"Lihat hasilnya","visual":"real screen recording","proof":"source link"},
+    {"role":"cta","headline":"Coba MotionCraft","visual":"repo/install"}
+  ]
+}
+```
+
+Omit `scenes` for the eight-role default. That default has blank headlines on purpose, so an agent cannot pass invented copy off as approved. Run:
+
+```bash
+node <skill-dir>/scripts/motioncraft.mjs storyboard --brief brief.json --out storyboard.json
+```
+
+The JSON has start/end and a late-in-scene preview frame for each scene. The Markdown board is for review. After approval, build actual Remotion scenes at those times, then render only one still per scene:
+
+```bash
+node <skill-dir>/scripts/motioncraft.mjs preview --dir my-video --board storyboard.json --comp Main --scale 0.35
+```
+
+Open every PNG and the contact sheet. The stills show the **current composition**, not a pretend video automatically generated from the board. They are not a substitute for motion/audio review or overlap QA. If a frame shows an entering animation, move its `previewFrame` to a later frame inside that scene and rerun.
+
+## Reorder and retime the rendered video
+
+Start with a timeline-aware composition:
+
+```bash
+node <skill-dir>/scripts/motioncraft.mjs timeline init launch --out timeline-launch.json
+node <skill-dir>/scripts/motioncraft.mjs timeline edit --board timeline-launch.json --grid audio/beatgrid.json --out timeline-editor.html
+```
+
+Open the local HTML. Drag scenes or use arrow buttons, change each duration, and shift beat markers. Export `storyboard.edited.json` and, if you supplied a grid, `beatgrid.edited.json`. Attached scene events scale with the new scene windows. Render the actual edited scene order and duration with no source-code change:
+
+```bash
+node <skill-dir>/scripts/motioncraft.mjs render --dir my-video --comp TimelineLaunch --timeline storyboard.edited.json --grid beatgrid.edited.json --props launch-props.json --out out/edited.mp4
+```
+
+For tutorials, use `timeline init tutorial` and `--comp TimelineTutorial`. For the legacy compositions, use `timeline init main` with `--comp Main` or `MainVertical`, `timeline init product-launch` with `--comp ProductLaunch`, and `timeline init screen-tutorial` with `--comp ScreenTutorial`. Export and pass the edited board with `--timeline`; source-frame segments drive scene reorder and retime in each original composition. Timeline-aware compositions have built-in `problem`, `demo`, `features`, `cta` launch roles and `intro`, `step`, `outro` tutorial roles. Edit headlines in the JSON. Product copy and real media paths come from props. Sequence windows move actual content blocks; the visible beat marker pulses at shifted beat times. Retime scene-aligned music and VO from the same original timing plan, including beat offset for music:
+
+```bash
+node <skill-dir>/scripts/motioncraft.mjs timeline audio --original timeline-launch.json --edited storyboard.edited.json --grid beatgrid.edited.json --music audio/music.wav --vo audio/vo.wav --outDir audio/retimed
+```
+
+Rerun `sfx auto` with the edited board, mix with `audio/retimed/music.wav` and `audio/retimed/vo.wav`, listen to the joins and stretched speech, and approve a fresh mix review before `render --audio`. Beat offset moves the music but not VO. Both inputs must span the original board duration; a shorter VO needs intentional padding before this step. These files are not applied by `render` automatically.
+
+**Limits:** Legacy compositions consume the timeline as an edit decision over the existing source-frame segments; changing a JSON headline does not rewrite their hand-coded text or underlying visual design. Footage frames advance from each scene's local start: moving or stretching a scene does not intelligently cut or resample source recordings. The audio command stretches and reorders scene-aligned VO/music, but cannot infer free-running narration or footage sync; it does not preserve pitch perfectly at large stretches. Independently synced media, VO, music and external events need separate review and adjustment. Inspect the final rendered pixels and audio; placeholder demo/capture panels are not publishable.
+
+## Cache heavy 3D once
+
+Make an isolated composition (for example `LogoOnly`) containing just the 3D element on a transparent background, at the same canvas size, position and timing as the final scene. The CLI cannot automatically remove a rendered background: test transparency before using the cache as an overlay. Render a short range:
+
+```bash
+node <skill-dir>/scripts/motioncraft.mjs cache3d --dir my-video --comp LogoOnly --start 240 --end 329 --fps 30 --scale 1 --sources src/scenes/LogoOnly.tsx,src/components/Three.tsx,src/style.json
+```
+
+The command creates lossless PNGs under `public/mc-cache/` and a manifest with hashes of the listed sources, props and render settings. Call it again with unchanged inputs: it returns `cached:true` without WebGL. In the final scene, replace the live 3D element in the same bounds with:
+
+```tsx
+import {CachedFrames} from '../components/CachedFrames';
+<CachedFrames dir="mc-cache/LogoOnly-<key from output>" start={240} count={90} />
+```
+
+The generated `component` field gives exact JSX. If your scene is inside a `<Sequence>`, Remotion's `useCurrentFrame()` is local to that sequence; pass a matching local `start` or put CachedFrames outside it. Always visually compare source and cache at entry, midpoint and exit. **List all source files that affect the 3D pixels**, including textures and token files. A change outside `--sources` cannot invalidate the key; delete the cache or add that file if unsure. Do not cache text/VO with the 3D or a text revision will invalidate the cache too. Re-run overlap QA on the final composed video.

package/vendor/motioncraft/references/phase2-timeline-audio.md

@@ -0,0 +1,33 @@
+# Phase 2: timeline audio
+
+The storyboard and structured animation timeline are cue sources. `sfx auto` now creates sparse cues without `events` in the brief: it detects a headline appearance near each scene start and a transition at each subsequent scene boundary. Pass `--timeline public/timeline.json` for precise `events` that name a scene and visual action (`text`, `transition`, `ui_click`, `logo_reveal`, `check`). Alternatively put structured `animations` on a scene with `kind` and absolute `at` seconds or `frame` (at storyboard FPS). Only recognized kinds become sounds. A separate scene's timeline events are ignored.
+
+The mapping is text/headline -> typing, scene transition -> whoosh, UI click -> button, logo reveal -> logo sting, check -> check. All audio lands on the existing synthesized SFX timeline. The system does not inspect Remotion JSX or watch video pixels: the animation data must describe the actual on-screen time. It will not invent a logo or click from prose alone.
+
+For a precise override, put `events` on a scene. An `events` array completely replaces automatic cues for that scene, including boundary and headline cues; `events: []` means intentional silence. The older `cue` field also works when no `events` are supplied. Unknown cue types are reported, not rendered.
+
+```json
+{"role":"proof","headline":"See it work","animations":[{"kind":"ui_click","at":15.6},{"kind":"logo_reveal","frame":540}]}
+```
+
+Run from the project directory (replace `<skill-dir>` with this folder):
+
+```bash
+node <skill-dir>/scripts/motioncraft.mjs storyboard --brief brief.json --out storyboard.json
+node <skill-dir>/scripts/motioncraft.mjs sfx auto --board storyboard.json --out audio/auto-cues.json
+node <skill-dir>/scripts/motioncraft.mjs music moods --mood premium
+node <skill-dir>/scripts/motioncraft.mjs music audition --duration 52 --out audio
+node <skill-dir>/scripts/motioncraft.mjs music make --preset cinematic-soft --duration 52 --out audio
+node <skill-dir>/scripts/motioncraft.mjs sfx make --cues audio/auto-cues.json --duration 52 --pack soft-pop --out audio/sfx.wav
+node <skill-dir>/scripts/motioncraft.mjs mix --music audio/music.wav --sfx audio/sfx.wav --duration 52 --out audio/final.wav
+node <skill-dir>/scripts/motioncraft.mjs mix review --file audio/final.wav --cues audio/auto-cues.json --out out/mix-review
+```
+
+After `timeline build`, add `--timeline public/timeline.json` to `sfx auto` and rerun `sfx make` for animation events. `music moods` is a selection aid over existing instrumental presets. Audition before making a track, then choose a distinct sound per video. The existing variety guard blocks a too-similar new track. For voiceover add `--vo vo_clean.wav` to mix. Listen to the entire mix and cue snippets, inspect that each sound corresponds to the actual motion, and adjust the cue JSON or bed level when needed. `qa audio` checks measured loudness/peak but cannot judge taste or voice masking. After listening:
+
+```bash
+node <skill-dir>/scripts/motioncraft.mjs mix review --file audio/final.wav --out out/mix-review --approve
+node <skill-dir>/scripts/motioncraft.mjs render --comp Main --audio audio/final.wav --review out/mix-review/review.json
+```
+
+A changed mix invalidates approval by SHA-256. Rendering with audio stops if the matching review is missing. This is an operator review, not an automated listening test. The source audio still must be checked against final video sync. Avoid cue overload: default cap 24 cues/minute with a 120 ms gap, and 550 ms between loud cues. Lower with `--maxPerMin` and change `--minGap` if the scene needs more space. This isn't audio source separation or detection of arbitrary Remotion animation code: keep the structured scene/timeline data aligned with the actual animation timing. The music arranger rounds up to bars, so it may run longer than the video. `mix --duration <seconds>` trims and fades its last 0.35 s to the exact video length, but refuses a source shorter than the target. Confirm the end in the final rendered file.

package/vendor/motioncraft/references/phase3-pixel-review.md

@@ -0,0 +1,13 @@
+# Phase 3: honest final-pixel QA
+
+After `render`, run `qa all` and `qa pixels` on the *final exported video*, not on the Remotion debug pass. Supply the storyboard to sample scene starts, near-ends, and representative preview frames. Without a board, eight evenly spaced frames plus first/last are checked. `qa pixels` writes actual full-size PNGs, scene-timed audio snippets when the video has audio, a contact sheet, and `review.json` with source hash, OCR text flags, font-import audit and frame timestamps.
+
+```bash
+node <skill-dir>/scripts/motioncraft.mjs qa pixels out/final.mp4 --board storyboard.json --dir . --outDir out/qa-pixels
+```
+
+This check flags likely small glyphs on a 360px-wide phone, text near frame edges, text under likely 9:16 app chrome (right 12% after top 12%, bottom 20%), and dense edges near the apparent headline. These are conservative *review leads*. OCR can miss words, confuse text with graphics, and report false alarms. Its headline-area test measures local edge density, not semantic empty space. Review the corresponding full-size PNG and watch motion at normal speed. A pass never means zero overlaps. `qa overlap` sees only instrumented `McBox` debug rectangles; graphics and text can collide in final pixels even when debug-box checks pass.
+
+Font audit checks that `src/style.json` names font families imported in `src/lib/fonts.ts` and that tokens load the file. It cannot prove a font downloaded or every glyph rendered in the intended face. Inspect the final glyph shapes and console for fallbacks. Text sizing is based on OCR glyph boxes after scaling to a 360px-wide phone, not CSS font-size, so treat flags as cues to inspect.
+
+Listen to the **final exported video** and its critical-time snippets, not only to the pre-export mix. Check sync at intro, scene cuts, logo and CTA, VO legibility and final fade. `qa audio` measures LUFS/true peak/silence, while `mix review` generates cue snippets and a hash-bound approval before export; neither hears quality. Sample checks do not replace watching the whole video. Keep an explicit human review note for crop, spacing, fonts, readability and audio, with timestamps of problems and fixes. Do not report a zero-overlap result without opening final pixels at the affected times.

package/vendor/motioncraft/references/phase4-templates.md

@@ -0,0 +1,30 @@
+# Phase 4: two pi-v2 templates
+
+A new project includes `ProductLaunch` (45s, 1920x1080, adjustable to 30-60s) and `ScreenTutorial` (60s, 1080x1920, adjustable to 30-90s). They reuse pi-v2 background, typography, cards, scenes and debug boxes, with a clear structure rather than a finished claim or asset. Demo/screen-capture placeholders are red and say DO NOT PUBLISH. Both require real numbered JPGs inside `public/`, a source credit and project-specific copy. The template checker validates key fields, time windows, safe pointer bounds and actual frame files. The render still needs final-pixel and audio QA.
+
+## Product launch
+
+Structure: problem 0-8s, real demonstration 8-27s, two substantiated features 27-39s, CTA 39-45s. Set `duration` in your props to 30-60. The composition metadata and four scene boundaries scale from the 45s version; inspect the pacing at your chosen length. Never invent a product claim. Example Remotion props:
+
+```json
+{"duration":45,"handle":"@brand","product":"Product name","problem":"Real pain point","feature1":"Verified feature","feature2":"Another verified feature","cta":"Try the demo","demoDir":"launch-frames","demoCount":540,"demoCredit":"Original capture by brand"}
+```
+
+Put JPGs `public/launch-frames/001.jpg` through `540.jpg`. This demo frame component advances at 30 fps after the scaled 9s reveal; confirm frame continuity, timing and source rights. Use `template launch --spec launch-props.json --out out/checked-props.json` to pass a checked prop file to Remotion. Run:
+
+```bash
+node <skill-dir>/scripts/motioncraft.mjs template launch --spec launch-props.json --dir .
+npx remotion still src/index.ts ProductLaunch out/launch-still.png --frame 450 --props=launch-props.json
+```
+
+## Screen tutorial
+
+Default: three 20s steps. Set `duration` to 30-90 and make the contiguous steps finish at that second; composition metadata follows it. A 920px-wide capture panel fills the middle. The title sits above it and step cards/captions sit below it, not over the UI. Each step points to a capture-relative fractional `(x,y)` (safe bounds x .12-.88, y .12-.85) and zoom 1-1.6. The highlight follows the transformed capture coordinate during the 12-frame focus zoom; confirm it still points at the intended control and is not clipped by the capture panel. Example props:
+
+```json
+{"duration":60,"handle":"@brand","title":"How to do the task","captureDir":"tutorial-frames","captureCount":1800,"captureFps":30,"sourceCredit":"Original recording by brand","steps":[{"title":"Open","caption":"Open the project","from":0,"to":20,"x":0.5,"y":0.3,"zoom":1.2},{"title":"Choose","caption":"Select the item","from":20,"to":40,"x":0.7,"y":0.5,"zoom":1.35},{"title":"Finish","caption":"Review the result","from":40,"to":60,"x":0.5,"y":0.7,"zoom":1.15}]}
+```
+
+Run `template tutorial --spec tutorial-props.json --dir .`, then inspect actual stills at each step and the exported video at phone size. Adjust captions so they remain short and do not overlap platform chrome. Long or scroll-heavy recordings may need resampling, manual cuts or a different focus path; the template does not detect what the UI says.
+
+For both templates: create a private preflight storyboard and cue annotations, render with a reviewed audio mix, run `qa all` and `qa pixels`, inspect the final PNGs and listen to the final export. Placeholder content, fabricated UI, missing credits or unreadable real screen content are not ready for delivery. The template checker is not a license check and cannot prove the frame sequence corresponds to a real demo.

package/vendor/motioncraft/references/preflight.md

@@ -0,0 +1,27 @@
+# Preflight
+
+```bash
+node <skill-dir>/scripts/motioncraft.mjs doctor          # full check, prints a table
+node <skill-dir>/scripts/motioncraft.mjs doctor --quick  # reuse a check from the last 7 days
+```
+
+Doctor never installs anything. It prints a fix command for your OS and a fallback for anything optional.
+
+| Item | Tier | Without it |
+|---|---|---|
+| Node.js 18+ | required | nothing works |
+| npm | required | comes with Node |
+| Remotion (in the project) | required | run `npm install` inside the project |
+| ffmpeg | recommended | Remotion's bundled ffmpeg is used (`npx remotion ffmpeg`) |
+| yt-dlp | recommended | ask the user for the reference file |
+| Whisper (faster-whisper, whisper.cpp or openai-whisper) | recommended | phrase-level timing from pauses |
+| Python 3 + numpy/scipy/librosa/soundfile/pyloudnorm | optional | pure-Node analysis (slightly less accurate BPM/key) |
+| tesseract | optional | no OCR in reference analysis |
+| GPU | optional | 3D renders with `--gl=swangle` (software, slower) |
+| Free disk > 5 GB | recommended | renders may fail |
+
+Shell wrappers: `scripts/doctor.sh` (macOS/Linux) and `scripts/doctor.ps1` (Windows) just call the same check.
+
+Ask before installing anything on the user's machine. Show them the exact command doctor printed.
+
+GPU device detection is not proof of acceleration. See [GPU/cloud render](gpu-cloud-render.md) before using a paid worker or promising a speedup.

package/vendor/motioncraft/references/qa.md

@@ -0,0 +1,53 @@
+# QA
+
+Nothing goes to the user until all of these pass.
+
+## 1. Automatic checks
+
+```bash
+node <skill-dir>/scripts/motioncraft.mjs qa overlap --comp Main
+node <skill-dir>/scripts/motioncraft.mjs qa all out/final.mp4 --comp Main --maxMb 16
+node <skill-dir>/scripts/motioncraft.mjs qa pixels out/final.mp4 --board storyboard.json --dir .
+```
+
+`qa overlap` flags only registered debug boxes and cannot prove that the final pixels are collision-free. `qa pixels` samples the actual exported video at scene starts, ends and preview frames, makes a contact sheet, and runs heuristic OCR checks for tiny or cropped text. Inspect every flagged frame at full size and a phone-sized version, then watch the full video.
+
+`qa overlap` renders the composition in debug mode at 1/4 size. Every `McBox kind="text"` is painted light red, every `McBox kind="block"` light green, and the content is hidden. It then scans every frame:
+
+| Flag | Meaning | Usual fix |
+|---|---|---|
+| `textOverlapPx` | two text boxes stacked (dark red) | put them in different zones, exit the old one first, shorten the text |
+| `blockOverlapPx` | two cards stacked (dark green) | spread them out, or stagger their entry/exit |
+| `textInMarginPx` | text inside the safe margin | move it in, reduce size, or reduce camera zoom in that range |
+
+Screenshots of each problem range land in `out/qa-overlap/`. During the debug pass, scene crossfades switch at the midpoint, so the intended blurred crossfade is not reported. A sticker that is meant to sit on a card can use `allowOverlap`, but use it rarely.
+
+Only boxes wrapped in `McBox` are checked. If you add a new text element, wrap it.
+
+`qa all` also checks:
+- file: size limit, audio stream present, audio and video length match
+- audio: -14 LUFS (±1), true peak <= -1 dBTP, no long silences
+- sheet: 24 frames tiled into `out/qa/sheet.jpg`
+
+## 2. Look at it yourself
+
+Open the sheet and at least 3 full-size frames. Check:
+
+- [ ] One focus per frame. Your eye knows where to look within half a second.
+- [ ] Headline readable at phone size (h1 >= 64 px at 1080p).
+- [ ] At most one accent word per sentence.
+- [ ] Nothing cut off at the edges, nothing hidden behind platform UI (9:16: bottom 20%, right 12%).
+- [ ] No leftover placeholder text, lorem, or "Example data" credits.
+- [ ] Numbers and names match the research sources.
+- [ ] Every third-party logo/screenshot has a credit.
+
+## 3. Listen
+
+- [ ] Every name and brand word is said correctly (read the word timings, then listen to those spots).
+- [ ] Music never covers the voice.
+- [ ] Big visual moments land on a beat or the drop.
+- [ ] SFX are sparse; no sound without a visual reason.
+
+## 4. Watch once at full speed
+
+Anything that feels rushed, dead, or jumpy gets fixed before sending. Holds should be at least `0.8 s + 0.25 s per word`.

package/vendor/motioncraft/references/reference-analysis.md

@@ -0,0 +1,37 @@
+# Reference analysis
+
+Use this when the user sends a video and says "make it like this".
+
+```bash
+node <skill-dir>/scripts/motioncraft.mjs ref get <url-or-file> --dir ref   # downloads with yt-dlp, or copies a local file
+node <skill-dir>/scripts/motioncraft.mjs ref report --dir ref               # writes ref/ref_report.md
+node <skill-dir>/scripts/motioncraft.mjs ref text --dir ref                 # optional, needs tesseract
+```
+
+If yt-dlp is missing or the site blocks it, ask the user to download the video and pass the file.
+
+## What the report gives you and how to use it
+
+| Report part | Read it as | Turn it into |
+|---|---|---|
+| Cuts (times) | pace. Many cuts per minute = energetic | `--energy` knob, scene lengths |
+| Motion per second | how much moves on screen | `--energy`, camera `still/smooth/active` |
+| Palette | background, ink, accent colors | `color` tokens (keep one accent) |
+| Music: BPM, key, LUFS, drop | tempo and where the peak is | `music make --bpm --drop`, pick a preset with a similar feel |
+| Contact sheet | layout, type, density, 3D or flat | zones, font level choice, `--density`, `--depth` |
+
+The key estimate is rough; treat it as a hint. BPM and loudness are reliable.
+
+## Also look yourself
+
+Open the contact sheet and a few frames and write down in plain words:
+
+- How text enters (blur, slide, type-on, scale)
+- How many words are on screen at once
+- Font feel (geometric sans, serif, mono) - find a free font with that feel
+- What the hero visuals are (UI mockups, 3D objects, photos, icons)
+- How scenes change (cut, crossfade, camera move)
+
+## Copy the feel, not the video
+
+Never reuse the reference's footage, logos, music, or exact layouts. Build the same *feel* with the style tokens and your own content. If you want to show part of the reference on screen (for example in a "look at this" moment), credit it with `<Credit>`.

package/vendor/motioncraft/references/research-and-topic.md

@@ -0,0 +1,25 @@
+# Research and topic
+
+## Pick an angle
+
+A good video answers one question the audience already has. Before writing:
+
+- Who is watching and what do they already know?
+- What is the one thing they should remember?
+- Why now? (new release, common mistake, trend)
+
+If the user gives only a topic, propose 2-3 angles in one line each and pick the strongest if they don't care.
+
+## Research
+
+- Use live sources: official docs, changelogs, release notes, the product's own site, reputable news.
+- Save every fact in `research.md` with its URL and the date you checked it.
+- Numbers (users, stars, prices, benchmarks) change fast. Re-check them right before the final render.
+- If two sources disagree, use the official one and say so in the note to the user.
+- Don't state something as fact if you only found it in one unofficial place.
+
+## On screen
+
+- Every number or claim from a third party gets a `<Credit>` line.
+- Screenshots of other products: use real ones, credit them, never fake a UI and pass it off as real.
+- If a fact can't be verified, cut it or turn it into an opinion ("feels faster") that the user agrees to.

package/vendor/motioncraft/references/script-and-structure.md

@@ -0,0 +1,39 @@
+# Script and structure
+
+## Default structure (30-90 s)
+
+| Part | Time | Job | Pattern |
+|---|---|---|---|
+| Hook | 0-3 s | stop the scroll | a bold claim, a question, or a surprising visual |
+| Reframe | 3-10 s | change how they see it | "Not X. Y." |
+| Proof | 10-35 s | show it working | UI cards, numbers with credits, before/after |
+| How / formula | 35-50 s | make it usable | 3 steps, one card each |
+| CTA | last 5-8 s | one action | "Comment X", "Follow for more", "Link in bio" |
+| End card | 2-3 s | who made it | handle + one line |
+
+Shorter video? Cut the formula, keep hook -> proof -> CTA.
+
+## Writing rules
+
+- One idea per sentence, 8-14 words.
+- Talk like a person. No "Unlock", "Revolutionize", "Game-changer", "In today's fast-paced world".
+- Concrete beats clever: "renders in 40 seconds" beats "blazing fast".
+- The hook must work with the sound off - the first headline carries it alone.
+- End on the action, not on a summary.
+
+## Scene list
+
+Write it next to the script, one row per line:
+
+```
+0:00  "Make videos like this."         h1 center + FloatingShapes
+0:03  "The secret is not prompts."     Strike "prompts."
+0:05  "References."                    h0, accent
+...
+```
+
+Each row names a component from the template. If a line has no visual idea, the line is probably filler - cut it.
+
+## Length check
+
+Spoken English runs about 2.5 words per second. A 60 s video fits roughly 130-150 words of voiceover, less if there are musical pauses.

package/vendor/motioncraft/references/sfx.md

@@ -0,0 +1,40 @@
+# Sound effects
+
+All sounds are synthesized by `sfx make` - no sample packs, nothing to license.
+
+## Types
+
+`word_pop`, `icon_pop`, `letter_tick`, `check`, `success`, `slot_tick`, `bubble`, `type`, `button`, `whoosh_in`, `whoosh_out`, `swoosh`, `riser`, `impact`, `confetti`, `logo_sting`
+
+## Packs
+
+`soft-pop` (pi-v2 default), `glass`, `paper`, `digital-soft`, `organic-wood`. Same cues, different material.
+
+## Cue file
+
+```json
+[
+  { "type": "whoosh_in", "t": 3.35 },
+  { "type": "word_pop",  "t": 4.8, "gain": -2 },
+  { "type": "check",     "t": 10.0 },
+  { "type": "riser",     "t": 11.2, "end": 12.9 },
+  { "type": "impact",    "t": 12.9, "snap": true }
+]
+```
+
+Fields: `type`, `t` (seconds), optional `gain` (dB), `pitch`, `pan`, `end` (for risers), `snap` (snap to the beat grid when `--bpm` is given).
+
+```bash
+node <skill-dir>/scripts/motioncraft.mjs sfx make --cues sfx.json --bpm 93 --pack soft-pop --out audio/sfx.wav
+node <skill-dir>/scripts/motioncraft.mjs beat snap sfx.json --grid audio/beatgrid.json --maxMs 80
+```
+
+`--density 0.6` randomly thins the small repeated sounds (word pops, ticks, typing).
+
+## Rules
+
+- One sound per meaningful visual event: a scene change, a card landing, a check, the big reveal. Not every word.
+- Put the cue 1-2 frames before the visual, not after.
+- A riser always resolves into an impact or the drop.
+- If the voice is talking, keep SFX small. Save big sounds for pauses.
+- `mix` places the SFX track at -4 dB relative; adjust with `--sfxDb`.

package/vendor/motioncraft/references/social-formats.md

@@ -0,0 +1,18 @@
+# Multi-format social output
+
+Build one responsive Remotion composition, then export it for each canvas:
+
+```bash
+node <skill-dir>/scripts/motioncraft.mjs new my-video --format 9:16 --platform tiktok
+cd my-video && npm install
+# After QA and mix review, render all three from the SAME scene code and props:
+node <skill-dir>/scripts/motioncraft.mjs render --comp Main --all-formats --preset ig
+# Or individually (Reels is also 9:16):
+node <skill-dir>/scripts/motioncraft.mjs render --comp Main --format 9:16 --platform reels --preset ig
+```
+
+`--all-formats` makes 1:1 IG feed (1080x1080), 4:5 IG feed (1080x1350), and 9:16 TikTok (1080x1920). To export Reels too, run the separate Reels command. `--props path.json` passes content props; format and platform are overlaid at export. Native Remotion preview: `npx remotion still src/index.ts Main out/feed.png --props='{"format":"4:5","platform":"ig-feed"}'`. `new --vertical` is a backward-compatible alias for 9:16.
+
+The shared geometry in `assets/template/src/lib/format.mjs` defines conservative inset defaults: TikTok 72 left / 175 right / 210 top / 350 bottom; Reels 72 / 175 / 190 / 340; feed square 72 / 72 / 96 / 115 and 4:5 72 / 72 / 100 / 135 (pixels). These are **not** platform-certified safe areas. UI overlays vary with captions, audio badges, account features, phone and app versions. Review actual uploads or app previews for the exact target. Keep vital copy/logo inside the safe content rectangle; do not park captions or CTAs below it.
+
+`Center` and `Zone` place content within this rectangle. Headline width and type shrink to fit narrow canvases; Example scene reflows card and checklist from a row to a column; ProductLaunch resizes the proof card; ScreenTutorial moves screen capture and captions into separate safe regions. `EndCard` scales mascot and handle. For a custom scene, use `useFormat()` and `geometry(format,platform)`, and adapt hero size/direction; absolute pixel coordinates from old widescreen scenes do not become responsive on their own. Long text, unusual branding, large screenshots, camera zoom and motion can still cross safe edges. Render critical frames for all outputs and inspect pixels; run overlap QA separately per format, e.g. `qa overlap --comp Main --format 4:5 --platform ig-feed`; the debug check uses that target's safe rectangle but only sees instrumented boxes. Do not call a video upload-ready until the footage, text, logo, audio, credits, and real app overlays pass review.

package/vendor/motioncraft/references/taste.md

@@ -0,0 +1,36 @@
+# Taste
+
+What separates a designed video from an "AI slop" one. Check every frame against this.
+
+## Looks generated (avoid)
+
+- Colored blurry blobs everywhere as the background
+- Inter or the system default font for everything
+- Emoji used as icons
+- Fake CSS 3D (flat cards spun on an axis) instead of real lit 3D or none
+- Every word popping with a bounce
+- Gradients on text, glows on everything, 4+ accent colors
+- Stock phrases: "Unlock", "Supercharge", "Revolutionize", "Seamless"
+- Text wall: 3+ lines, small type, centered on a busy visual
+- Numbers with no source
+- Every element moving at once
+
+## Looks designed (aim for)
+
+- One accent color, used for one word per sentence
+- Lots of empty space; the frame breathes
+- Clear hierarchy: one big thing, one supporting thing
+- Words appear exactly when spoken, rising softly out of blur
+- A few real objects (UI cards, logos, lit 3D shapes) that mean something
+- Slow camera drift so nothing is ever frozen
+- Transitions that carry motion from one scene into the next
+- Sound that you notice only when it's missing
+
+## Before you send, ask
+
+1. Would a designer screenshot any frame of this for inspiration?
+2. Is there anything on screen that doesn't help the sentence being spoken?
+3. Does the first frame make sense with the sound off?
+4. Does the video look like *this style*, or like every other AI video?
+
+If any answer is no, fix that first.

package/vendor/motioncraft/references/troubleshooting.md

@@ -0,0 +1,19 @@
+# Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| Render fails with a GL / WebGL error | add `--gl=swangle` (software). Slower but works everywhere. |
+| 3D scenes render black or very slow | use `--gl=swangle`, lower `FloatingShapes` count, or pre-render 3D to a PNG sequence and play it with `<Frames>` |
+| Fonts look wrong in the render | fonts load from Google Fonts via `src/lib/fonts.ts`; make sure the machine is online, or switch to `@remotion/fonts` with local files in `public/fonts` (see the comment in that file) |
+| Text changes line breaks between studio and render | same cause: font not loaded when measured. Fix fonts first. |
+| `headline too long` warning | rewrite the line shorter. Don't shrink below the level's minimum. |
+| Words appear out of sync | re-run `vo align`; check you used the cleaned VO file in `mix` and `timeline build`; confirm the composition fps matches the style (30) |
+| Audio and video lengths differ (qa file) | set `durationInFrames` in `src/Root.tsx` to the `timeline.json` duration x fps |
+| Final file too big for WhatsApp | `render --preset wa` (two-pass, aims under 16 MB) |
+| Loudness off in `qa audio` | re-run `mix`; don't normalize again in another tool |
+| `music make` refuses ("too similar") | change key, BPM (by 6+), progression or lead. That's the variety guard. |
+| `qa overlap` fails on a crossfade | it shouldn't: scenes switch at the midpoint in debug mode. If it does, your two scenes overlap by more than the token `scene.overlap`. |
+| `qa overlap` misses an element | wrap it in `McBox` |
+| `yt-dlp` blocked | ask the user for the file |
+| Render is slow | render at 30 fps, use `--concurrency`, close Remotion Studio, pre-render heavy 3D |
+| Remotion license question | https://www.remotion.dev/license |

package/vendor/motioncraft/references/typography.md

@@ -0,0 +1,34 @@
+# Typography
+
+Values below are the `pi-v2` defaults from `styles/pi-v2/tokens.json`. Other styles change the numbers, not the rules.
+
+## Levels
+
+| Level | Use | Size at 1080p | Weight | Line height |
+|---|---|---|---|---|
+| h0 | one big word or number | 120-150 | 700 | 1.08 |
+| h1 | main headline | 64-76 | 600 | 1.15 |
+| h2 | supporting line | 34-46 | 500 | 1.3 |
+| caption | labels, credits | 20-30 | 500 | 1.35 |
+
+For 9:16, keep the same pixel sizes; the narrower width forces shorter lines, which is good.
+
+## Rules
+
+- Display font: Figtree. Mono: JetBrains Mono (code, commands). Two fonts max.
+- Tracking -0.02 em on display text.
+- Max 2 lines, max 7 words per line. Longer? Split into two beats.
+- One accent word per sentence, marked with `*word*` in `words()`. Accent = color, never a different font.
+- No all-caps sentences. All-caps only for a single short label.
+- Text is never centered on top of a busy visual. Use zones: headline in `top`, hero in `center`.
+- Text only appears when it is spoken (word timings), and leaves before the next headline enters.
+- Numbers use tabular figures (`Counter` already does).
+- Don't stack more than 3 text levels on one frame.
+
+## Measuring
+
+`Headline` measures every word with `@remotion/layout-utils` and breaks lines by real width: one line if it fits, otherwise the most balanced two lines, never a single orphan word on line 2. If it still does not fit in 2 lines, it prints a `[motioncraft] headline too long` warning in the console - rewrite the line shorter; do not drop below the level's minimum size.
+
+## Kinetic reveals (v0.5)
+
+`<Headline reveal="character" items={words('A big *idea*', at)} />` staggers characters inside each word with fixed layout width. The default word reveal remains unchanged. Character timing, blur and rise come from `motion.character` in the selected style. Keep copy short and inspect the entire line at phone size; character reveals on long sentences read slowly. `<Counter from={20} to={100} at={...} decimals={0} />` animates a cited number, and `motion.number.duration` controls its default length. A counter still needs a visible `<Credit>` for real data.

package/vendor/motioncraft/references/voiceover.md

@@ -0,0 +1,37 @@
+# Voiceover
+
+## Sources
+
+1. The user's own recording (best for trust).
+2. A TTS voice from whatever tool the user or agent has.
+3. No voice: text-only videos with music. Then timing comes from the beat grid.
+
+## Clean
+
+```bash
+node <skill-dir>/scripts/motioncraft.mjs vo clean vo.wav      # high-pass, noise reduction, loudness normalize
+```
+
+## Align (word timings)
+
+```bash
+node <skill-dir>/scripts/motioncraft.mjs vo align vo_clean.wav --script script.txt --lang en --out audio/words.json
+```
+
+- With Python + `faster-whisper` installed: word-level timings (`mode: word`).
+- Without it: phrase timings from pauses, matched to the script sentences (`mode: phrase`). `timeline build` spreads the words evenly inside each phrase. Put one sentence per line in `script.txt` and leave clear pauses between sentences.
+
+## Always check the transcript
+
+TTS voices and recognizers both get names wrong. After aligning:
+
+1. Compare the returned `text` with the script, word by word, especially names, brands, and numbers.
+2. If a spot looks wrong, cut that piece with ffmpeg and transcribe it alone - full-file transcripts can hide errors.
+3. Fix pronunciation by respelling in the TTS input (for example "Remotion" -> "Ree-motion"), regenerate only that line, and re-align.
+
+## Writing for voice
+
+- Short sentences, 8-14 words.
+- Numbers as they are said ("thirty frames per second", not "30fps").
+- Leave a 0.3-0.5 s pause before a big reveal so the visual can land.
+- Read the script aloud once. If you run out of breath, split the sentence.

package/vendor/motioncraft/references/workflow.md

@@ -0,0 +1,40 @@
+# Workflow
+
+The full loop, with what to show the user at each checkpoint.
+
+| # | Step | Output | Show the user? |
+|---|---|---|---|
+| 0 | `doctor` | ready machine | only if something is missing |
+| 1 | Brief | `brief.md` (topic, audience, format, length, style, voice, CTA, target) | yes, if you filled gaps with assumptions |
+| 2 | Research | `research.md` with source URLs | no, unless facts are uncertain |
+| 3 | Script | `script.txt` + a scene list (line -> visual) | **yes - get OK before voice** |
+| 4 | Reference (optional) | `ref/ref_report.md` + knob values | short summary |
+| 5 | Project | `new` + `npm install` + knobs + `style check` | no |
+| 6 | Voice | `vo clean` + `vo align` -> `audio/words.json` | check names by ear |
+| 7 | Music | `music audition` -> pick -> `music make` + `beat grid` | yes, the 3 auditions if the user cares about music |
+| 8 | Build | scenes in `src/scenes`, `timeline build` | 3-4 stills of key moments |
+| 9 | SFX + mix | `sfx make`, `mix` -> `audio/final.wav` | no |
+| 10 | QA | `qa overlap` pass, `render`, `qa all` pass, look at the sheet | no |
+| 11 | Deliver | final MP4 + two-line note | yes |
+| 12 | Feedback | changes by timestamp -> back to the right step -> QA -> render | yes |
+
+## Time budget for a 60 s video
+
+Script and research take the longest thinking; the build takes the longest clock time. Show stills before a full render - it's much cheaper to fix a layout in a still than after a render.
+
+## Feedback loop
+
+- Ask for feedback with timestamps ("0:12 the text is too small").
+- Group changes, apply them together, re-run QA, render once.
+- Note any preference that should hold for future videos (font, music vibe, pace) in the project's `brief.md`, so the next video starts right.
+
+## Files in a project
+
+```
+my-video/
+  brief.md  research.md  script.txt  mc.config.json
+  audio/     vo_clean.wav  words.json  music.wav  beatgrid.json  sfx.wav  final.wav
+  public/    timeline.json  (images, logos, screen recordings)
+  src/       style.json  scenes/  components/  lib/
+  out/       final.mp4  qa/  qa-overlap/
+```

package/vendor/motioncraft/scripts/assets/timeline-editor.js

@@ -0,0 +1,24 @@
+const {board,grid}=JSON.parse(document.getElementById('data').textContent);
+const list=document.getElementById('list'),error=document.getElementById('error'),summary=document.getElementById('summary');
+let order=board.scenes.map(s=>s.id);const scenes=new Map(board.scenes.map(s=>[s.id,s]));let duration=Object.fromEntries(board.scenes.map(s=>[s.id,s.end-s.start]));
+function draw(){list.replaceChildren();for(const id of order){const s=scenes.get(id),row=document.createElement('div');row.className='row';row.draggable=true;
+ const grip=document.createElement('span');grip.className='handle';grip.textContent='☰';row.append(grip);
+ const title=document.createElement('span');title.className='name';title.textContent=s.headline||s.role||id;const detail=document.createElement('small');detail.textContent=id;title.append(detail);row.append(title);
+ const label=document.createElement('label');label.textContent='Seconds ';const input=document.createElement('input');input.type='number';input.min=.8;input.step=1/board.fps;input.value=duration[id];input.oninput=()=>{duration[id]=input.value;total()};label.append(input);row.append(label);
+ for(const [icon,delta] of [['↑',-1],['↓',1]]){const button=document.createElement('button');button.textContent=icon;button.setAttribute('aria-label',`Move ${id} ${delta<0?'up':'down'}`);button.onclick=()=>move(id,delta);row.append(button)}
+ row.ondragstart=e=>{e.dataTransfer.setData('text/plain',id);row.classList.add('dragging')};row.ondragend=()=>row.classList.remove('dragging');row.ondragover=e=>e.preventDefault();row.ondrop=e=>{e.preventDefault();const from=e.dataTransfer.getData('text/plain');if(from!==id&&scenes.has(from)){order=order.filter(x=>x!==from);order.splice(order.indexOf(id),0,from);draw()}};
+ list.append(row)}total()}
+function move(id,delta){const i=order.indexOf(id),j=i+delta;if(j<0||j>=order.length)return;[order[i],order[j]]=[order[j],order[i]];draw()}
+function total(){let n=order.reduce((sum,id)=>sum+Number(duration[id]||0),0);summary.textContent=`Total: ${n.toFixed(2)}s (${Math.round(n*board.fps)} frames at ${board.fps} fps)`}
+function download(name,value){const url=URL.createObjectURL(new Blob([JSON.stringify(value,null,2)],{type:'application/json'}));const a=document.createElement('a');a.href=url;a.download=name;a.click();setTimeout(()=>URL.revokeObjectURL(url),5000)}
+document.getElementById('export').onclick=()=>{try{
+ const fps=Number(board.fps),offset=Number(document.getElementById('beat').value);if(!Number.isFinite(offset)||Math.abs(offset)>60)throw Error('Beat offset must be between -60 and 60 seconds');if(!grid&&offset)throw Error('Add --grid when opening this editor to shift beats');
+ let frame=0;const edited=order.map(id=>{const s=scenes.get(id),seconds=Number(duration[id]),frames=Math.round(seconds*fps);if(!Number.isFinite(seconds)||seconds<.8||!Number.isSafeInteger(frames))throw Error(`Invalid duration: ${id}`);
+ const start=Number(s.start),length=Number(s.end)-start;if(!(length>0))throw Error(`Invalid original scene: ${id}`);const shift=t=>+(frame/fps+(Number(t)-start)*frames/fps/length).toFixed(3);
+ const remap=e=>{const out={...e};for(const key of ['at','t'])if(e[key]!=null)out[key]=shift(e[key]);if(e.frame!=null)out.frame=Math.round(shift(Number(e.frame)/fps)*fps);return out};
+ const ratio=(s.previewFrame-s.fromFrame)/(s.toFrame-s.fromFrame);const out={...s,fromFrame:frame,toFrame:frame+frames,start:+(frame/fps).toFixed(3),end:+((frame+frames)/fps).toFixed(3),previewFrame:frame+Math.min(frames-1,Math.max(0,Math.round((Number.isFinite(ratio)?ratio:.7)*frames)))};
+ if(Array.isArray(s.events))out.events=s.events.map(remap);if(Array.isArray(s.animations))out.animations=s.animations.map(remap);frame+=frames;return out});
+ const length=+(frame/fps).toFixed(3);download('storyboard.edited.json',{...board,duration:length,scenes:edited});if(grid){const shift=t=>+(Number(t)+offset).toFixed(3);download('beatgrid.edited.json',{...grid,duration:length,beatOffset:offset,beats:(grid.beats||[]).map(shift).filter(t=>Number.isFinite(t)&&t>=0&&t<length),sections:Array.isArray(grid.sections)?grid.sections.map(s=>typeof s==='number'?shift(s):{...s,t:s.t==null?s.t:shift(s.t)}):grid.sections})}
+ error.textContent='Exported. Run timeline audio, then re-mix and review audio before rendering. Legacy copy/content stays hand-coded; this changes scene order and timing.';
+ }catch(e){error.textContent=e.message}};
+draw();

package/vendor/motioncraft/scripts/doctor.ps1

@@ -0,0 +1,13 @@
+# motioncraft bootstrap check (Windows PowerShell). Works without Node. Detects only - never installs.
+Write-Host "motioncraft bootstrap (Windows)"
+$winget = Get-Command winget -ErrorAction SilentlyContinue
+$node = Get-Command node -ErrorAction SilentlyContinue
+if ($node) {
+  $v = (& node -v); $maj = [int]($v.TrimStart('v').Split('.')[0])
+  if ($maj -ge 18) { Write-Host "  OK   node      $v" } else { Write-Host "  MISS node      found $v, need 18+  ->  winget install OpenJS.NodeJS.LTS" }
+} else { Write-Host "  MISS node      ->  winget install OpenJS.NodeJS.LTS   (or https://nodejs.org)" }
+if (Get-Command ffmpeg -ErrorAction SilentlyContinue) { Write-Host "  OK   ffmpeg" } else { Write-Host "  MISS ffmpeg    ->  winget install Gyan.FFmpeg   (optional: Remotion ships its own)" }
+if (-not $winget) { Write-Host "  note: winget not found; use the website links instead." }
+Write-Host ""
+Write-Host "Nothing was installed. Ask the user before running any install command above."
+if ($node) { Write-Host "Full check: node `"$PSScriptRoot\motioncraft.mjs`" doctor" }