agentcut 0.2.3 → 0.2.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/dist/studio/tools.js +17 -2
  2. package/dist/studio/tools.js.map +1 -1
  3. package/dist/studio/workspace.js +4 -0
  4. package/dist/studio/workspace.js.map +1 -1
  5. package/package.json +1 -1
  6. package/template/components/CATALOG.md +52 -0
  7. package/template/components/README.md +70 -61
  8. package/template/components/STYLES.md +2 -0
  9. package/template/components/catalog.json +477 -0
  10. package/template/components/catalog.ts +4 -0
  11. package/template/components/cinematic/Cinematic.tsx +1139 -0
  12. package/template/components/cinematic/Device3D.tsx +299 -0
  13. package/template/components/cinematic/devices3d/display-model.ts +184 -0
  14. package/template/components/cinematic/devices3d/iphone-model.ts +643 -0
  15. package/template/components/cinematic/devices3d/macbook-model.ts +553 -0
  16. package/template/components/cinematic/devices3d/models.ts +612 -0
  17. package/template/components/cinematic/devices3d/runtime.ts +258 -0
  18. package/template/components/cinematic/math.ts +100 -0
  19. package/template/components/dot-trace-title/DotTraceTitle.tsx +181 -0
  20. package/template/components/dot-trace-title/meta.json +51 -0
  21. package/template/components/generate/GenerateReveal.tsx +381 -0
  22. package/template/components/index.ts +36 -0
  23. package/template/components/lib.ts +18 -6
  24. package/template/components/loops/LoopCanvas.tsx +132 -0
  25. package/template/components/loops/engine.ts +184 -0
  26. package/template/components/loops/library.ts +667 -0
  27. package/template/components/loops/library2.ts +777 -0
  28. package/template/components/motion-loop/MotionLoop.tsx +37 -0
  29. package/template/components/motion-loop/meta.json +312 -0
  30. package/template/runtime/composition.tsx +927 -920
  31. package/template/skill/SKILL.md +20 -3
  32. package/template/skill/references/browser-export.md +61 -61
  33. package/template/skill/references/cinematic.md +171 -0
  34. package/template/skill/references/loops.md +151 -0
  35. package/template/skill/references/performance.md +81 -0
@@ -64,7 +64,8 @@ projects/<slug>/
64
64
  5. **Sound** (`references/sound.md`): voice and music first, then SFX on picture cues. You cannot hear;
65
65
  never say a sound fits without `agentcut_listen_*` numbers, and write them in notes.md.
66
66
  6. **Review**: `agentcut_contact_sheet` across the whole video for each variant, and
67
- `agentcut_listen_critique` for the mix. Fix what they show.
67
+ `agentcut_listen_critique` for the mix. Fix what they show. `agentcut_preview_check` every heavy scene
68
+ so the preview plays smoothly (`references/performance.md`); never at the cost of render quality.
68
69
  7. **Hand off** in a few lines: what's where, what's easy to tweak by hand. Export only when the user
69
70
  asks (`agentcut_export`); report the paths and measured loudness.
70
71
 
@@ -74,7 +75,7 @@ projects/<slug>/
74
75
 
75
76
  The export and the captures use Remotion's web renderer, which draws a subset of CSS:
76
77
  - No `z-index` (order elements back to front), no `mix-blend-mode`, `backdrop-filter`, inset shadows,
77
- `object-position`, CSS 3D `perspective`.
78
+ `object-position`, CSS 3D `perspective` (for 3D use the cinematic `Stage` from `agentcut/components`).
78
79
  - Backgrounds: `linear-gradient` only. For radial glows use `<RadialGlow>` from `agentcut`.
79
80
  - `<Audio>`/`<Video>` from `@remotion/media` (never `OffthreadVideo`/`Html5Audio`), `<Img>` from remotion.
80
81
  - Fonts come from `project.json` (Google specs or local files in assets/fonts).
@@ -118,6 +119,21 @@ When a user supplies a reference video URL or asks to adapt its style, hook, cap
118
119
  read `references/style-spy.md`. The helper imports references (`agentcut_import_reference`) and
119
120
  samples their frames; the studio shows them automatically.
120
121
 
122
+ ## Motion loops and variety
123
+
124
+ No video sits on a dead flat colour, and no two videos look alike. Read `references/loops.md` before
125
+ choosing backgrounds: 44 seamless brand-coloured loops (backgrounds, shapes, symmetry, morphing, games,
126
+ physics, generative) (`motion-loop` clips or `<LoopCanvas>` in
127
+ scenes), the "generated by an agent" effects (`dot-trace-title`, `GenerateReveal`), how to build the
128
+ palette from the brand, the variety rules, and how to write and save new loops to the workspace library.
129
+
130
+ ## Cinematic Mode
131
+
132
+ When a message starts with "Cinematic:" or "Cinematic, another take:", or the user wants product shots with a 3D camera (tilted
133
+ screens, depth of field, UI lifting off the screen, device mockups, Apple-style launch shots), read
134
+ `references/cinematic.md`. Scenes use the toolkit in `agentcut/components` (`Stage`, `Screen`, `Lift`,
135
+ `Plane`, `Backdrop`); follow the direction the message gives and pass its quality gate.
136
+
121
137
  ## Working with the user
122
138
 
123
139
  The user edits the same timeline by hand while you work, and points at things instead of describing
