agentcut 0.2.25 → 0.2.27

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 (127) hide show
  1. package/README.md +177 -148
  2. package/dist/config.d.ts +0 -1
  3. package/dist/config.js +0 -5
  4. package/dist/config.js.map +1 -1
  5. package/dist/studio/agents/claude.js +3 -2
  6. package/dist/studio/agents/claude.js.map +1 -1
  7. package/dist/studio/chat.js +1 -1
  8. package/dist/studio/chat.js.map +1 -1
  9. package/dist/studio/cli.js +40 -21
  10. package/dist/studio/cli.js.map +1 -1
  11. package/dist/studio/download.d.ts +24 -0
  12. package/dist/studio/download.js +234 -0
  13. package/dist/studio/download.js.map +1 -0
  14. package/dist/studio/host.d.ts +1 -2
  15. package/dist/studio/host.js +36 -8
  16. package/dist/studio/host.js.map +1 -1
  17. package/dist/studio/housekeeping.d.ts +2 -2
  18. package/dist/studio/housekeeping.js +18 -17
  19. package/dist/studio/housekeeping.js.map +1 -1
  20. package/dist/studio/mcp-guides.js +1 -18
  21. package/dist/studio/mcp-guides.js.map +1 -1
  22. package/dist/studio/proc.js +16 -6
  23. package/dist/studio/proc.js.map +1 -1
  24. package/dist/studio/proxies.d.ts +4 -0
  25. package/dist/studio/proxies.js +15 -6
  26. package/dist/studio/proxies.js.map +1 -1
  27. package/dist/studio/release-cursor.js +21 -21
  28. package/dist/studio/release-video.js +10 -10
  29. package/dist/studio/schema.d.ts +0 -1
  30. package/dist/studio/schema.js +0 -1
  31. package/dist/studio/schema.js.map +1 -1
  32. package/dist/studio/tools.d.ts +0 -4
  33. package/dist/studio/tools.js +32 -31
  34. package/dist/studio/tools.js.map +1 -1
  35. package/dist/studio/voice/kokoro-catalog.d.ts +56 -28
  36. package/dist/studio/voice/kokoro-catalog.js +56 -28
  37. package/dist/studio/voice/kokoro-catalog.js.map +1 -1
  38. package/dist/studio/voice/ming-catalog.d.ts +19 -0
  39. package/dist/studio/voice/ming-catalog.js +40 -0
  40. package/dist/studio/voice/ming-catalog.js.map +1 -0
  41. package/dist/studio/voice/ming.d.ts +12 -0
  42. package/dist/studio/voice/ming.js +397 -0
  43. package/dist/studio/voice/ming.js.map +1 -0
  44. package/dist/studio/voice/previews.d.ts +5 -0
  45. package/dist/studio/voice/previews.js +50 -0
  46. package/dist/studio/voice/previews.js.map +1 -0
  47. package/dist/studio/voice/registry.js +2 -0
  48. package/dist/studio/voice/registry.js.map +1 -1
  49. package/dist/studio/voice.d.ts +1 -1
  50. package/dist/studio/voice.js +5 -6
  51. package/dist/studio/voice.js.map +1 -1
  52. package/package.json +56 -56
  53. package/template/AGENTS.md +14 -14
  54. package/template/components/README.md +70 -70
  55. package/template/components/before-after/BeforeAfter.tsx +89 -89
  56. package/template/components/catalog.ts +107 -107
  57. package/template/components/cinematic/Device3D.tsx +324 -324
  58. package/template/components/cinematic/devices3d/display-model.ts +184 -184
  59. package/template/components/cinematic/devices3d/iphone-model.ts +643 -643
  60. package/template/components/cinematic/devices3d/macbook-model.ts +608 -608
  61. package/template/components/cinematic/devices3d/models.ts +657 -657
  62. package/template/components/cinematic/devices3d/runtime.ts +267 -267
  63. package/template/components/cinematic/math.ts +100 -100
  64. package/template/components/color/grade-effect.ts +650 -650
  65. package/template/components/color/grade.ts +512 -512
  66. package/template/components/color/looks.ts +154 -154
  67. package/template/components/countdown/Countdown.tsx +166 -166
  68. package/template/components/dot-trace-title/DotTraceTitle.tsx +181 -181
  69. package/template/components/dot-trace-title/meta.json +51 -51
  70. package/template/components/generate/GenerateReveal.tsx +381 -381
  71. package/template/components/hook-card/HookCard.tsx +554 -554
  72. package/template/components/index.ts +199 -199
  73. package/template/components/lib.ts +191 -191
  74. package/template/components/line-diagram/LineDiagram.tsx +205 -205
  75. package/template/components/line-diagram/meta.json +215 -215
  76. package/template/components/list-card/ListCard.tsx +104 -104
  77. package/template/components/live-clip.ts +75 -75
  78. package/template/components/looks.tsx +1447 -1447
  79. package/template/components/loops/LoopCanvas.tsx +132 -132
  80. package/template/components/loops/engine.ts +184 -184
  81. package/template/components/loops/library.ts +667 -667
  82. package/template/components/loops/library2.ts +777 -777
  83. package/template/components/motion-loop/MotionLoop.tsx +37 -37
  84. package/template/components/motion-loop/meta.json +311 -311
  85. package/template/components/props.ts +73 -73
  86. package/template/components/quote-card/QuoteCard.tsx +71 -71
  87. package/template/components/style-layer.tsx +233 -233
  88. package/template/components/styles.ts +113 -113
  89. package/template/components/types.ts +66 -66
  90. package/template/components/word-pop/WordPop.tsx +59 -59
  91. package/template/components/word-stack/WordStack.tsx +122 -122
  92. package/template/presets/charcoal-sketch/PROMPT.md +48 -48
  93. package/template/presets/charcoal-sketch/scripts/duck_music.py +34 -34
  94. package/template/presets/punk-cut-paper/scenes/Motif.tsx +376 -376
  95. package/template/presets/punk-cut-paper/scenes/Photo.tsx +73 -73
  96. package/template/presets/punk-cut-paper/scenes/Ransom.tsx +119 -119
  97. package/template/runtime/composition.tsx +1189 -1185
  98. package/template/runtime/helpers.tsx +230 -230
  99. package/template/runtime/index.tsx +22 -22
  100. package/template/runtime/types.ts +315 -315
  101. package/template/skill/SKILL.md +186 -351
  102. package/template/skill/references/broll.md +44 -44
  103. package/template/skill/references/browser-export.md +61 -61
  104. package/template/skill/references/cinematic.md +206 -206
  105. package/template/skill/references/color.md +79 -79
  106. package/template/skill/references/craft.md +54 -10
  107. package/template/skill/references/editing-styles.md +57 -57
  108. package/template/skill/references/feature-launch.md +5 -1
  109. package/template/skill/references/footage.md +72 -72
  110. package/template/skill/references/format.md +142 -142
  111. package/template/skill/references/how-to.md +0 -15
  112. package/template/skill/references/launch-direction.md +89 -0
  113. package/template/skill/references/loops.md +151 -151
  114. package/template/skill/references/mcp-external.md +19 -0
  115. package/template/skill/references/performance.md +93 -93
  116. package/template/skill/references/person-cutout.md +19 -19
  117. package/template/skill/references/presets.md +60 -60
  118. package/template/skill/references/product-launch.md +4 -1
  119. package/template/skill/references/release-capture.md +53 -0
  120. package/template/skill/references/sound.md +167 -155
  121. package/template/skill/references/style-spy.md +160 -160
  122. package/template/skill/references/website-howto.md +45 -45
  123. package/template/starter/.studio/chat.json +1 -1
  124. package/template/starter/layers.json +46 -46
  125. package/template/starter/notes.md +4 -4
  126. package/template/starter/project.json +13 -13
  127. package/template/starter/scenes/Title.tsx +38 -38
