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,324 +1,324 @@
1
- // Real 3D devices (iPhone 16 Pro Max model, MacBook, Studio Display) inside a cinematic <Stage>.
2
- // three.js draws them on a full-frame canvas through exactly the Stage's camera, so they move, turn and
3
- // blur with the CSS planes around them. Models come from ScreenSlick's device stage.
4
- import { useLayoutEffect, useRef, useState } from "react";
5
- import { Img, useDelayRender, useRemotionEnvironment, useVideoConfig } from "remotion";
6
- import { blurFor, Group, Plane, useStageContext } from "./Cinematic";
7
- import { mul, placementMatrix, type M4, type Placement } from "./math";
8
- import type { DeviceRenderer, VideoDeviceModelId } from "./devices3d/runtime";
9
-
10
- export type Device3DModel = "iphone" | "iphone-color" | "iphone-classic" | "macbook" | "macbook-pro" | "display";
11
-
12
- const MODEL_IDS: Record<Device3DModel, VideoDeviceModelId> = {
13
- iphone: "iphone-16-pro-max",
14
- "iphone-color": "procedural-iphone",
15
- "iphone-classic": "procedural-iphone",
16
- macbook: "procedural-macbook",
17
- "macbook-pro": "macbook-pro-14",
18
- display: "procedural-display",
19
- };
20
-
21
- /** Default size: the device's largest dimension in world px. */
22
- const DEFAULT_SIZE: Record<Device3DModel, number> = { iphone: 760, "iphone-color": 760, "iphone-classic": 760, macbook: 1250, "macbook-pro": 1250, display: 1150 };
23
-
24
- /** Rough footprint (width, height as fractions of size) for the soft shadow behind the device. */
25
- const FOOTPRINT: Record<Device3DModel, [number, number]> = {
26
- iphone: [0.47, 1],
27
- "iphone-color": [0.47, 1],
28
- "iphone-classic": [0.47, 1],
29
- macbook: [1, 0.62],
30
- "macbook-pro": [1, 0.62],
31
- display: [1, 0.86],
32
- };
33
-
34
- export const DEVICE_FINISHES: Record<string, string> = {
35
- silver: "#cfd1d3",
36
- starlight: "#d9cdb6",
37
- "space-gray": "#6f7174",
38
- // The deep anodised black of the current MacBook Pro (matched to a reference model).
39
- "space-black": "#3d3c40",
40
- // Colour iPhone finishes (iphone-color), most with calibrated logo tints in iphone-model.ts.
41
- lavender: "#c5a4df",
42
- "mist-blue": "#829dce",
43
- white: "#d9dad6",
44
- "cosmic-orange": "#c9643a",
45
- graphite: "#6a6a6a",
46
- midnight: "#2f3541",
47
- black: "#3c3d40",
48
- };
49
-
50
- export interface Device3DProps extends Placement {
51
- model: Device3DModel;
52
- /**
53
- * Your own GLB for this device (asset("library:models/…")). Required for "macbook-pro", whose model
54
- * can't ship with Agentcut; optional for the others.
55
- */
56
- modelSrc?: string;
57
- /** Screenshot on the screen (asset("assets/…")). It covers the screen; a taller one shows its top. */
58
- src?: string;
59
- /** Largest dimension of the device in world px (iPhone ≈ its height, MacBook ≈ its width). */
60
- size?: number;
61
- /**
62
- * Hardware colour, or any hex. MacBook / display: space-black (MacBook default), space-gray, silver,
63
- * starlight, midnight, black. iphone-color: graphite (default), lavender, mist-blue, white,
64
- * cosmic-orange, or a brand hex. The iPhone 16 Pro Max model has its own fixed finish.
65
- */
66
- finish?: string;
67
- /** MacBook lid angle in degrees: 110 open, 0 closed. Animate it for an opening shot. */
68
- lidAngle?: number;
69
- /** Scrolls a tall screenshot: 0 top … 1 bottom. */
70
- scroll?: number;
71
- /** Light: 1 normal, 0.8 moody, 1.3 bright. */
72
- exposure?: number;
73
- /** Soft shadow behind the device: 0 none, 1 strong. */
74
- shadow?: number;
75
- /** Lens blur from the Stage's focus and aperture (whole device). */
76
- dof?: boolean;
77
- opacity?: number;
78
- /**
79
- * Pieces of the screenshot that rise off the device's screen toward the camera (cards, buttons,
80
- * charts). `box` is [x, y, w, h] in fractions of the SCREENSHOT; `z` how far it rises (world px).
81
- */
82
- lifts?: Device3DLift[];
83
- }
84
-
85
- export interface Device3DLift {
86
- box: [number, number, number, number];
87
- /** Rise toward the viewer, world px (animate 0 → 40–140). */
88
- z: number;
89
- /** Extra scale while lifted (1.0–1.15). */
90
- scale?: number;
91
- /** Extra offset in world px while lifted (x right, y down). */
92
- x?: number;
93
- y?: number;
94
- radius?: number;
95
- shadow?: number;
96
- rim?: number;
97
- opacity?: number;
98
- }
99
-
100
- type V3 = [number, number, number];
101
- const sub = (a: V3, b: V3): V3 => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
102
- const len = (a: V3) => Math.hypot(a[0], a[1], a[2]);
103
- const norm = (a: V3): V3 => {
104
- const l = len(a) || 1;
105
- return [a[0] / l, a[1] / l, a[2] / l];
106
- };
107
- const cross = (a: V3, b: V3): V3 => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
108
-
109
- function loadImage(src: string) {
110
- return new Promise<HTMLImageElement>((resolve, reject) => {
111
- const image = new Image();
112
- image.crossOrigin = "anonymous";
113
- image.decoding = "async";
114
- image.onload = () => resolve(image);
115
- image.onerror = () => reject(new Error(`Couldn't load the screen image ${src}.`));
116
- image.src = src;
117
- });
118
- }
119
-
120
- /** A real 3D device in the Stage, with a screenshot on its screen. */
121
- export function Device3D({
122
- model,
123
- modelSrc,
124
- src,
125
- size,
126
- finish,
127
- lidAngle = 110,
128
- scroll = 0,
129
- exposure = 1,
130
- shadow = 0.6,
131
- dof = true,
132
- opacity = 1,
133
- lifts,
134
- ...placement
135
- }: Device3DProps) {
136
- const ctx = useStageContext("Device3D");
137
- const { width, height } = useVideoConfig();
138
- const env = useRemotionEnvironment();
139
- const { delayRender, continueRender, cancelRender } = useDelayRender();
140
- const holder = useRef<HTMLDivElement>(null);
141
- const pending = useRef<number | null>(null);
142
- const [device, setDevice] = useState<DeviceRenderer | null>(null);
143
- // The built-in MacBook defaults to space black; other devices keep their own default.
144
- const finishName = finish ?? (model === "macbook" ? "space-black" : model === "iphone-color" ? "graphite" : undefined);
145
- const finishColor = finishName ? (DEVICE_FINISHES[finishName] ?? finishName) : undefined;
146
- const deviceSize = size ?? DEFAULT_SIZE[model];
147
-
148
- // Load three, the model and the screenshot; hold the render until the first frame is drawn. A layout
149
- // effect, so the hold exists before the commit ends (an export or capture can look for holds right
150
- // after it) and is never created by a render React throws away.
151
- useLayoutEffect(() => {
152
- const box = holder.current;
153
- if (!box) return;
154
- // A reload (new model, finish or screenshot) holds the render again until it's drawn.
155
- pending.current ??= delayRender(`Loading the 3D ${model}`, { timeoutInMilliseconds: 60000 });
156
- const handle = pending.current;
157
- let alive = true;
158
- let created: DeviceRenderer | null = null;
159
- const canvas = document.createElement("canvas");
160
- canvas.style.cssText = "position:absolute;left:0;top:0;width:100%;height:100%";
161
- box.appendChild(canvas);
162
- const image = src ? loadImage(src) : Promise.resolve(null);
163
- // Handled below; this keeps a failure while the model loads from being reported as unhandled.
164
- image.catch(() => {});
165
- (async () => {
166
- const { createDeviceRenderer } = await import("./devices3d/runtime");
167
- const renderer = await createDeviceRenderer(canvas, MODEL_IDS[model], finishColor, modelSrc);
168
- if (!alive) {
169
- renderer.dispose();
170
- return;
171
- }
172
- created = renderer;
173
- const loaded = await image;
174
- if (!alive) return;
175
- renderer.setImage(loaded);
176
- setDevice(renderer);
177
- })().catch((error) => {
178
- if (alive) cancelRender(error);
179
- });
180
- return () => {
181
- alive = false;
182
- created?.dispose();
183
- canvas.remove();
184
- setDevice(null);
185
- if (pending.current === handle) {
186
- continueRender(handle);
187
- pending.current = null;
188
- }
189
- };
190
- }, [model, modelSrc, finishColor, src, delayRender, continueRender, cancelRender]);
191
-
192
- const matrix = mul(ctx.view, ctx.model, placementMatrix(placement));
193
- const centerDist = ctx.D - matrix[11];
194
- const blur = dof ? blurFor(ctx, centerDist) : 0;
195
- const preview = env.isPlayer && !env.isRendering;
196
-
197
- useLayoutEffect(() => {
198
- if (!device) return;
199
- device.render({
200
- width,
201
- height,
202
- D: ctx.D,
203
- fov: ctx.fov,
204
- shiftX: ctx.shiftX,
205
- shiftY: ctx.shiftY,
206
- matrix,
207
- size: deviceSize,
208
- exposure,
209
- lidAngle,
210
- scroll,
211
- // The live preview draws the 3D device at half resolution; captures and exports at full.
212
- pixelRatio: preview ? 0.5 : 1,
213
- });
214
- if (pending.current !== null) {
215
- continueRender(pending.current);
216
- pending.current = null;
217
- }
218
- });
219
-
220
- const [fw, fh] = FOOTPRINT[model];
221
- const shadowFill = `rgba(0,0,0,${Math.min(0.8, 0.45 * shadow) * opacity})`;
222
- // World px: the Plane turns it into its own local px.
223
- const shadowBlur = Math.max(8, deviceSize * 0.04);
224
- // Phones float: their shadow falls on a wall behind them. Laptops and displays stand: it pools on
225
- // the floor under them.
226
- const laptop = model === "macbook" || model === "macbook-pro";
227
- const standing = laptop || model === "display";
228
- return (
229
- <>
230
- {shadow > 0 ? (
231
- <Group {...placement}>
232
- {standing ? (
233
- <Plane
234
- y={deviceSize * fh * 0.5}
235
- z={laptop ? deviceSize * 0.12 : 0}
236
- tilt={90}
237
- width={deviceSize * (laptop ? 1.02 : 0.5)}
238
- height={deviceSize * (laptop ? 0.72 : 0.3)}
239
- radius={deviceSize * 0.08}
240
- background={shadowFill}
241
- dof={false}
242
- blur={shadowBlur}
243
- />
244
- ) : (
245
- <Plane
246
- z={-deviceSize * 0.06}
247
- y={deviceSize * fh * 0.04}
248
- width={deviceSize * fw * 0.92}
249
- height={deviceSize * fh * 0.92}
250
- radius={deviceSize * fw * 0.12}
251
- background={shadowFill}
252
- dof={false}
253
- blur={shadowBlur}
254
- />
255
- )}
256
- </Group>
257
- ) : null}
258
- <div
259
- ref={holder}
260
- style={{
261
- position: "absolute",
262
- left: 0,
263
- top: 0,
264
- width,
265
- height,
266
- opacity,
267
- filter: blur > 0.5 ? `blur(${blur.toFixed(2)}px)` : undefined,
268
- }}
269
- />
270
- {device && src && lifts?.length ? (
271
- <Group {...placement}>
272
- {lifts.map((lift, i) => {
273
- // Lay the piece exactly over its spot on the screen, then raise it along the screen's normal.
274
- const k = deviceSize / device.targetSize;
275
- const toWorld = (x: number, y: number): V3 => {
276
- const p = device.imagePoint(x, y, scroll, lidAngle);
277
- return [p[0] * k, -p[1] * k, p[2] * k];
278
- };
279
- const [bx, by, bw, bh] = lift.box;
280
- const p0 = toWorld(bx, by);
281
- const ax = sub(toWorld(bx + bw, by), p0);
282
- const ay = sub(toWorld(bx, by + bh), p0);
283
- const w = len(ax);
284
- const h = len(ay);
285
- const ex = norm(ax);
286
- const ey = norm(ay);
287
- const n = norm(cross(ex, ey));
288
- // The normal must face the viewer (z+) side of the screen.
289
- const out: V3 = n[2] < 0 ? [-n[0], -n[1], -n[2]] : n;
290
- const s = lift.scale ?? 1;
291
- const c: V3 = [
292
- p0[0] + ax[0] / 2 + ay[0] / 2 + out[0] * (lift.z + 0.6) + (lift.x ?? 0),
293
- p0[1] + ax[1] / 2 + ay[1] / 2 + out[1] * (lift.z + 0.6) + (lift.y ?? 0),
294
- p0[2] + ax[2] / 2 + ay[2] / 2 + out[2] * (lift.z + 0.6),
295
- ];
296
- const basis: M4 = [
297
- ex[0] * s, ey[0] * s, out[0] * s, c[0],
298
- ex[1] * s, ey[1] * s, out[1] * s, c[1],
299
- ex[2] * s, ey[2] * s, out[2] * s, c[2],
300
- 0, 0, 0, 1,
301
- ];
302
- const fullW = w / bw;
303
- const fullH = h / bh;
304
- return (
305
- <Plane
306
- key={i}
307
- basis={basis}
308
- width={w}
309
- height={h}
310
- radius={lift.radius ?? Math.min(w, h) * 0.08}
311
- shadow={(lift.shadow ?? 0.8) * Math.min(1, lift.z / 40)}
312
- shadowDepth={Math.max(10, lift.z)}
313
- rim={lift.rim ?? 0.4}
314
- opacity={(lift.opacity ?? 1) * opacity}
315
- >
316
- <Img src={src} style={{ position: "absolute", left: -bx * fullW, top: -by * fullH, width: fullW, height: fullH }} />
317
- </Plane>
318
- );
319
- })}
320
- </Group>
321
- ) : null}
322
- </>
323
- );
324
- }
1
+ // Real 3D devices (iPhone 16 Pro Max model, MacBook, Studio Display) inside a cinematic <Stage>.
2
+ // three.js draws them on a full-frame canvas through exactly the Stage's camera, so they move, turn and
3
+ // blur with the CSS planes around them. Models come from ScreenSlick's device stage.
4
+ import { useLayoutEffect, useRef, useState } from "react";
5
+ import { Img, useDelayRender, useRemotionEnvironment, useVideoConfig } from "remotion";
6
+ import { blurFor, Group, Plane, useStageContext } from "./Cinematic";
7
+ import { mul, placementMatrix, type M4, type Placement } from "./math";
8
+ import type { DeviceRenderer, VideoDeviceModelId } from "./devices3d/runtime";
9
+
10
+ export type Device3DModel = "iphone" | "iphone-color" | "iphone-classic" | "macbook" | "macbook-pro" | "display";
11
+
12
+ const MODEL_IDS: Record<Device3DModel, VideoDeviceModelId> = {
13
+ iphone: "iphone-16-pro-max",
14
+ "iphone-color": "procedural-iphone",
15
+ "iphone-classic": "procedural-iphone",
16
+ macbook: "procedural-macbook",
17
+ "macbook-pro": "macbook-pro-14",
18
+ display: "procedural-display",
19
+ };
20
+
21
+ /** Default size: the device's largest dimension in world px. */
22
+ const DEFAULT_SIZE: Record<Device3DModel, number> = { iphone: 760, "iphone-color": 760, "iphone-classic": 760, macbook: 1250, "macbook-pro": 1250, display: 1150 };
23
+
24
+ /** Rough footprint (width, height as fractions of size) for the soft shadow behind the device. */
25
+ const FOOTPRINT: Record<Device3DModel, [number, number]> = {
26
+ iphone: [0.47, 1],
27
+ "iphone-color": [0.47, 1],
28
+ "iphone-classic": [0.47, 1],
29
+ macbook: [1, 0.62],
30
+ "macbook-pro": [1, 0.62],
31
+ display: [1, 0.86],
32
+ };
33
+
34
+ export const DEVICE_FINISHES: Record<string, string> = {
35
+ silver: "#cfd1d3",
36
+ starlight: "#d9cdb6",
37
+ "space-gray": "#6f7174",
38
+ // The deep anodised black of the current MacBook Pro (matched to a reference model).
39
+ "space-black": "#3d3c40",
40
+ // Colour iPhone finishes (iphone-color), most with calibrated logo tints in iphone-model.ts.
41
+ lavender: "#c5a4df",
42
+ "mist-blue": "#829dce",
43
+ white: "#d9dad6",
44
+ "cosmic-orange": "#c9643a",
45
+ graphite: "#6a6a6a",
46
+ midnight: "#2f3541",
47
+ black: "#3c3d40",
48
+ };
49
+
50
+ export interface Device3DProps extends Placement {
51
+ model: Device3DModel;
52
+ /**
53
+ * Your own GLB for this device (asset("library:models/…")). Required for "macbook-pro", whose model
54
+ * can't ship with Agentcut; optional for the others.
55
+ */
56
+ modelSrc?: string;
57
+ /** Screenshot on the screen (asset("assets/…")). It covers the screen; a taller one shows its top. */
58
+ src?: string;
59
+ /** Largest dimension of the device in world px (iPhone ≈ its height, MacBook ≈ its width). */
60
+ size?: number;
61
+ /**
62
+ * Hardware colour, or any hex. MacBook / display: space-black (MacBook default), space-gray, silver,
63
+ * starlight, midnight, black. iphone-color: graphite (default), lavender, mist-blue, white,
64
+ * cosmic-orange, or a brand hex. The iPhone 16 Pro Max model has its own fixed finish.
65
+ */
66
+ finish?: string;
67
+ /** MacBook lid angle in degrees: 110 open, 0 closed. Animate it for an opening shot. */
68
+ lidAngle?: number;
69
+ /** Scrolls a tall screenshot: 0 top … 1 bottom. */
70
+ scroll?: number;
71
+ /** Light: 1 normal, 0.8 moody, 1.3 bright. */
72
+ exposure?: number;
73
+ /** Soft shadow behind the device: 0 none, 1 strong. */
74
+ shadow?: number;
75
+ /** Lens blur from the Stage's focus and aperture (whole device). */
76
+ dof?: boolean;
77
+ opacity?: number;
78
+ /**
79
+ * Pieces of the screenshot that rise off the device's screen toward the camera (cards, buttons,
80
+ * charts). `box` is [x, y, w, h] in fractions of the SCREENSHOT; `z` how far it rises (world px).
81
+ */
82
+ lifts?: Device3DLift[];
83
+ }
84
+
85
+ export interface Device3DLift {
86
+ box: [number, number, number, number];
87
+ /** Rise toward the viewer, world px (animate 0 → 40–140). */
88
+ z: number;
89
+ /** Extra scale while lifted (1.0–1.15). */
90
+ scale?: number;
91
+ /** Extra offset in world px while lifted (x right, y down). */
92
+ x?: number;
93
+ y?: number;
94
+ radius?: number;
95
+ shadow?: number;
96
+ rim?: number;
97
+ opacity?: number;
98
+ }
99
+
100
+ type V3 = [number, number, number];
101
+ const sub = (a: V3, b: V3): V3 => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
102
+ const len = (a: V3) => Math.hypot(a[0], a[1], a[2]);
103
+ const norm = (a: V3): V3 => {
104
+ const l = len(a) || 1;
105
+ return [a[0] / l, a[1] / l, a[2] / l];
106
+ };
107
+ const cross = (a: V3, b: V3): V3 => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
108
+
109
+ function loadImage(src: string) {
110
+ return new Promise<HTMLImageElement>((resolve, reject) => {
111
+ const image = new Image();
112
+ image.crossOrigin = "anonymous";
113
+ image.decoding = "async";
114
+ image.onload = () => resolve(image);
115
+ image.onerror = () => reject(new Error(`Couldn't load the screen image ${src}.`));
116
+ image.src = src;
117
+ });
118
+ }
119
+
120
+ /** A real 3D device in the Stage, with a screenshot on its screen. */
121
+ export function Device3D({
122
+ model,
123
+ modelSrc,
124
+ src,
125
+ size,
126
+ finish,
127
+ lidAngle = 110,
128
+ scroll = 0,
129
+ exposure = 1,
130
+ shadow = 0.6,
131
+ dof = true,
132
+ opacity = 1,
133
+ lifts,
134
+ ...placement
135
+ }: Device3DProps) {
136
+ const ctx = useStageContext("Device3D");
137
+ const { width, height } = useVideoConfig();
138
+ const env = useRemotionEnvironment();
139
+ const { delayRender, continueRender, cancelRender } = useDelayRender();
140
+ const holder = useRef<HTMLDivElement>(null);
141
+ const pending = useRef<number | null>(null);
142
+ const [device, setDevice] = useState<DeviceRenderer | null>(null);
143
+ // The built-in MacBook defaults to space black; other devices keep their own default.
144
+ const finishName = finish ?? (model === "macbook" ? "space-black" : model === "iphone-color" ? "graphite" : undefined);
145
+ const finishColor = finishName ? (DEVICE_FINISHES[finishName] ?? finishName) : undefined;
146
+ const deviceSize = size ?? DEFAULT_SIZE[model];
147
+
148
+ // Load three, the model and the screenshot; hold the render until the first frame is drawn. A layout
149
+ // effect, so the hold exists before the commit ends (an export or capture can look for holds right
150
+ // after it) and is never created by a render React throws away.
151
+ useLayoutEffect(() => {
152
+ const box = holder.current;
153
+ if (!box) return;
154
+ // A reload (new model, finish or screenshot) holds the render again until it's drawn.
155
+ pending.current ??= delayRender(`Loading the 3D ${model}`, { timeoutInMilliseconds: 60000 });
156
+ const handle = pending.current;
157
+ let alive = true;
158
+ let created: DeviceRenderer | null = null;
159
+ const canvas = document.createElement("canvas");
160
+ canvas.style.cssText = "position:absolute;left:0;top:0;width:100%;height:100%";
161
+ box.appendChild(canvas);
162
+ const image = src ? loadImage(src) : Promise.resolve(null);
163
+ // Handled below; this keeps a failure while the model loads from being reported as unhandled.
164
+ image.catch(() => {});
165
+ (async () => {
166
+ const { createDeviceRenderer } = await import("./devices3d/runtime");
167
+ const renderer = await createDeviceRenderer(canvas, MODEL_IDS[model], finishColor, modelSrc);
168
+ if (!alive) {
169
+ renderer.dispose();
170
+ return;
171
+ }
172
+ created = renderer;
173
+ const loaded = await image;
174
+ if (!alive) return;
175
+ renderer.setImage(loaded);
176
+ setDevice(renderer);
177
+ })().catch((error) => {
178
+ if (alive) cancelRender(error);
179
+ });
180
+ return () => {
181
+ alive = false;
182
+ created?.dispose();
183
+ canvas.remove();
184
+ setDevice(null);
185
+ if (pending.current === handle) {
186
+ continueRender(handle);
187
+ pending.current = null;
188
+ }
189
+ };
190
+ }, [model, modelSrc, finishColor, src, delayRender, continueRender, cancelRender]);
191
+
192
+ const matrix = mul(ctx.view, ctx.model, placementMatrix(placement));
193
+ const centerDist = ctx.D - matrix[11];
194
+ const blur = dof ? blurFor(ctx, centerDist) : 0;
195
+ const preview = env.isPlayer && !env.isRendering;
196
+
197
+ useLayoutEffect(() => {
198
+ if (!device) return;
199
+ device.render({
200
+ width,
201
+ height,
202
+ D: ctx.D,
203
+ fov: ctx.fov,
204
+ shiftX: ctx.shiftX,
205
+ shiftY: ctx.shiftY,
206
+ matrix,
207
+ size: deviceSize,
208
+ exposure,
209
+ lidAngle,
210
+ scroll,
211
+ // The live preview draws the 3D device at half resolution; captures and exports at full.
212
+ pixelRatio: preview ? 0.5 : 1,
213
+ });
214
+ if (pending.current !== null) {
215
+ continueRender(pending.current);
216
+ pending.current = null;
217
+ }
218
+ });
219
+
220
+ const [fw, fh] = FOOTPRINT[model];
221
+ const shadowFill = `rgba(0,0,0,${Math.min(0.8, 0.45 * shadow) * opacity})`;
222
+ // World px: the Plane turns it into its own local px.
223
+ const shadowBlur = Math.max(8, deviceSize * 0.04);
224
+ // Phones float: their shadow falls on a wall behind them. Laptops and displays stand: it pools on
225
+ // the floor under them.
226
+ const laptop = model === "macbook" || model === "macbook-pro";
227
+ const standing = laptop || model === "display";
228
+ return (
229
+ <>
230
+ {shadow > 0 ? (
231
+ <Group {...placement}>
232
+ {standing ? (
233
+ <Plane
234
+ y={deviceSize * fh * 0.5}
235
+ z={laptop ? deviceSize * 0.12 : 0}
236
+ tilt={90}
237
+ width={deviceSize * (laptop ? 1.02 : 0.5)}
238
+ height={deviceSize * (laptop ? 0.72 : 0.3)}
239
+ radius={deviceSize * 0.08}
240
+ background={shadowFill}
241
+ dof={false}
242
+ blur={shadowBlur}
243
+ />
244
+ ) : (
245
+ <Plane
246
+ z={-deviceSize * 0.06}
247
+ y={deviceSize * fh * 0.04}
248
+ width={deviceSize * fw * 0.92}
249
+ height={deviceSize * fh * 0.92}
250
+ radius={deviceSize * fw * 0.12}
251
+ background={shadowFill}
252
+ dof={false}
253
+ blur={shadowBlur}
254
+ />
255
+ )}
256
+ </Group>
257
+ ) : null}
258
+ <div
259
+ ref={holder}
260
+ style={{
261
+ position: "absolute",
262
+ left: 0,
263
+ top: 0,
264
+ width,
265
+ height,
266
+ opacity,
267
+ filter: blur > 0.5 ? `blur(${blur.toFixed(2)}px)` : undefined,
268
+ }}
269
+ />
270
+ {device && src && lifts?.length ? (
271
+ <Group {...placement}>
272
+ {lifts.map((lift, i) => {
273
+ // Lay the piece exactly over its spot on the screen, then raise it along the screen's normal.
274
+ const k = deviceSize / device.targetSize;
275
+ const toWorld = (x: number, y: number): V3 => {
276
+ const p = device.imagePoint(x, y, scroll, lidAngle);
277
+ return [p[0] * k, -p[1] * k, p[2] * k];
278
+ };
279
+ const [bx, by, bw, bh] = lift.box;
280
+ const p0 = toWorld(bx, by);
281
+ const ax = sub(toWorld(bx + bw, by), p0);
282
+ const ay = sub(toWorld(bx, by + bh), p0);
283
+ const w = len(ax);
284
+ const h = len(ay);
285
+ const ex = norm(ax);
286
+ const ey = norm(ay);
287
+ const n = norm(cross(ex, ey));
288
+ // The normal must face the viewer (z+) side of the screen.
289
+ const out: V3 = n[2] < 0 ? [-n[0], -n[1], -n[2]] : n;
290
+ const s = lift.scale ?? 1;
291
+ const c: V3 = [
292
+ p0[0] + ax[0] / 2 + ay[0] / 2 + out[0] * (lift.z + 0.6) + (lift.x ?? 0),
293
+ p0[1] + ax[1] / 2 + ay[1] / 2 + out[1] * (lift.z + 0.6) + (lift.y ?? 0),
294
+ p0[2] + ax[2] / 2 + ay[2] / 2 + out[2] * (lift.z + 0.6),
295
+ ];
296
+ const basis: M4 = [
297
+ ex[0] * s, ey[0] * s, out[0] * s, c[0],
298
+ ex[1] * s, ey[1] * s, out[1] * s, c[1],
299
+ ex[2] * s, ey[2] * s, out[2] * s, c[2],
300
+ 0, 0, 0, 1,
301
+ ];
302
+ const fullW = w / bw;
303
+ const fullH = h / bh;
304
+ return (
305
+ <Plane
306
+ key={i}
307
+ basis={basis}
308
+ width={w}
309
+ height={h}
310
+ radius={lift.radius ?? Math.min(w, h) * 0.08}
311
+ shadow={(lift.shadow ?? 0.8) * Math.min(1, lift.z / 40)}
312
+ shadowDepth={Math.max(10, lift.z)}
313
+ rim={lift.rim ?? 0.4}
314
+ opacity={(lift.opacity ?? 1) * opacity}
315
+ >
316
+ <Img src={src} style={{ position: "absolute", left: -bx * fullW, top: -by * fullH, width: fullW, height: fullH }} />
317
+ </Plane>
318
+ );
319
+ })}
320
+ </Group>
321
+ ) : null}
322
+ </>
323
+ );
324
+ }