docs: add Video Editor Cheatsheet guide

docs/docs.json

@@ -78,6 +78,7 @@
               "guides/hdr",
               "guides/performance",
               "guides/timeline-editing",
+              "guides/video-editor-cheatsheet",
               "guides/common-mistakes",
               "guides/troubleshooting"
             ]

docs/guides/video-editor-cheatsheet.mdx

@@ -0,0 +1,267 @@
+---
+title: Video Editor Cheatsheet
+description: "Fast reference for video editors and creative people directing agents, cutting timing, tweaking layouts, previewing, and publishing HyperFrames projects."
+---
+
+Use this as a fast reference when you are directing agents, cutting timing, making visual layout tweaks, previewing, and sharing HyperFrames projects.
+
+## The Fast Loop
+
+```bash
+npx hyperframes init my-video --example blank
+cd my-video
+npx hyperframes preview
+```
+
+Keep the preview running while your agent edits `index.html` or files in `compositions/`. The Studio updates automatically, so you can direct the agent, scrub the result, make manual visual tweaks, then repeat.
+
+Most production work should feel like this:
+
+1. Ask the agent for the first cut, scene, caption pass, transition, or cleanup.
+2. Use the Studio preview and timeline to check timing.
+3. Use manual DOM editing for Figma-like layout tweaks: select elements, move them, and adjust visual properties directly.
+4. Ask the agent to clean up or generalize anything you changed manually.
+5. Lint, validate, render, and publish.
+
+Before showing or rendering a project:
+
+```bash
+npx hyperframes lint
+npx hyperframes validate
+npx hyperframes render --quality standard --output review.mp4
+```
+
+For fast iteration renders, use draft quality:
+
+```bash
+npx hyperframes render --quality draft --output draft.mp4
+```
+
+For final delivery:
+
+```bash
+npx hyperframes render --quality high --fps 30 --output final.mp4
+```
+
+## Terminal Shortcuts
+
+Move around projects quickly:
+
+```bash
+pwd                 # show current folder
+ls                  # list files
+cd my-video         # enter a project folder
+cd ..               # go up one folder
+cd -                # jump back to the previous folder
+open .              # open the current folder in Finder on macOS
+code .              # open the current folder in VS Code, if installed
+```
+
+Common HyperFrames project folders:
+
+```bash
+cd assets           # source videos, images, audio
+cd compositions     # reusable scenes and overlays
+cd ..               # back to the project root
+```
+
+Run HyperFrames commands from the project root, where `index.html` lives. If you are not sure where you are, run `pwd` then `ls`. If you see `index.html`, you are in the right place.
+
+## Preview Shortcuts
+
+Start the Studio:
+
+```bash
+npx hyperframes preview
+```
+
+Use a different port if `3002` is already busy:
+
+```bash
+npx hyperframes preview --port 4567
+```
+
+Inside the Studio:
+
+| Shortcut | Use |
+| --- | --- |
+| `Space` | Play or pause (focus on the page body) |
+| `Left Arrow` / `Right Arrow` | Nudge seek bar by 1 second (seek bar focused) |
+| `Shift+Left Arrow` / `Shift+Right Arrow` | Nudge seek bar by 5 seconds (seek bar focused) |
+| `Shift+T` | Show or hide the timeline editor |
+| `Cmd+1` / `Ctrl+1` | Switch to Compositions |
+| `Cmd+2` / `Ctrl+2` | Switch to Assets |
+| `Delete` / `Backspace` | Delete the selected timeline clip (when not typing in an editor) |
+| `Escape` | Leave a sub-composition or close editor dialogs |
+
+<Tip>
+  Preview uses the same runtime as rendering, so the visual frame matches the output. If preview stutters on a heavy frame but the render is clean, that is expected — preview plays in real time, render captures one frame at a time.
+</Tip>
+
+## Agent-Led Editing
+
+Ask the agent to verify visible changes in the browser. For a user-visible edit, a good handoff is:
+
+```
+Run the preview, check it with agent-browser, take a screenshot, and render a draft MP4 to take a look at the frames with ffmpeg.
+```
+
+## Manual DOM Editing
+
+In the Studio, you can edit the DOM visually for the final 10% of creative adjustment where dragging is faster than describing.
+
+Use manual DOM editing for:
+
+- moving titles, captions, product cards, logos, and overlays into position
+- adjusting size, spacing, opacity, color, and other visual properties
+- checking composition balance at an exact timestamp
+- making Figma-like placement tweaks
+
+Use agents for:
+
+- creating scenes from scratch
+- refactoring repeated visual patterns
+- wiring GSAP timelines
+- fixing broken timing, layout overflow, or render errors
+- turning a manual visual tweak into reusable, clean HTML/CSS
+
+After manual DOM edits, ask the agent to inspect the diff and keep the source clean:
+
+```
+I moved the hero title and resized the CTA manually in Studio. Inspect the changes, clean up the CSS if needed, then run lint and validate.
+```
+
+## CLI Commands Editors Use Most
+
+| Command | Use it for |
+| --- | --- |
+| `npx hyperframes init my-video` | Create a new project |
+| `npx hyperframes init my-video --example warm-grain` | Start from a visual template |
+| `npx hyperframes init my-video --video source.mp4` | Import video and generate captions from the source audio |
+| `npx hyperframes capture https://example.com` | Capture a website as source material for a video |
+| `npx hyperframes preview` | Open the live Studio preview |
+| `npx hyperframes lint` | Catch structural mistakes before preview or render |
+| `npx hyperframes validate` | Run the composition in headless Chrome to catch runtime errors |
+| `npx hyperframes inspect` | Find text overflow and layout problems across the timeline |
+| `npx hyperframes snapshot --at 1,3,5` | Save PNG checks at exact timestamps |
+| `npx hyperframes render --output final.mp4` | Render the video |
+| `npx hyperframes publish` | Upload the project and get a shareable HyperFrames URL |
+| `npx hyperframes doctor` | Check Node.js, FFmpeg, Chrome, Docker, and other dependencies |
+| `npx hyperframes docs` | Open local CLI docs |
+| `npx hyperframes upgrade` | Check for a newer CLI version |
+
+## Timing Cheatsheet
+
+Every visible timed layer should usually be a clip:
+
+```html
+<h1
+  class="clip"
+  data-start="0"
+  data-duration="3"
+  data-track-index="0"
+>
+  Opening title
+</h1>
+```
+
+Use these attributes like timeline controls:
+
+| Attribute | Video editor meaning |
+| --- | --- |
+| `data-start` | When the layer starts |
+| `data-duration` | How long the layer stays active |
+| `data-track-index` | Timeline track number |
+| `data-media-start` | Offset into a media file |
+| `data-volume` | Audio volume for an audio or video clip |
+| `data-composition-src` | Nested scene or reusable overlay |
+
+For GSAP animation, register one paused timeline per composition:
+
+```html
+<script>
+  window.__timelines = window.__timelines || {};
+  const tl = gsap.timeline({ paused: true });
+
+  tl.from("#title", { opacity: 0, y: 40, duration: 0.6 });
+  tl.set({}, {}, 5); // keeps the timeline at least 5 seconds long
+
+  window.__timelines["main"] = tl;
+</script>
+```
+
+<Warning>
+  If a video cuts off early, check that the GSAP timeline is at least as long as the intended edit. The final `tl.set({}, {}, 5)` pattern is the fix.
+</Warning>
+
+## Render Presets
+
+| Goal | Command |
+| --- | --- |
+| Fast iteration | `npx hyperframes render --quality draft --output draft.mp4` |
+| Review link | `npx hyperframes render --quality standard --output review.mp4` |
+| Final export | `npx hyperframes render --quality high --fps 30 --output final.mp4` |
+| Transparent overlay | `npx hyperframes render --format webm --output overlay.webm` |
+| Deterministic output | `npx hyperframes render --docker --output final.mp4` |
+
+Use WebM for transparent overlays, captions, and lower thirds. Use `--docker` when you need pixel-consistent output across different machines.
+
+## Publish and Share
+
+Use `publish` when you want to share the editable project, not just the rendered MP4:
+
+```bash
+npx hyperframes publish
+```
+
+Publish zips the current project, uploads it, and prints a stable `hyperframes.dev` URL. The URL includes a claim token so the recipient can open it, claim the project, and continue editing in the web app.
+
+```bash
+npx hyperframes publish ./my-video   # publish a specific folder
+npx hyperframes publish --yes        # skip the confirmation prompt in scripts
+```
+
+Publish expects an `index.html` at the project root. It ignores `.git`, `node_modules`, `dist`, `.next`, and `coverage`.
+
+## What Agent Browser Is
+
+`agent-browser` is a browser automation tool for AI agents. It opens Chrome, navigates to your preview, clicks controls, reads page state, and captures screenshots. It is how an agent proves the video preview actually works instead of only saying the code looks right.
+
+Typical verification flow:
+
+```bash
+agent-browser open http://localhost:3002
+agent-browser snapshot -i
+agent-browser screenshot --screenshot-dir ./qa
+```
+
+Use it when you want the agent to open the HyperFrames Studio preview, play or scrub the video, click timeline controls, inspect visible UI text, capture screenshots for review, or record proof of a tested flow.
+
+For editor-facing changes, keep `npx hyperframes preview` running, then have the agent use `agent-browser` against the local preview URL.
+
+## Quick Fixes
+
+| Problem | Command or check |
+| --- | --- |
+| Preview will not start | `npx hyperframes doctor` |
+| Port already in use | `npx hyperframes preview --port 4567` |
+| Render fails | `npx hyperframes lint` then `npx hyperframes validate` |
+| Need exact frame checks | `npx hyperframes snapshot --at 1,2.5,5` |
+| Text overflows in the frame | `npx hyperframes inspect` |
+| Final render is too slow | Try `--quality draft`, reduce image sizes, or lower `--fps` |
+| Need to share editable project | `npx hyperframes publish` |
+
+<CardGroup cols={2}>
+  <Card title="Prompt Guide" icon="wand-magic-sparkles" href="/guides/prompting">
+    How to direct AI agents to build better videos
+  </Card>
+  <Card title="Timeline Editing" icon="timeline" href="/guides/timeline-editing">
+    Timing, tracks, and GSAP timeline patterns
+  </Card>
+  <Card title="Common Mistakes" icon="circle-exclamation" href="/guides/common-mistakes">
+    Pitfalls the linter can't catch
+  </Card>
+  <Card title="CLI Reference" icon="terminal" href="/packages/cli">
+    Full command reference
+  </Card>
+</CardGroup>