@@ -1,142 +1,142 @@
1
- # Project format (v1)
2
-
3
- All times are **integer frames** at `project.fps`. Clip `from` is the timeline frame where the clip
4
- starts; `duration` is its length in frames. Inside a clip (scene code, caption words, fades) frames are
5
- **relative to the clip start**.
6
-
7
- ## project.json
8
-
9
- ```json
10
- {
11
- "version": 1,
12
- "name": "Rolino launch",
13
- "fps": 30,
14
- "durationInFrames": 1800,
15
- "background": "#060a16",
16
- "variants": {
17
- "wide": { "width": 1920, "height": 1080 },
18
- "mobile": { "width": 1080, "height": 1920 }
19
- },
20
- "defaultVariant": "wide",
21
- "fonts": [
22
- "Inter:400;600;800",
23
- { "family": "Brand Onest", "src": "assets/fonts/onest-700.woff2", "weight": "700" }
24
- ]
25
- }
26
- ```
27
-
28
- - `durationInFrames` is the export length; keep it equal to the end of the last clip.
29
- - Fonts: Google Fonts specs (`"Family:400;700"`) or local files (preferred for brand fonts: renders
30
- then never depend on Google Fonts). Reference them by `family` in styles.
31
-
32
- ## layers.json
33
-
34
- ```json
35
- {
36
- "version": 1,
37
- "tracks": [
38
- { "id": "captions", "name": "Captions", "kind": "captions", "clips": [] },
39
- { "id": "text", "name": "Titles", "kind": "text", "clips": [] },
40
- { "id": "grain", "name": "Film grain", "kind": "scene", "clips": [] },
41
- { "id": "scenes", "name": "Scenes", "kind": "scene", "clips": [] },
42
- { "id": "voice", "name": "Voice", "kind": "audio", "clips": [] },
43
- { "id": "music", "name": "Music", "kind": "audio", "clips": [] },
44
- { "id": "sfx", "name": "SFX", "kind": "audio", "clips": [] }
45
- ],
46
- "markers": [
47
- { "id": "m-drop", "frame": 204, "label": "Drop", "kind": "beat" },
48
- { "id": "m-reveal", "frame": 198, "label": "Reveal", "kind": "section" }
49
- ]
50
- }
51
- ```
52
-
53
- `tracks[0]` is drawn **on top**; later tracks are drawn underneath. Clips on a track are sorted by
54
- `from`. Clips may overlap only on `scene` and `audio` tracks (use more tracks otherwise).
55
-
56
- Track fields: `id` (kebab-case, unique), `name`, `kind`, `clips`, optional `hidden` (visual), `muted`
57
- (audio/video), `locked` (user lock — don't move locked clips), `volume` (audio track gain).
58
-
59
- Markers (`section` = scene starts, `cue` = moments sounds/animations hit, `beat` = music beats you rely
60
- on) show on the timeline ruler. Keep section markers in sync with scene clips.
61
-
62
- ### Clip fields (all kinds)
63
-
64
- | field | |
65
- |---|---|
66
- | `id` | unique in the project, stable, readable |
67
- | `name` | timeline label (optional) |
68
- | `from`, `duration` | frames |
69
- | `enter`, `exit` | `{ "preset": "fade" \| "slide-up" \| "slide-down" \| "slide-left" \| "slide-right" \| "pop" \| "scale" \| "blur" \| "none", "frames": 12 }` (visual clips) |
70
- | `opacity` | 0..1 (visual clips) |
71
- | `note` | why the clip is there (cue reason) |
72
- | `variants` | per-variant overrides, e.g. `{ "mobile": { "box": {…}, "style": {…} } }` |
73
-
74
- `box` = `{ "x", "y", "width", "height" }` as fractions of the frame (0..1), top-left origin.
75
-
76
- ### Kinds
77
-
78
- **scene** — `{ "scene": "Hook", "props": { … } }` renders `scenes/Hook.tsx`; or
79
- `{ "component": "text-reveal", "props": { … } }` renders a library component (one of the two per clip;
80
- see `references/components.md`).
81
-
82
- **audio** — `{ "src": "assets/voice.wav", "volume": 1, "trimStart": 0, "fadeIn": 0, "fadeOut": 0, "loop": false, "playbackRate": 1, "role": "voice" | "music" | "sfx" | "ambience" }`.
83
- `trimStart` skips frames of the file. Set `duration` from `agentcut_media_info` (frames). An SFX
84
- clip's `from` is the cue frame minus the file's onset (see sound.md).
85
-
86
- **video** — `{ "src", "trimStart", "volume", "muted", "fit": "cover" | "contain", "box", "playbackRate", "grade" }`.
87
- `grade` — colour: `{ "exposure": 0.2, "contrast": 1.1, "temperature": 0.1, "look": "golden-stock" }` and more (fields and workflow:
88
- `references/color.md`). Leave out what you don't change. `inheritGrade: false` keeps the project grade and adjustment layers off it.
89
- Footage from the editor: see `references/footage.md`.
90
-
91
- **image** — `{ "src", "fit", "box", "radius", "grade", "inheritGrade" }`. `inheritGrade: true` also applies the project grade and adjustment layers.
92
-
93
- **adjustment** — `{ "grade" }`. Draws nothing: it grades the footage below it while it runs (`references/color.md`).
94
-
95
- **text** — `{ "text", "box", "style": { "fontFamily", "fontSize" (px at the variant size), "fontWeight", "color", "align", "lineHeight", "letterSpacing", "textTransform", "shadow" } }`. For styled kinetic type use a scene instead.
96
-
97
- **captions** — `{ "words": [{ "text", "from", "to" }], "style": { "preset": "pop" | "karaoke" | "plain", "fontFamily", "fontSize", "fontWeight", "color", "highlight", "position": "bottom" | "center" | "top", "maxWordsPerLine" } }`.
98
- Word `from`/`to` are frames **relative to the clip start**. Build them from `agentcut_transcribe`
99
- (`fromFrame - clip.from`). For custom caption looks, write a scene that takes `words` in props.
100
-
101
- `src` forms: `assets/<file>`, `library:<path>` (workspace library shared by projects), `https://…` (must
102
- allow CORS).
103
-
104
- ## Scenes
105
-
106
- ```tsx
107
- // scenes/Hook.tsx
108
- import { AbsoluteFill, useCurrentFrame } from "remotion";
109
- import { RadialGlow, SPRING, ease, sp, mix, useStudio, type SceneProps } from "agentcut";
110
-
111
- type Props = SceneProps & { title: string; accent: string };
112
-
113
- export default function Hook({ title, accent, width, height, clip }: Props) {
114
- const f = useCurrentFrame(); // 0 at the clip start
115
- const vertical = height > width;
116
- const s = sp(f, 6, SPRING.pop); // spring starting at local frame 6
117
- const out = ease(f, clip.duration - 8, clip.duration);
118
- return (
119
- <AbsoluteFill style={{ background: "linear-gradient(160deg,#0b0b14,#050507)", opacity: 1 - out }}>
120
- <RadialGlow x={0.5} y={0.45} radius={0.5} color={accent} opacity={0.25} />
121
- <AbsoluteFill style={{ alignItems: "center", justifyContent: "center" }}>
122
- <div style={{ fontFamily: "Inter", fontWeight: 900, fontSize: vertical ? 140 : 120,
123
- transform: `translateY(${mix(60, 0, s)}px)`, color: "#fff" }}>{title}</div>
124
- </AbsoluteFill>
125
- </AbsoluteFill>
126
- );
127
- }
128
- ```
129
-
130
- Scene props: everything in the clip's `props`, plus `clip` (`id`, `from`, `duration`), `variant`,
131
- `width`, `height`, `fps`.
132
-
133
- `agentcut` exports: `useStudio()` (project, variant, width, height, fps), `useIsVertical()`, `usePreviewQuality()`
134
- (cheaper drawing in the live preview, full quality in captures/export),
135
- `asset(path)` (URL for `assets/…` / `library:…`), `clamp`, `mix`, `ease(f, from, to, easing?)`,
136
- `sp(f, start, config?, duration?)`, `SPRING` (smooth, snappy, bouncy, pop, land), `sec(seconds)`,
137
- `<RadialGlow>`, `<FrameBox>`, and the format types.
138
-
139
- Shared helpers for several scenes go in `scenes/lib/*.ts(x)` (files in subfolders aren't scenes).
140
- Available packages: `react`, `remotion`, `@remotion/media`, `@remotion/transitions` (+ presentations),
141
- `@remotion/shapes`, `@remotion/paths`, `@remotion/noise`. Anything else: `npm install` it in the
142
- workspace root and it gets bundled.
1
+ # Project format (v1)
2
+
3
+ All times are **integer frames** at `project.fps`. Clip `from` is the timeline frame where the clip
4
+ starts; `duration` is its length in frames. Inside a clip (scene code, caption words, fades) frames are
5
+ **relative to the clip start**.
6
+
7
+ ## project.json
8
+
9
+ ```json
10
+ {
11
+ "version": 1,
12
+ "name": "Rolino launch",
13
+ "fps": 30,
14
+ "durationInFrames": 1800,
15
+ "background": "#060a16",
16
+ "variants": {
17
+ "wide": { "width": 1920, "height": 1080 },
18
+ "mobile": { "width": 1080, "height": 1920 }
19
+ },
20
+ "defaultVariant": "wide",
21
+ "fonts": [
22
+ "Inter:400;600;800",
23
+ { "family": "Brand Onest", "src": "assets/fonts/onest-700.woff2", "weight": "700" }
24
+ ]
25
+ }
26
+ ```
27
+
28
+ - `durationInFrames` is the export length; keep it equal to the end of the last clip.
29
+ - Fonts: Google Fonts specs (`"Family:400;700"`) or local files (preferred for brand fonts: renders
30
+ then never depend on Google Fonts). Reference them by `family` in styles.
31
+
32
+ ## layers.json
33
+
34
+ ```json
35
+ {
36
+ "version": 1,
37
+ "tracks": [
38
+ { "id": "captions", "name": "Captions", "kind": "captions", "clips": [] },
39
+ { "id": "text", "name": "Titles", "kind": "text", "clips": [] },
40
+ { "id": "grain", "name": "Film grain", "kind": "scene", "clips": [] },
41
+ { "id": "scenes", "name": "Scenes", "kind": "scene", "clips": [] },
42
+ { "id": "voice", "name": "Voice", "kind": "audio", "clips": [] },
43
+ { "id": "music", "name": "Music", "kind": "audio", "clips": [] },
44
+ { "id": "sfx", "name": "SFX", "kind": "audio", "clips": [] }
45
+ ],
46
+ "markers": [
47
+ { "id": "m-drop", "frame": 204, "label": "Drop", "kind": "beat" },
48
+ { "id": "m-reveal", "frame": 198, "label": "Reveal", "kind": "section" }
49
+ ]
50
+ }
51
+ ```
52
+
53
+ `tracks[0]` is drawn **on top**; later tracks are drawn underneath. Clips on a track are sorted by
54
+ `from`. Clips may overlap only on `scene` and `audio` tracks (use more tracks otherwise).
55
+
56
+ Track fields: `id` (kebab-case, unique), `name`, `kind`, `clips`, optional `hidden` (visual), `muted`
57
+ (audio/video), `locked` (user lock — don't move locked clips), `volume` (audio track gain).
58
+
59
+ Markers (`section` = scene starts, `cue` = moments sounds/animations hit, `beat` = music beats you rely
60
+ on) show on the timeline ruler. Keep section markers in sync with scene clips.
61
+
62
+ ### Clip fields (all kinds)
63
+
64
+ | field | |
65
+ |---|---|
66
+ | `id` | unique in the project, stable, readable |
67
+ | `name` | timeline label (optional) |
68
+ | `from`, `duration` | frames |
69
+ | `enter`, `exit` | `{ "preset": "fade" \| "slide-up" \| "slide-down" \| "slide-left" \| "slide-right" \| "pop" \| "scale" \| "blur" \| "none", "frames": 12 }` (visual clips) |
70
+ | `opacity` | 0..1 (visual clips) |
71
+ | `note` | why the clip is there (cue reason) |
72
+ | `variants` | per-variant overrides, e.g. `{ "mobile": { "box": {…}, "style": {…} } }` |
73
+
74
+ `box` = `{ "x", "y", "width", "height" }` as fractions of the frame (0..1), top-left origin.
75
+
76
+ ### Kinds
77
+
78
+ **scene** — `{ "scene": "Hook", "props": { … } }` renders `scenes/Hook.tsx`; or
79
+ `{ "component": "text-reveal", "props": { … } }` renders a library component (one of the two per clip;
80
+ see `references/components.md`).
81
+
82
+ **audio** — `{ "src": "assets/voice.wav", "volume": 1, "trimStart": 0, "fadeIn": 0, "fadeOut": 0, "loop": false, "playbackRate": 1, "role": "voice" | "music" | "sfx" | "ambience" }`.
83
+ `trimStart` skips frames of the file. Set `duration` from `agentcut_media_info` (frames). An SFX
84
+ clip's `from` is the cue frame minus the file's onset (see sound.md).
85
+
86
+ **video** — `{ "src", "trimStart", "volume", "muted", "fit": "cover" | "contain", "box", "playbackRate", "grade" }`.
87
+ `grade` — colour: `{ "exposure": 0.2, "contrast": 1.1, "temperature": 0.1, "look": "golden-stock" }` and more (fields and workflow:
88
+ `references/color.md`). Leave out what you don't change. `inheritGrade: false` keeps the project grade and adjustment layers off it.
89
+ Footage from the editor: see `references/footage.md`.
90
+
91
+ **image** — `{ "src", "fit", "box", "radius", "grade", "inheritGrade" }`. `inheritGrade: true` also applies the project grade and adjustment layers.
92
+
93
+ **adjustment** — `{ "grade" }`. Draws nothing: it grades the footage below it while it runs (`references/color.md`).
94
+
95
+ **text** — `{ "text", "box", "style": { "fontFamily", "fontSize" (px at the variant size), "fontWeight", "color", "align", "lineHeight", "letterSpacing", "textTransform", "shadow" } }`. For styled kinetic type use a scene instead.
96
+
97
+ **captions** — `{ "words": [{ "text", "from", "to" }], "style": { "preset": "pop" | "karaoke" | "plain", "fontFamily", "fontSize", "fontWeight", "color", "highlight", "position": "bottom" | "center" | "top", "maxWordsPerLine" } }`.
98
+ Word `from`/`to` are frames **relative to the clip start**. Build them from `agentcut_transcribe`
99
+ (`fromFrame - clip.from`). For custom caption looks, write a scene that takes `words` in props.
100
+
101
+ `src` forms: `assets/<file>`, `library:<path>` (workspace library shared by projects), `https://…` (must
102
+ allow CORS).
103
+
104
+ ## Scenes
105
+
106
+ ```tsx
107
+ // scenes/Hook.tsx
108
+ import { AbsoluteFill, useCurrentFrame } from "remotion";
109
+ import { RadialGlow, SPRING, ease, sp, mix, useStudio, type SceneProps } from "agentcut";
110
+
111
+ type Props = SceneProps & { title: string; accent: string };
112
+
113
+ export default function Hook({ title, accent, width, height, clip }: Props) {
114
+ const f = useCurrentFrame(); // 0 at the clip start
115
+ const vertical = height > width;
116
+ const s = sp(f, 6, SPRING.pop); // spring starting at local frame 6
117
+ const out = ease(f, clip.duration - 8, clip.duration);
118
+ return (
119
+ <AbsoluteFill style={{ background: "linear-gradient(160deg,#0b0b14,#050507)", opacity: 1 - out }}>
120
+ <RadialGlow x={0.5} y={0.45} radius={0.5} color={accent} opacity={0.25} />
121
+ <AbsoluteFill style={{ alignItems: "center", justifyContent: "center" }}>
122
+ <div style={{ fontFamily: "Inter", fontWeight: 900, fontSize: vertical ? 140 : 120,
123
+ transform: `translateY(${mix(60, 0, s)}px)`, color: "#fff" }}>{title}</div>
124
+ </AbsoluteFill>
125
+ </AbsoluteFill>
126
+ );
127
+ }
128
+ ```
129
+
130
+ Scene props: everything in the clip's `props`, plus `clip` (`id`, `from`, `duration`), `variant`,
131
+ `width`, `height`, `fps`.
132
+
133
+ `agentcut` exports: `useStudio()` (project, variant, width, height, fps), `useIsVertical()`, `usePreviewQuality()`
134
+ (cheaper drawing in the live preview, full quality in captures/export),
135
+ `asset(path)` (URL for `assets/…` / `library:…`), `clamp`, `mix`, `ease(f, from, to, easing?)`,
136
+ `sp(f, start, config?, duration?)`, `SPRING` (smooth, snappy, bouncy, pop, land), `sec(seconds)`,
137
+ `<RadialGlow>`, `<FrameBox>`, and the format types.
138
+
139
+ Shared helpers for several scenes go in `scenes/lib/*.ts(x)` (files in subfolders aren't scenes).
140
+ Available packages: `react`, `remotion`, `@remotion/media`, `@remotion/transitions` (+ presentations),
141
+ `@remotion/shapes`, `@remotion/paths`, `@remotion/noise`. Anything else: `npm install` it in the
142
+ workspace root and it gets bundled.
@@ -144,18 +144,3 @@ Reuse current material and passed checks. Check changed regions first, then revi
144
144
  in both formats. Run page-heavy checks in sequence as `website-howto.md` requires. If a tool stalls,
145
145
  inspect active work before retrying. Record what passed and what remains blocked; do not claim a
146
146
  build alone proves instructional accuracy.
147
-
148
- ## Evidence used for this guide
149
-
150
- The application above is original Agentcut guidance, informed by these primary sources. These studies
151
- do not establish a universal video length or guarantee an outcome for Agentcut users.
152
-
153
- - [Software-training research (2013)](https://ris.utwente.nl/ws/portalfiles/portal/6827789/s4.pdf)
154
- supports task-focused demonstrations, accurate interfaces and coordinated action and narration.
155
- - [A controlled study of pause and navigation guidance (2022)](https://pmc.ncbi.nlm.nih.gov/articles/PMC9610327/)
156
- supports explicit help for when to pause and review. Its experiment used educational material,
157
- so applying it to software-step holds is a design inference.
158
- - [A software-tutorial study of reviews (2018)](https://research.utwente.nl/en/publications/supporting-motivation-task-performance-and-retention-in-video-tut/)
159
- found no extra benefit from its review or second-demonstration conditions. Keep recaps purposeful.
160
- - [W3C caption guidance](https://www.w3.org/WAI/media/av/captions/) calls for synchronized, accurate
161
- captions and correction of automatic output. This informs the caption review above.
@@ -0,0 +1,89 @@
1
+ # Launch direction: from brief to checked shots
2
+
3
+ Use this with `product-launch.md` or `feature-launch.md` for a new film or a major revision.
4
+ For a small edit, keep the existing direction and check the changed shots. The user's script,
5
+ reference, selected style and format take priority. Keep decisions in the project's `notes.md`.
6
+ This guide uses Agentcut tools and frame timing; it does not require another video engine.
7
+
8
+ ## Choose a story that the images can tell
9
+
10
+ Compare two possible stories using the available evidence, not just two opening titles. For example,
11
+ show a finished result and then how it was made, or follow one real input through an action to its
12
+ result. Pick the clearest story and record why. Continue without an approval stop unless the user
13
+ asked to choose a direction. Do not repeat this exercise for an approved script or storyboard.
14
+
15
+ Keep the same recognizable file, query, project or other subject through the demonstration when
16
+ the source supports it. A viewer should see what changed. Unrelated screens with benefit labels
17
+ do not explain a workflow. Do not fabricate a failure in the old workflow to create tension.
18
+
19
+ ## Turn the direction into build decisions
20
+
21
+ Before building scenes, add a compact direction and shot table to `notes.md`:
22
+
23
+ - **Look:** actual background and text colors, accent use, font files/families, weights, text sizes,
24
+ margins and product framing for each output format. Use selected style tokens where available.
25
+ Replace vague words such as "premium" with these choices. Keep meaningful product status colors.
26
+ - **Motion:** entrance, camera and exit durations in frames, easing or spring settings, and the
27
+ settled reading window. Choose motion by purpose; do not give every element the same entrance.
28
+ - **Avoid for this film:** identify likely distractions, such as repeated feature cards, tiny UI
29
+ inside a large empty stage, or decoration that competes with proof. This is specific to the brief;
30
+ do not ban a color, material or effect that the user's style needs.
31
+
32
+ | Frames [start, end) | What the viewer learns | Source and visible change | Framing and main move | Exact words and settled read frames | Sound cue | Link to next shot |
33
+ | --- | --- | --- | --- | --- | --- | --- |
34
+
35
+ Fill one row per shot. Use real asset paths and source ranges, not placeholder evidence. Keep the
36
+ table aligned with the timeline after timing changes. Plan the final readable frame before `end`.
37
+ Do not add claims, voice or captions just to fill the table.
38
+
39
+ For each demonstration, establish where the task happens, bring the relevant action into clear
40
+ view, then show its result in context. These can be parts of one shot. A pan across a still image
41
+ can explain a layout; it cannot prove an interaction. Keep real footage for the action.
42
+
43
+ ## Prove the visual direction early
44
+
45
+ Build the opening and the main proof shot first, in story order when possible. Capture their
46
+ settled frames in each output format with `agentcut_capture_frames`. Inspect actual words, assets,
47
+ framing and contrast before extending that treatment to the rest of the film. A full storyboard
48
+ approval step is optional, only when requested; these are working checks in the live project.
49
+
50
+ The first frame should give the viewer useful visual context unless the brief calls for darkness.
51
+ Give the product enough space for the relevant action to read. At small display size, crop closer
52
+ or reduce the words before reducing text size. A full app view establishes context; its incidental
53
+ labels do not all need to be readable. Essential labels and results do.
54
+
55
+ ## Make motion carry the story
56
+
57
+ - Give each shot one main movement. Delay or reduce secondary motion so it does not compete.
58
+ Let essential titles and UI settle while the viewer reads. Idle floating is not a demonstration.
59
+ - Contrast short transitions with longer action and result holds. As a starting estimate, allow
60
+ about `0.5 + 0.3 * wordCount` seconds for a short line after it settles. Validate with the actual
61
+ layout and audience; dense UI needs more time. Cut words or decoration to meet a fixed duration.
62
+ - Connect shots through a visible action, a continuing subject, matching framing or a deliberate
63
+ cut. Name the connection in the shot table. Do not require a transition quota or a new effect at
64
+ every cut. A clear hard cut is useful when a morph would distort the evidence.
65
+ - Keep important labels sharp during the reading window. Motion blur belongs to movement, not
66
+ the proof hold. Use the existing component catalog and `cinematic.md` tools where suitable.
67
+ Follow `browser-export.md`; a browser-only effect is not proof that an export works.
68
+ - Use source action times, narration timings or analyzed music cues. For a regular beat grid,
69
+ calculate each frame from its beat index and round once; repeated rounded intervals cause drift.
70
+
71
+ ## Review the cuts and the meaning
72
+
73
+ Keep the main skill's full picture, sound and performance review. Add these checks to it:
74
+
75
+ 1. Inspect frame 0, the settled proof and the final readable frame in each format. Read the shot
76
+ sequence as a new viewer. Without the headline, is the promised change still visible?
77
+ 2. For each cut at frame `c`, sample `c - 1` and `c`, plus nearby frames across the transition.
78
+ Clamp samples to the video bounds. For a longer move, sample intermediate frames too. Look for
79
+ blank gaps, duplicated subjects, jumps in labels, obscured results and conflicting motion.
80
+ 3. Inspect essential words and UI at a small display size, about 360 px wide where available.
81
+ If a tool cannot show that size, record this limit; do not claim a small-screen check passed.
82
+ 4. Record concrete issues as `frame / variant / issue / change / recheck result` in `notes.md`.
83
+ Fix wrong claims, unreadable evidence and broken transitions before decorative details. Recheck
84
+ changed shots using `efficient-review.md`; timing or shared changes require broader checks.
85
+
86
+ At hand-off, state what was checked and any remaining weak shot or missing evidence. A build pass
87
+ only proves the project compiles. Do not describe a film as visually verified without viewing its
88
+ captures, or say sound was heard when it was only measured.
89
+