@@ -137,10 +153,11 @@ scripts from the project folder (e.g. composing music or fetching CC0 sounds, se
137
153
  |---|---|
138
154
  | `agentcut_status` | first, and after every edit (build + validation) |
139
155
  | `agentcut_create_project` / `_open_project` | new video / switch project |
140
- | `agentcut_capture_frames` | look at specific frames (same renderer as export) |
156
+ | `agentcut_capture_frames` | look at specific frames (same renderer as export); `region` + `scale: 2` for a sharp crop |
141
157
  | `agentcut_contact_sheet` | stills sheet of the whole video before export |
142
158
  | `agentcut_media_info` | exact durations (frames) for clips |
143
159
  | `agentcut_transcribe` | word timings for voice / lyrics |
160
+ | `agentcut_preview_check` | does the live preview keep up? dropped frames per clip (see `references/performance.md`) |
144
161
  | `agentcut_import_reference` | Style Spy: a reference video plus sampled frames (see `references/style-spy.md`) |
145
162
  | `agentcut_voice_options` / `_generate_voice` | voice-overs with the user's own provider (see `references/sound.md`) |
146
163
  | `agentcut_components` | the component library: search, then `id` for props and a ready clip |
@@ -1,61 +1,61 @@
1
- # Browser export: what the renderer can draw
2
-
3
- Captures (`agentcut_capture_frames`, `_contact_sheet`) and the export use Remotion's web renderer
4
- (`@remotion/web-renderer`, encoding with Mediabunny). It walks the DOM and draws each element onto a canvas,
5
- so it supports a **subset** of CSS. The live preview (Remotion Player) is a normal browser page and shows
6
- everything — so a scene can look right in the preview and wrong in the export. Always judge by captures.
7
-
8
- ## Replace these
9
-
10
- | Don't use | Use instead |
11
- |---|---|
12
- | `z-index` | order elements back to front in the DOM (later = on top) |
13
- | `background: radial-gradient(…)` / `conic-gradient` | `<RadialGlow x y radius color opacity />` from `agentcut`, or an inline `<svg>` with `<radialGradient>` |
14
- | `background-image: url()` | `<Img>` or an image clip |
15
- | `mix-blend-mode`, `background-blend-mode` | pre-blended colors, opacity, or an SVG with the effect baked in |
16
- | `backdrop-filter` (glass blur) | a semi-opaque fill + a blurred copy of the background behind it |
17
- | `box-shadow: inset …`, shadow spread | an inner element with a gradient/border, or an outer shadow without spread |
18
- | `object-position` | position the `<Img>` inside an `overflow: hidden` box with transforms |
19
- | `perspective`, `transform-style: preserve-3d` | 2D transforms (scale/skew/rotate) faking depth |
20
- | `mask-image` with radial/SVG masks | linear-gradient masks, or `clip-path` shapes (`inset`, `circle`, `polygon`) |
21
- | `clip-path: url(#svgClip)` | `clip-path: polygon(…)` / `circle(…)` |
22
- | `OffthreadVideo`, `Html5Video`, `Html5Audio` | `<Video>` / `<Audio>` from `@remotion/media` (or video/audio clips) |
23
- | `writing-mode`, wavy `text-decoration` | rotated boxes, SVG paths |
24
- | fonts from CSS `@import` / `<link>` in scenes | `project.json` → `fonts` |
25
-
26
- Supported and safe: flexbox/grid layout, `transform` (2D), `opacity`, `filter` (blur, brightness…; not in
27
- Safari), `linear-gradient` backgrounds, `border-radius`, borders, outer `box-shadow`, `text-shadow`,
28
- `clip-path` shapes, inline SVG (gradients, paths, filters inside the SVG), `<Img>`, canvas.
29
-
30
- Text inside SVG `<text>` or `foreignObject` doesn't get project fonts: prefer HTML text.
31
-
32
- ## Checklist after writing a scene
33
-
34
- 1. `agentcut_status` → no build errors.
35
- 2. Capture its entrance, hold and exit in both variants.
36
- 3. Compare with what you meant. Missing glow, wrong stacking, hard edges where a blend was → one of the
37
- properties above.
38
- 4. If an effect can't be done within these rules and the user wants it, say so: the "Render on this
39
- computer" export (classic Remotion renderer) draws full CSS, but the captures won't show it.
40
-
41
- Shader transitions (`@remotion/transitions` zoom-blur, film-burn, …) use WebGL: they render in the browser
42
- but slowly; check a capture of a transition frame before relying on one.
43
-
44
- ## WebGL / three.js scenes
45
-
46
- - Create the `<canvas>` **inside** the effect (`document.createElement("canvas")`, append it to a container
47
- `<div ref>`), and remove it in the cleanup. Never call `renderer.forceContextLoss()` on a canvas React
48
- keeps: the dev server mounts every component twice, and the second mount gets a dead context
49
- ("Cannot read properties of null (reading 'precision')").
50
- - `preserveDrawingBuffer: true` so captures and the export can read the pixels; render synchronously for the
51
- current frame (`useCurrentFrame()`), never in `requestAnimationFrame`.
52
- - One renderer per scene, sized to the composition (`useVideoConfig()`), `setPixelRatio(1)`. Dispose
53
- geometries, materials, textures and the renderer in the cleanup. Browsers allow ~16 live WebGL contexts.
54
- - Keep the live preview smooth. The Player draws 30 frames a second on the page's main thread; when a
55
- frame takes longer, it skips frames, and the user sees stutters and jumps. Use `usePreviewQuality()` from
56
- `agentcut`: `renderer.setPixelRatio(q.pixelRatio)`, `shadow.mapSize.set(q.shadowMapSize, …)`,
57
- and redraw big canvas textures (`needsUpdate`) only every `q.textureEvery` frames. Captures and the export
58
- always get full quality.
59
- - Call `renderer.compile(scene, camera)` at the end of setup so shaders compile while the scene is
60
- premounted (clips mount 1 s early in the preview), not on its first visible frame.
61
- - Capture a frame of every 3D scene in both variants before moving on.
1
+ # Browser export: what the renderer can draw
2
+
3
+ Captures (`agentcut_capture_frames`, `_contact_sheet`) and the export use Remotion's web renderer
4
+ (`@remotion/web-renderer`, encoding with Mediabunny). It walks the DOM and draws each element onto a canvas,
5
+ so it supports a **subset** of CSS. The live preview (Remotion Player) is a normal browser page and shows
6
+ everything — so a scene can look right in the preview and wrong in the export. Always judge by captures.
7
+
8
+ ## Replace these
9
+
10
+ | Don't use | Use instead |
11
+ |---|---|
12
+ | `z-index` | order elements back to front in the DOM (later = on top) |
13
+ | `background: radial-gradient(…)` / `conic-gradient` | `<RadialGlow x y radius color opacity />` from `agentcut`, or an inline `<svg>` with `<radialGradient>` |
14
+ | `background-image: url()` | `<Img>` or an image clip |
15
+ | `mix-blend-mode`, `background-blend-mode` | pre-blended colors, opacity, or an SVG with the effect baked in |
16
+ | `backdrop-filter` (glass blur) | a semi-opaque fill + a blurred copy of the background behind it |
17
+ | `box-shadow: inset …`, shadow spread | an inner element with a gradient/border, or an outer shadow without spread |
18
+ | `object-position` | position the `<Img>` inside an `overflow: hidden` box with transforms |
19
+ | `perspective`, `transform-style: preserve-3d` | the cinematic `Stage` / `Plane` from `agentcut/components` (one `matrix3d()` per element, drawn through WebGL; see `cinematic.md`), or 2D transforms faking depth |
20
+ | `mask-image` with radial/SVG masks | linear-gradient masks, or `clip-path` shapes (`inset`, `circle`, `polygon`) |
21
+ | `clip-path: url(#svgClip)` | `clip-path: polygon(…)` / `circle(…)` |
22
+ | `OffthreadVideo`, `Html5Video`, `Html5Audio` | `<Video>` / `<Audio>` from `@remotion/media` (or video/audio clips) |
23
+ | `writing-mode`, wavy `text-decoration` | rotated boxes, SVG paths |
24
+ | fonts from CSS `@import` / `<link>` in scenes | `project.json` → `fonts` |
25
+
26
+ Supported and safe: flexbox/grid layout, `transform` (2D), `opacity`, `filter` (blur, brightness…; not in
27
+ Safari), `linear-gradient` backgrounds, `border-radius`, borders, outer `box-shadow`, `text-shadow`,
28
+ `clip-path` shapes, inline SVG (gradients, paths, filters inside the SVG), `<Img>`, canvas.
29
+
30
+ Text inside SVG `<text>` or `foreignObject` doesn't get project fonts: prefer HTML text.
31
+
32
+ ## Checklist after writing a scene
33
+
34
+ 1. `agentcut_status` → no build errors.
35
+ 2. Capture its entrance, hold and exit in both variants.
36
+ 3. Compare with what you meant. Missing glow, wrong stacking, hard edges where a blend was → one of the
37
+ properties above.
38
+ 4. If an effect can't be done within these rules and the user wants it, say so: the "Render on this
39
+ computer" export (classic Remotion renderer) draws full CSS, but the captures won't show it.
40
+
41
+ Shader transitions (`@remotion/transitions` zoom-blur, film-burn, …) use WebGL: they render in the browser
42
+ but slowly; check a capture of a transition frame before relying on one.
43
+
44
+ ## WebGL / three.js scenes
45
+
46
+ - Create the `<canvas>` **inside** the effect (`document.createElement("canvas")`, append it to a container
47
+ `<div ref>`), and remove it in the cleanup. Never call `renderer.forceContextLoss()` on a canvas React
48
+ keeps: the dev server mounts every component twice, and the second mount gets a dead context
49
+ ("Cannot read properties of null (reading 'precision')").
50
+ - `preserveDrawingBuffer: true` so captures and the export can read the pixels; render synchronously for the
51
+ current frame (`useCurrentFrame()`), never in `requestAnimationFrame`.
52
+ - One renderer per scene, sized to the composition (`useVideoConfig()`), `setPixelRatio(1)`. Dispose
53
+ geometries, materials, textures and the renderer in the cleanup. Browsers allow ~16 live WebGL contexts.
54
+ - Keep the live preview smooth. The Player draws 30 frames a second on the page's main thread; when a
55
+ frame takes longer, it skips frames, and the user sees stutters and jumps. Use `usePreviewQuality()` from
56
+ `agentcut`: `renderer.setPixelRatio(q.pixelRatio)`, `shadow.mapSize.set(q.shadowMapSize, …)`,
57
+ and redraw big canvas textures (`needsUpdate`) only every `q.textureEvery` frames. Captures and the export
58
+ always get full quality.
59
+ - Call `renderer.compile(scene, camera)` at the end of setup so shaders compile while the scene is
60
+ premounted (clips mount 1 s early in the preview), not on its first visible frame.
61
+ - Capture a frame of every 3D scene in both variants before moving on.
@@ -0,0 +1,171 @@
1
+ # Cinematic Mode: product shots with a real camera
2
+
3
+ A **Cinematic** message hands you screenshots and/or screen recordings and a **direction** (mood, camera
4
+ energy, signature move, palette, type, transitions) rolled at random by the studio. Your job: a short,
5
+ premium product film in the spirit of Apple launch shots — screens tilted in 3D, lens blur,
6
+ UI pieces lifting off the glass, light sweeping across, a camera that always moves with intent.
7
+
8
+ Every take must look different (follow the direction you were given, don't fall back to your favourite
9
+ moves) and every take must look expensive (the quality gate below is not optional).
10
+
11
+ ## The toolkit (`agentcut/components`)
12
+
13
+ ```tsx
14
+ import { useCurrentFrame } from "remotion";
15
+ import { asset, type SceneProps } from "agentcut";
16
+ import { Backdrop, Device3D, Floor, Glare, Group, Lift, Plane, PlaneVideo, Screen, Stage, progress, useStage } from "agentcut/components";
17
+ ```
18
+
19
+ It is a real 3D camera: each plane gets one `matrix3d()`, which the preview and the browser export both
20
+ draw (the export through WebGL). **Never** add CSS `perspective`, `preserve-3d` or your own 3D transforms
21
+ around it; place things with the toolkit's props.
22
+
23
+ **Draw order is JSX order, not depth.** Nothing sorts by z: write the Stage's children back to front
24
+ (backdrop and loops, floor, far planes, the device, lifts and titles in front). A `Device3D` is one
25
+ full-frame layer, so a Plane written after it covers it wherever they overlap, whatever their z.
26
+
27
+ **World units**: px at 1080 on the short side (`useStage().u` scales to the frame). `x` right, `y` down,
28
+ `z` toward the viewer; (0,0,0) is the frame center. `useStage()` → `{ width, height, u, vertical, worldWidth,
29
+ worldHeight }`: size screens from `worldWidth` so both variants frame well (`vertical` → smaller screens,
30
+ narrower moves).
31
+
32
+ - `<Stage camera={pose | keys} float motionBlur seed background>` — everything 3D goes inside. `camera` is
33
+ one pose or keyframes `{ at: frame, ...pose, ease }`; keys carry values forward, `ease` is the move
34
+ *into* that key: `linear`, `in`, `out`, `inOut` (default), `expo` (premium glide), `back` (small
35
+ overshoot), `whip` (slow–very fast–slow). Pose:
36
+ - `x, y, z`: the point the camera looks at. `zoom`: 1 = things at z 0 at their size, 2 = twice as close.
37
+ - `tilt` (> 0: the camera rises and looks down, so floors and laptop decks show their top), `turn`
38
+ (> 0: the camera orbits left, the right side recedes), `roll` (> 0 clockwise), all degrees. To lay a
39
+ flat screen back like a laptop on a desk, tilt the **Screen/Group** (`tilt 25–55`) and keep the camera
40
+ tilt small (5–20) with some `turn` and `roll`.
41
+ - `fov`: 15–25 flat telephoto (default 24, product look), 35 natural, 50–70 dramatic close-ups.
42
+ - `focus`: a world point `[x, y, z]` (put it ON the thing that matters) or px toward the camera from
43
+ the target. `aperture`: 0 none, 0.4 subtle, 1 strong, 2 macro. Focus and aperture animate: a rack
44
+ focus is two keys with different `focus` points.
45
+ - `shiftX`, `shiftY`: move the subject off-center (fractions of the frame) to leave room for a title.
46
+ - `float` 0–1: handheld drift (0.3–0.6 on holds keeps them alive). `motionBlur` 0–1: blur on fast moves.
47
+ - `<Screen kind src width ...placement>` — a screenshot (`src`), a screen recording (`video`, with
48
+ `videoProps` for `volume`, `loop`, `trimBefore`…) or `children` (live React UI) in a device. `kind`: `browser` (+ `url`), `macbook`, `iphone`, `ipad`,
49
+ `monitor`, `none`. `width` is the SCREEN width. Set `aspect` to the screenshot's width/height when it
50
+ differs from the device (or `imageAspect` + `scroll` 0→1 to scroll a tall page). `finish`: `black` /
51
+ `silver` (hardware), `light` / `dark` (browser). Extras: `shadow` (0.7), `reflection` (0–0.5 on dark
52
+ floors), `rim` (glass edge light), `glare` (0→1 sweep position), `dof={false}` to keep it sharp.
53
+ - `<Device3D model src size lifts ...placement>` — **real 3D hardware**, and the default for every phone,
54
+ laptop and desktop shot (three.js, drawn through the same camera, studio-lit with real reflections):
55
+ `model` `iphone` (iPhone 16 Pro Max model), `macbook` (keyboard, trackpad, opening lid: animate
56
+ `lidAngle` 0→110), `display` (Studio Display on its foot), `iphone-classic`. `src` is the screenshot
57
+ on its screen (it covers the screen; a taller one shows its top, `scroll` 0→1 moves down it). `size` =
58
+ largest dimension in world px (defaults 760 / 1250 / 1150), `finish` `silver` `starlight` `space-gray`
59
+ `midnight` `black` (MacBook, display), `exposure`, `shadow`. `lifts`: pieces of the screenshot that rise
60
+ off the device's screen, `[{ box: [x, y, w, h] (fractions of the SCREENSHOT), z, scale, radius }]` —
61
+ they follow the screen's angle, even on an opening lid. Devices blur as a whole with the lens. Credit
62
+ the iPhone model in the hand-off: "iPhone 16 Pro Max model by MajdyModels, CC BY 4.0".
63
+ - **Never** use the flat `Screen` `iphone` / `macbook` / `ipad` / `monitor` frames when the shot shows the
64
+ device: they look like clip-art next to the 3D models. Flat `Screen` is for browser windows
65
+ (`kind="browser"`), frameless UI (`kind="none"`), giant readable close-ups where the hardware is off
66
+ frame, and tall pages you fly over with `scroll`.
67
+ - `<Lift src box kind width z scale ...>` — a region of a FLAT Screen rising out of it (for 3D devices use
68
+ `Device3D`'s `lifts`): put it in the same `<Group>` as its `<Screen>` with the same `kind`, `width`, `aspect`. `box` = `[x, y, w, h]` in
69
+ fractions of the screen picture. Animate `z` 0 → 40–140 and `scale` 1 → 1.03–1.15; it casts a real
70
+ shadow on the screen. With the camera looking down (tilt > 0) a lift also travels up the frame.
71
+ - `<Group ...placement>` moves/turns screens and their lifts together. `<Plane width height ...>` is the
72
+ raw surface: cards, text, logos, a second screenshot, anything in depth (`radius`, `background`,
73
+ `shadow`, `shadowDepth`, `reflection`, `rim`, `dof`, `blur` for extra softness in world px).
74
+ - A Plane with lens blur or a reflection draws its content more than once (blurred and mirrored copies
75
+ under the sharp one). Videos inside a Plane or as Screen `children` must be `<PlaneVideo>` (same props as
76
+ `@remotion/media`'s `<Video>`): only the sharp copy plays sound. Your own heavy content can check
77
+ `usePlaneLayer().copy` and draw less in the copies.
78
+ - **Backgrounds are motion loops first** (`references/loops.md`): `<LoopCanvas loop … />` as the
79
+ Stage's first child, or on a big Plane far behind (`z -600…-1200`) so it parallaxes with the camera.
80
+ Rotate loops and tones across shots; add a transparent shape loop as an accent. `<Backdrop>` is for
81
+ quiet shots where the background should disappear.
82
+ - `<GenerateReveal …>` as a flat Screen's children: the UI builds itself on the 3D screen like an agent is
83
+ generating it (see `references/loops.md` › Generated by an agent). A strong hook or reveal shot.
84
+ - `<Backdrop look>`: `studio` (dark, accent glow), `light` (Apple white), `aurora`, `spotlight`, `mesh`,
85
+ `solid`; `color`, `accent`, `accent2`, `glowX/Y` (animate slowly), `intensity`. First child of the Stage.
86
+ - `<Floor y size spacing color opacity glow near>`: a receding grid floor (reads best with tilt 15–35). It is
87
+ drawn in tiles, so the part that passes the lens drops out on its own.
88
+ - `<Glare progress angle width strength>` inside any Plane; `progress(frame, from, to, ease)` → 0…1.
89
+ - Placement (Screen, Plane, Group, Lift offsets): `x y z tilt turn roll scale`.
90
+
91
+ ## Workflow
92
+
93
+ 1. **Look at every file.** Open each screenshot (Read) and `agentcut_media_info` for size; for a
94
+ recording, capture or sample frames. Find 3–6 **hero regions** per screen (the number that matters,
95
+ the button, the chart, the card with the promise) and measure their `box` fractions from the image.
96
+ Write them in notes.md. Read the product's words: they become the titles.
97
+ 2. **Shot list in notes.md** (show it to the user in 2–3 lines): 4–7 shots, 1.5–4 s each, for the
98
+ requested length. Each line: subject, camera move, signature effect, focus target, text, frames. Arc:
99
+ **reveal** (the whole product in a bold angle) → **details** (lifts, rack focus, push-ins on hero
100
+ regions, one per shot) → **payoff** (hero angle again, wider or rotated, then the name / CTA).
101
+ 3. **Build one shot per scene file** (`scenes/Cine01Reveal.tsx` …), one clip each on a "Cinematic" track;
102
+ words, colors and key timings in `props` so the user can tune them. Titles: a library text component
103
+ on a track above, or HTML text on a `Plane` in the stage (text in depth, with blur, is a premium look).
104
+ 4. **Music**: `agentcut_music_options` for the direction's mood, beats with `agentcut_analyze_audio`;
105
+ land cuts and lift peaks on beats, whips on a downbeat. One whoosh per whip, a soft tick per lift.
106
+ 5. **Quality gate** (below), then hand off.
107
+
108
+ ## Shot vocabulary (adapt the numbers, combine, invent)
109
+
110
+ | Move | Recipe |
111
+ |---|---|
112
+ | Tilt reveal | `<Group tilt={34}>` around the Screen; camera from `zoom 0.75 tilt 14 turn -26 roll 10` to `zoom 1.05 tilt 10 turn -16 roll 8`, `expo`, 70–110 f |
113
+ | Hero push | same angle, zoom +15–25 % over the shot, `inOut`, `float 0.4` |
114
+ | Rack focus | camera still or drifting; `focus` from region A to B over 20–30 f, `aperture 0.9–1.3` |
115
+ | Lift-out | `Device3D` `lifts` (or `Lift` on a flat Screen) z 0→80–140, scale →1.08, `back` or `expo`, focus moves to the lift |
116
+ | Push to detail | zoom 1→2.2–3 on a hero region (`x, y` = its world center), aperture up as you go in |
117
+ | Fly-over | low `tilt 55–65`, camera `y` travels down the page, `fov 35`, long screenshot with `scroll` |
118
+ | Orbit | `Device3D` iPhone: camera `turn` −35 → +25, `tilt` 5–12, `fov 28–32`, a dark backdrop with a glow behind |
119
+ | Laptop opens | `Device3D macbook` with `lidAngle` 0→110 over 40–60 f (`expo`), camera `tilt 15–25` pushing in |
120
+ | Whip pan | hold, then `x` jumps to the next subject in 12–16 f with `whip`, `motionBlur 1`; cut or keep going |
121
+ | Drop-in | device (Screen or Device3D) starts `y −900 tilt 25`, lands with `back`; camera tiny shake via `float` |
122
+ | Exploded view | 3–5 Lifts at increasing z (40, 90, 140…) with small `turn`; camera turns 15° to show depth |
123
+ | Spotlight | `Backdrop spotlight` glow follows the hero (`glowX/Y`), aperture high, others fall into blur |
124
+ | Split screens | two Screens (desktop + phone) at different z; focus pulls from one to the other |
125
+ | Glass sweep | `glare` 0→1 over 40–60 f on a hold; `rim 0.6` |
126
+ | Dolly zoom | zoom up while fov goes down (or the reverse): the background perspective warps, subject holds |
127
+ | Title in depth | a Plane with the headline at z 150–300 in front of the screen, focus on it, screen soft behind |
128
+
129
+ ## Brand colours and variety
130
+
131
+ Find the brand colours first (logo, UI, website) and build the palette from them
132
+ (`references/loops.md` › Brand palette). Every take must differ in loop choice, tone rotation, shapes
133
+ and type, not only in camera moves: write the rotation in the shot list, and check notes.md for what
134
+ the last take used.
135
+
136
+ ## Taste rules
137
+
138
+ - **The hero is always sharp.** Put `focus` on it; blur is for what's around it. Never blur text the
139
+ viewer must read during a hold.
140
+ - One idea per shot, one signature effect per shot. Motion never stops: every hold drifts (`float`, slow
141
+ zoom), and moves start/stop with eased keys.
142
+ - Angles between 8° and 45°; mostly telephoto (fov 18–30). Extreme angles only on whips and reveals.
143
+ - Depth everywhere: something nearer than the screen (a lift, a title, a second device) and something
144
+ behind it (backdrop glow, floor). Flat-looking frames fail the gate.
145
+ - Never show the screen's edge cutting through the frame at an awkward 2–3 %: either full in frame with
146
+ air, or confidently cropped (≥ 15 % off frame).
147
+ - Text: 2–6 words per title, big, with contrast against the backdrop; on screen ≥ 1.2 s.
148
+ - Both variants: re-frame per variant with `useStage().vertical` (smaller widths, narrower x travel,
149
+ more vertical moves on mobile), never just let the wide shot crop.
150
+ - Contrast pairs that read premium: light UI on `studio`/`spotlight`; dark UI on `light` or `mesh`.
151
+
152
+ ## Quality gate (before you say it's done)
153
+
154
+ For every shot: `agentcut_capture_frames` at the entrance, the middle and the exit, in wide AND mobile.
155
+ Open them and check:
156
+ 1. The hero region is sharp and readable; the blur falls off naturally (no hard seams).
157
+ 2. Nothing important is clipped; edges are either clean or boldly cropped.
158
+ 3. There is depth (foreground + background), and the frame isn't empty or flat.
159
+ 4. Titles are readable and don't collide with UI.
160
+ 5. The move has a clear start and end (compare entrance vs exit).
161
+ Then `agentcut_contact_sheet` over the whole video (pacing, variety: no two consecutive shots with the
162
+ same angle and move) and `agentcut_preview_check` (each Plane with lens blur draws several copies; if a
163
+ shot is choppy, lower `aperture` on secondary planes or set `dof={false}` on them, never on the hero in
164
+ the export path). Fix what fails and re-capture. Write what you checked in notes.md.
165
+
166
+ ## Takes
167
+
168
+ "Another take" asks for a new film from the same media with a new direction. Before changing anything,
169
+ copy project.json, layers.json and scenes/ to a new timestamped folder under `.studio/cinematic-takes/`
170
+ (never overwrite one). Then replace the Cinematic track and its scenes: new shot list, new moves, new
171
+ backdrop and type. Reusing the previous take's structure with new colors is a failure.
@@ -0,0 +1,151 @@
1
+ # Motion loops, brand palettes and variety
2
+
3
+ Agentcut ships a library of 44 seamless **motion loops** (all live at agentcut.synteq.app/loops),
4
+ each a pure function of time on a 12 s cycle (the frame at 12 s is the frame at 0 s), drawn from the
5
+ brand's colours. Use them so no video sits on a dead flat colour, and so every video looks different.
6
+
7
+ ## Use one
8
+
9
+ - **As a clip** (the user can edit it in the inspector): component `motion-loop` on a track under the
10
+ content, e.g. `{ "component": "motion-loop", "props": { "loop": "dot-wave", "tone": "light",
11
+ "accent": "#f97316", "accent2": "#ec4899", "seed": 7 } }`. `agentcut_components` with
12
+ `id: "motion-loop"` lists every loop.
13
+ - **Inside a scene** (behind a cinematic Stage, on a card, in a split):
14
+ `import { LoopCanvas } from "agentcut/components"` →
15
+ `<LoopCanvas loop="iso-cubes" accent={brand} accent2={brand2} tone="dark" seed={3} />`. Without
16
+ `width`/`height` it is frame-sized and stretches to its parent, so use it full-frame (or in a box
17
+ with the frame's aspect). In any other box pass that box's size in px, e.g. on a `Plane` (a great
18
+ card in 3D): `<Plane width={800} height={500}><LoopCanvas loop="dot-wave" width={800} height={500} /></Plane>`;
19
+ then it draws at exactly that size and never distorts. Put it first inside `<Stage>` instead of
20
+ `<Backdrop>`, or on a Plane far behind the devices (`z: -800`) so it parallaxes with the camera.
21
+ - Props: `tone` `dark` (deep brand-tinted background, brand motif), `accent` (solid brand colour,
22
+ ink or paper motif), `light` (paper background, ink motif, brand as the second colour); `speed`
23
+ (seamless at any speed inside a clip; a clip that repeats needs length × speed to be a multiple of
24
+ 12 s); `seed` (another layout of the same loop); `transparent` (shapes over footage or a Stage);
25
+ `blur` (motion-blur sub-frames in captures and exports, 4 default for both `motion-loop` and
26
+ `LoopCanvas`, 8 for fast loops, 1 for none; the live preview always draws 1). An unknown `loop` id
27
+ warns in the console and falls back to `gradient-blobs`.
28
+
29
+ ## The library
30
+
31
+ Backgrounds: `perspective-grid` (grid floor streaming to a glowing horizon: tech, retro, gaming),
32
+ `dot-wave` (dots swelling in a diagonal wave: calm product), `flow-lines` (breathing signal lines: data,
33
+ finance), `gradient-blobs` (living mesh gradient: the safe premium backdrop), `stripes-scroll` (bold
34
+ diagonal stripes: loud promos, sport, sales), `concentric-pulse` (rings on the beat: reveals, music),
35
+ `checker-twist` (tiles twisting in a wave: playful, design), `halftone-sweep` (halftone with light
36
+ bands: editorial, print), `terrain-ridges` (ridgelines rolling in: moody, music, night), `starfield-warp`
37
+ (warp streaks: hype, speed), `bokeh-drift` (soft rising lights: dreamy, lifestyle, behind devices),
38
+ `iso-cubes` (isometric blocks rising: infrastructure, dev tools), `ribbon-weave` (thick waving
39
+ ribbons: fluid, consumer), `tile-mosaic` (tiles flipping colour: marketplaces, many features).
40
+
41
+ Symmetry: `kaleidoscope` (8-way mirrored drift: music, festivals, hypnotic), `mandala-bloom` (petal rings
42
+ turning both ways: wellness, elegant), `spirograph` (a pen tracing a spirograph: precision, design),
43
+ `mirror-tiles` (four-way mirrored arc tiles turning: design, architecture), `radial-burst` (retro sunburst:
44
+ announcements, sales, pop).
45
+
46
+ Morphing: `shape-morph` (circle → square → triangle → star with squash: transformation, versatility),
47
+ `morph-grid` (a grid of shapes morphing in a wave: systems, modular), `shape-shuffle` (three shapes
48
+ hopping and becoming each other: choices, onboarding), `metaballs` (liquid blobs merging: fluid, AI).
49
+
50
+ Games: `snake-game` (pixel snake eating food: gaming, retro, 'level up'), `falling-blocks` (blocks stack and
51
+ clear: building, organizing), `pong` (paddles rallying: back-and-forth, versus), `life-gliders`
52
+ (Game of Life gliders: code, dev tools, emergence).
53
+
54
+ Physics: `newtons-cradle` (momentum, cause and effect), `clock-gears` (automation, workflows),
55
+ `liquid-fill` (progress, growth, drinks), `domino-wave` (chain reactions, automation).
56
+
57
+ Generative: `vortex` (particles spiralling into a core: AI, gravity), `lissajous-trail` (a comet tracing
58
+ a Lissajous figure: signals, elegance), `bubble-pop` (bubbles rising and popping: playful, social).
59
+
60
+ Shapes (one centered subject, use `transparent` over other layers): `orbit-rings` (AI, platforms),
61
+ `morph-blob` (assistants, organic), `bouncing-ball` (playful, loading), `spinner-petals` (blooming,
62
+ wellness), `stacked-squares` (layers, structure), `ripple-drop` (impact, calm), `cube-spin`
63
+ (products, blocks), `dna-helix` (science, health, data), `pie-burst` (analytics, sharing),
64
+ `wave-bars` (audio, voice, podcasts).
65
+
66
+ ## "Generated by an agent" effects
67
+
68
+ - `dot-trace-title` (component): a headline traced in dots by a scan line that resolves into the type.
69
+ For AI features, agents, "built for you" moments. Lines take `*starred*` words or a `*starred phrase*`
70
+ for the accent; `size` is a share of the frame's short side (× 0.9), `dot` is px at 1080p (scales).
71
+ - `GenerateReveal` (scenes, from `agentcut/components`): a screenshot or photo builds itself the way an
72
+ agent would generate it: dotted wireframes per UI block (with the agent's cursor), a dotted fill made of
73
+ the image's own pixels, then the real pixels resolve block by block, with an optional agent log. When
74
+ the build ends (`from + duration`) the whole image cross-fades in over ~10 frames, so the end state is
75
+ exactly the screenshot, including areas no box covers.
76
+ `<GenerateReveal src={asset("assets/app.png")} width={1440} height={900} from={0} duration={120}
77
+ boxes={[[0,0,0.16,1],[0.18,0.1,0.79,0.08], …]} log={["Laying out the sidebar", …]} accent={brand} />`
78
+ - `width`/`height`: the box in px; the image covers it (crop like `object-fit: cover`). Inside a
79
+ cinematic `Screen` (as its children) the Screen's `width` and `aspect` define the box: pass
80
+ `width={W} height={W / aspect}` with the same values, or the build won't fill the screen.
81
+ - `boxes`: the UI's blocks `[x, y, w, h]` as fractions of the image in build order; measure them from
82
+ the image like hero regions (values are clamped to 0–1). Leave out for photos (one block).
83
+ - `mode`: `"ui"` (wireframe → dots → pixels) or `"image"` (tone sketch → colour dots → photo).
84
+ - `dot` (pitch in box px, default 9), `accent`, `log` (one line per block reads best; Geist Mono, loaded
85
+ and held for you), `logPosition`, `radius`, `background`.
86
+ - `resolution`: pixel ratio of the dots canvas, default 2 in renders/exports (sharp under a camera
87
+ push-in) and 1 in the live preview; lower it for very large boxes. A Plane's blurred and reflected
88
+ copies draw it at 0.5 automatically.
89
+ - The dotted fill reads the image's pixels, so it needs a same-origin asset (`asset(…)`) or a CORS-enabled
90
+ URL. Otherwise it logs a warning and builds without the dotted fill (wireframes, log and pixel reveal
91
+ still play); it never stops the export. A missing image still fails the render (its `<Img>`).
92
+ Use it once per video, as the hook or the "watch it build" moment.
93
+
94
+ ## Brand palette first
95
+
96
+ 1. Find the brand colours before you design: the logo, the product UI in the screenshots, the
97
+ website, `project.json`. Write them in notes.md: primary, secondary, and the brand's own dark and
98
+ light (often in the UI).
99
+ 2. Build every look from them: `accent` = primary, `accent2` = secondary (or a complement: the primary's
100
+ opposite hue at lower saturation), tone per shot. Text on the loop: ink on `light`, paper on `dark`,
101
+ whichever reads on `accent`.
102
+ 3. Two or three colours per frame, never a rainbow. One accent moment per shot.
103
+
104
+ ## Variety (every video, every take)
105
+
106
+ - Never the same loop twice in a row, and at least three different loops or looks in a 15–30 s video.
107
+ - Alternate tones between shots (dark → light → accent …) or hold one tone and vary the loop: decide,
108
+ then write the rotation in the shot list.
109
+ - Change `seed` when you reuse a loop, and pick loops by mood (the list above), not by habit: before
110
+ you choose, write the two you used in the last video in notes.md (if any) and pick others.
111
+ - Mix layers: a background loop, the hero (screens, devices, type), and sometimes a shape loop as an
112
+ accent (transparent, small, in a corner or behind a title) or kinetic shapes on a Plane in depth.
113
+ - Shape loops are great section openers and end cards: a centered shape with the brand name below it.
114
+
115
+ ## Write a new loop (when nothing fits)
116
+
117
+ Write it in the scene as a draw function and pass it to `LoopCanvas`:
118
+
119
+ ```tsx
120
+ import { LoopCanvas, type LoopDraw } from "agentcut/components";
121
+ const sparks: LoopDraw = (ctx, w, h, t, P, M, seed) => {
122
+ const u = h / 100;
123
+ for (let i = 0; i < 60; i++) {
124
+ const p = M.phase(t, 3, M.rand(i, seed)); // a 3 s cycle, staggered per element
125
+ ctx.fillStyle = M.rgba(i % 4 ? P.fg : P.fg2, 1 - p);
126
+ ctx.beginPath();
127
+ ctx.arc(M.rand(i, 1) * w, h - p * h, u * (0.5 + 2 * M.rand(i, 2)), 0, M.TAU);
128
+ ctx.fill();
129
+ }
130
+ };
131
+ // <LoopCanvas loop={sparks} accent={brand} tone="dark" />
132
+ ```
133
+
134
+ Rules that keep it seamless and premium:
135
+ - The frame depends on `t` only: no `Math.random`, `Date` or state between frames; randomness from
136
+ `M.rand(i, salt)`. Every period divides 12 (1, 1.5, 2, 3, 4, 6, 12) via `M.phase(t, period, offset)`;
137
+ scrolls move whole pattern repeats per period; anything indexed by cycle wraps with `M.mod`.
138
+ - Colours only from `P` (`bg fg fg2 mid accent accent2 paper ink`) with `M.rgba` / `M.mixColor`.
139
+ - Sizes from `u = h / 100` (shapes: `Math.min(w, h) / 100`), counts from `w`, so it works in wide and
140
+ mobile.
141
+ - Designed motion: eases from `M.ease` (`outBack`, `spring`, `inOutCubic`…), anticipation and
142
+ overshoot, short holds; constant speed only for scrolls and streams. `M.win(p, a, b)` chains
143
+ wind-up, action and settle inside a cycle; put the loop point inside a hold.
144
+ - Keep a frame under ~2,000 primitives; glows are radial gradients, never `ctx.filter`.
145
+ - Check it: capture frames inside one cycle and either side of the 12 s point.
146
+
147
+ A loop worth keeping for other videos: save it in the workspace library
148
+ (`library/loops/<name>.ts`, exporting the draw function) with a one-line description at the top, and
149
+ list it in `library/loops/README.md`. Later videos import it by relative path from their scene:
150
+ `import { sparks } from "../../../library/loops/sparks";` (scenes live in `projects/<slug>/scenes/`).
151
+ Read `library/loops/README.md` before writing a new loop: one may already exist.
@@ -0,0 +1,81 @@
1
+ # Preview performance
2
+
3
+ The user watches the live preview, which draws every scene in their browser at playback speed. A scene
4
+ that takes too long per frame makes the preview skip frames (choppy) and can freeze the tab while you
5
+ capture frames. The export doesn't skip: it renders every frame at full quality. So:
6
+
7
+ **Never lower what the render shows to make the preview smoother.** No lower resolution, fewer
8
+ elements on screen, skipped frames, softer images or simpler motion. Every change below must render
9
+ the same frames as before (check with captures); when one can't, keep the look and tell the user that
10
+ part previews choppy but exports perfectly.
11
+
12
+ ## Measure
13
+
14
+ - `agentcut_preview_check` (from/to in frames) plays a range muted in the user's preview and returns
15
+ per visual clip: frames played and dropped, loading stalls, the longest freeze, the most DOM elements
16
+ the clip drew, and a verdict: `smooth`, `choppy` from 20 % dropped, `heavy` from 40 % (and at least 6
17
+ dropped frames); a freeze over a second or more than 0.5 s of stalls also counts as slow. It takes as
18
+ long as the range plays: check the clip you changed, not the whole video every time. One check at a
19
+ time; it stops if the user pauses or seeks.
20
+ - `slowClips` lists the likeliest cause first. `sharesDropsOnly` marks a clip (often text or captions)
21
+ that only sits on top of a slower one: fix the other one. `slowToMount` means the clip drops frames in
22
+ the second before it starts, while it mounts early: its setup work is heavy (see rule 4), even when it
23
+ plays fine afterwards.
24
+ - `agentcut_status` → `page.previewPerformance` has the latest check (`lastCheck`) and the user's own
25
+ playback (`playback`). `current: false` means it was measured on an older build.
26
+ - Run a check after building or changing a heavy scene (walls and grids, hundreds of elements, image
27
+ sequences, big blurs, generated images) and before you say you're done. A first run includes loading
28
+ (stalls); run it again to see steady playback. A machine's own jitter varies between runs: act on a
29
+ `choppy` only when a second run agrees.
30
+
31
+ ## Make it lighter (same pixels)
32
+
33
+ 1. **Image sequences that stall.** Swapping a different picture every few frames makes the browser fetch
34
+ and decode a full image each time. When a check shows stalls or drops on one, encode it into one video,
35
+ but only if it keeps the same picture and timing:
36
+ - Keep the images when the frames have transparency (H.264 has none, they'd render on black), or
37
+ small text and hard-edged colored UI (4:2:0 color softens it).
38
+ - The video must show each image on exactly the frames it shows now. Images held the same number of
39
+ frames each: `-framerate <fps / frames per image>`. Any other timing (eased, held, reversed): write
40
+ the images out in display order, one file per project frame, and encode at the project fps.
41
+ - Encode at the frames' own size (never smaller than they ever appear), visually lossless, BT.709:
42
+ ```
43
+ ffmpeg -framerate <rate> -start_number <first> -i f%03d.png \
44
+ -vf "pad=ceil(iw/2)*2:ceil(ih/2)*2,scale=out_color_matrix=bt709:out_range=tv,format=yuv420p" \
45
+ -c:v libx264 -crf 12 -preset slow -colorspace bt709 -color_primaries bt709 -color_trc bt709 \
46
+ -color_range tv -movflags +faststart out.mp4
47
+ ```
48
+ `pad` adds one pixel on the right or bottom when a side is odd (H.264 4:2:0 needs even sizes):
49
+ draw the video at its padded size inside a box of the frames' size with `overflow: hidden`.
50
+ - ffmpeg is on PATH or in `~/.agentcut/tools/ffmpeg/`; if there's none, ask the user.
51
+ - Play it with `<Video>` from `@remotion/media` (`trimBefore` in frames to start inside it). Many tiles
52
+ of the same footage: one video per distinct clip.
53
+ - Capture frames across the sequence before and after and compare; if colors or edges differ,
54
+ keep the images.
55
+ 2. **Repeated complex elements that never change** (a wall of the same static card): draw the piece
56
+ once to an image and show the copies as `<Img>`. Make it with `agentcut_capture_frames` at `scale: 2`
57
+ with `region` set to the piece's box in composition pixels, on a frame where it's fully drawn and
58
+ unobstructed; save it in `assets/` and show it at its 1x size. Keep the live version for every copy
59
+ that animates or changes, and for anything the camera zooms past 2x, so its text stays sharp (House
60
+ style).
61
+ 3. **Draw only what's visible.** An absolutely positioned element that is fully outside the frame or at
62
+ opacity 0 can `return null`. Not when it sits in a flex or grid layout (opacity 0 still takes its
63
+ space, so its siblings would move), not when it holds `<Audio>`/`<Video>` (the sound would stop), and
64
+ "outside" means after the camera's transforms and including its shadow and blur.
65
+ 4. **Compute once.** Canvases, data URLs, noise and layout math that don't depend on the frame go in
66
+ `useMemo` (or module scope), never in every render; nothing heavy in a component that mounts per tile.
67
+ Anything random must stay deterministic: `random("seed")` from `remotion`, never `Math.random()`,
68
+ which differs on every load and between the export's render tabs (it would flicker).
69
+ 5. **One filter on a wrapper** instead of the same `filter`/`blur` on dozens of children, only when the
70
+ children don't overlap or touch (a blur or drop-shadow of the group differs where they meet), then
71
+ compare captures. Big animated blurs are the most expensive thing to draw: keep their area as small as
72
+ the look allows.
73
+ 6. **Fewer DOM nodes for the same look.** A stack of plain divs for a skeleton UI can often be one
74
+ element with a `linear-gradient` background or an inline SVG that draws the same lines (check
75
+ `browser-export.md` for what the export draws). Never remove anything that shows.
76
+ 7. **WebGL and canvas scenes**: `usePreviewQuality()` lowers resolution and redraw rate in the preview
77
+ only (`browser-export.md`); captures and the export keep full quality.
78
+
79
+ After a change, capture the same frames as before (`agentcut_capture_frames`, the export's own
80
+ renderer) and compare: the frames must look the same. Then run `agentcut_preview_check` again and report
81
+ the before/after drop rates.