agentcut 0.2.5 → 0.2.7
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.
- package/package.json +1 -1
- package/template/components/cinematic/Cinematic.tsx +1177 -1139
- package/template/components/cinematic/Device3D.tsx +35 -10
- package/template/components/cinematic/devices3d/macbook-model.ts +78 -23
- package/template/components/cinematic/devices3d/models.ts +75 -30
- package/template/components/cinematic/devices3d/runtime.ts +18 -9
- package/template/skill/references/cinematic.md +40 -5
|
@@ -7,23 +7,27 @@ import { blurFor, Group, Plane, useStageContext } from "./Cinematic";
|
|
|
7
7
|
import { mul, placementMatrix, type M4, type Placement } from "./math";
|
|
8
8
|
import type { DeviceRenderer, VideoDeviceModelId } from "./devices3d/runtime";
|
|
9
9
|
|
|
10
|
-
export type Device3DModel = "iphone" | "iphone-classic" | "macbook" | "display";
|
|
10
|
+
export type Device3DModel = "iphone" | "iphone-color" | "iphone-classic" | "macbook" | "macbook-pro" | "display";
|
|
11
11
|
|
|
12
12
|
const MODEL_IDS: Record<Device3DModel, VideoDeviceModelId> = {
|
|
13
13
|
iphone: "iphone-16-pro-max",
|
|
14
|
+
"iphone-color": "procedural-iphone",
|
|
14
15
|
"iphone-classic": "procedural-iphone",
|
|
15
16
|
macbook: "procedural-macbook",
|
|
17
|
+
"macbook-pro": "macbook-pro-14",
|
|
16
18
|
display: "procedural-display",
|
|
17
19
|
};
|
|
18
20
|
|
|
19
21
|
/** Default size: the device's largest dimension in world px. */
|
|
20
|
-
const DEFAULT_SIZE: Record<Device3DModel, number> = { iphone: 760, "iphone-classic": 760, macbook: 1250, display: 1150 };
|
|
22
|
+
const DEFAULT_SIZE: Record<Device3DModel, number> = { iphone: 760, "iphone-color": 760, "iphone-classic": 760, macbook: 1250, "macbook-pro": 1250, display: 1150 };
|
|
21
23
|
|
|
22
24
|
/** Rough footprint (width, height as fractions of size) for the soft shadow behind the device. */
|
|
23
25
|
const FOOTPRINT: Record<Device3DModel, [number, number]> = {
|
|
24
26
|
iphone: [0.47, 1],
|
|
27
|
+
"iphone-color": [0.47, 1],
|
|
25
28
|
"iphone-classic": [0.47, 1],
|
|
26
29
|
macbook: [1, 0.62],
|
|
30
|
+
"macbook-pro": [1, 0.62],
|
|
27
31
|
display: [1, 0.86],
|
|
28
32
|
};
|
|
29
33
|
|
|
@@ -31,17 +35,34 @@ export const DEVICE_FINISHES: Record<string, string> = {
|
|
|
31
35
|
silver: "#cfd1d3",
|
|
32
36
|
starlight: "#d9cdb6",
|
|
33
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",
|
|
34
46
|
midnight: "#2f3541",
|
|
35
47
|
black: "#3c3d40",
|
|
36
48
|
};
|
|
37
49
|
|
|
38
50
|
export interface Device3DProps extends Placement {
|
|
39
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;
|
|
40
57
|
/** Screenshot on the screen (asset("assets/…")). It covers the screen; a taller one shows its top. */
|
|
41
58
|
src?: string;
|
|
42
59
|
/** Largest dimension of the device in world px (iPhone ≈ its height, MacBook ≈ its width). */
|
|
43
60
|
size?: number;
|
|
44
|
-
/**
|
|
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
|
+
*/
|
|
45
66
|
finish?: string;
|
|
46
67
|
/** MacBook lid angle in degrees: 110 open, 0 closed. Animate it for an opening shot. */
|
|
47
68
|
lidAngle?: number;
|
|
@@ -99,6 +120,7 @@ function loadImage(src: string) {
|
|
|
99
120
|
/** A real 3D device in the Stage, with a screenshot on its screen. */
|
|
100
121
|
export function Device3D({
|
|
101
122
|
model,
|
|
123
|
+
modelSrc,
|
|
102
124
|
src,
|
|
103
125
|
size,
|
|
104
126
|
finish,
|
|
@@ -118,7 +140,9 @@ export function Device3D({
|
|
|
118
140
|
const holder = useRef<HTMLDivElement>(null);
|
|
119
141
|
const pending = useRef<number | null>(null);
|
|
120
142
|
const [device, setDevice] = useState<DeviceRenderer | null>(null);
|
|
121
|
-
|
|
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;
|
|
122
146
|
const deviceSize = size ?? DEFAULT_SIZE[model];
|
|
123
147
|
|
|
124
148
|
// Load three, the model and the screenshot; hold the render until the first frame is drawn. A layout
|
|
@@ -140,7 +164,7 @@ export function Device3D({
|
|
|
140
164
|
image.catch(() => {});
|
|
141
165
|
(async () => {
|
|
142
166
|
const { createDeviceRenderer } = await import("./devices3d/runtime");
|
|
143
|
-
const renderer = await createDeviceRenderer(canvas, MODEL_IDS[model], finishColor);
|
|
167
|
+
const renderer = await createDeviceRenderer(canvas, MODEL_IDS[model], finishColor, modelSrc);
|
|
144
168
|
if (!alive) {
|
|
145
169
|
renderer.dispose();
|
|
146
170
|
return;
|
|
@@ -163,7 +187,7 @@ export function Device3D({
|
|
|
163
187
|
pending.current = null;
|
|
164
188
|
}
|
|
165
189
|
};
|
|
166
|
-
}, [model, finishColor, src, delayRender, continueRender, cancelRender]);
|
|
190
|
+
}, [model, modelSrc, finishColor, src, delayRender, continueRender, cancelRender]);
|
|
167
191
|
|
|
168
192
|
const matrix = mul(ctx.view, ctx.model, placementMatrix(placement));
|
|
169
193
|
const centerDist = ctx.D - matrix[11];
|
|
@@ -199,7 +223,8 @@ export function Device3D({
|
|
|
199
223
|
const shadowBlur = Math.max(8, deviceSize * 0.04);
|
|
200
224
|
// Phones float: their shadow falls on a wall behind them. Laptops and displays stand: it pools on
|
|
201
225
|
// the floor under them.
|
|
202
|
-
const
|
|
226
|
+
const laptop = model === "macbook" || model === "macbook-pro";
|
|
227
|
+
const standing = laptop || model === "display";
|
|
203
228
|
return (
|
|
204
229
|
<>
|
|
205
230
|
{shadow > 0 ? (
|
|
@@ -207,10 +232,10 @@ export function Device3D({
|
|
|
207
232
|
{standing ? (
|
|
208
233
|
<Plane
|
|
209
234
|
y={deviceSize * fh * 0.5}
|
|
210
|
-
z={
|
|
235
|
+
z={laptop ? deviceSize * 0.12 : 0}
|
|
211
236
|
tilt={90}
|
|
212
|
-
width={deviceSize * (
|
|
213
|
-
height={deviceSize * (
|
|
237
|
+
width={deviceSize * (laptop ? 1.02 : 0.5)}
|
|
238
|
+
height={deviceSize * (laptop ? 0.72 : 0.3)}
|
|
214
239
|
radius={deviceSize * 0.08}
|
|
215
240
|
background={shadowFill}
|
|
216
241
|
dof={false}
|
|
@@ -155,7 +155,8 @@ function createLegendTexture(
|
|
|
155
155
|
keys: KeyRect[],
|
|
156
156
|
bounds: { x: number; z: number; w: number; d: number },
|
|
157
157
|
) {
|
|
158
|
-
|
|
158
|
+
// Dense enough that the legends stay crisp in close-ups.
|
|
159
|
+
const pxPerMm = 14;
|
|
159
160
|
const width = Math.ceil(bounds.w * pxPerMm);
|
|
160
161
|
const height = Math.ceil(bounds.d * pxPerMm);
|
|
161
162
|
const canvas = createCanvas(width, height);
|
|
@@ -166,7 +167,8 @@ function createLegendTexture(
|
|
|
166
167
|
| undefined;
|
|
167
168
|
if (!canvas || !context) return null;
|
|
168
169
|
context.clearRect(0, 0, width, height);
|
|
169
|
-
|
|
170
|
+
// Bright, slightly bold legends: backlit-key white that reads against the black caps.
|
|
171
|
+
context.fillStyle = "#ffffff";
|
|
170
172
|
context.textBaseline = "middle";
|
|
171
173
|
for (const key of keys) {
|
|
172
174
|
if (!key.label) continue;
|
|
@@ -175,7 +177,7 @@ function createLegendTexture(
|
|
|
175
177
|
const keyWidth = key.w * pxPerMm;
|
|
176
178
|
const keyDepth = key.d * pxPerMm;
|
|
177
179
|
if (key.kind === "mod") {
|
|
178
|
-
context.font = `
|
|
180
|
+
context.font = `600 ${Math.round(2.5 * pxPerMm)}px -apple-system, "SF Pro Text", "Helvetica Neue", Arial, sans-serif`;
|
|
179
181
|
context.textAlign = "left";
|
|
180
182
|
context.fillText(
|
|
181
183
|
key.label,
|
|
@@ -184,8 +186,8 @@ function createLegendTexture(
|
|
|
184
186
|
keyWidth - 3 * pxPerMm,
|
|
185
187
|
);
|
|
186
188
|
} else {
|
|
187
|
-
const fontSize = key.kind === "half" ? 2.
|
|
188
|
-
context.font = `
|
|
189
|
+
const fontSize = key.kind === "half" ? 2.6 : 3.9;
|
|
190
|
+
context.font = `600 ${Math.round(fontSize * pxPerMm)}px -apple-system, "SF Pro Text", "Helvetica Neue", Arial, sans-serif`;
|
|
189
191
|
context.textAlign = "center";
|
|
190
192
|
context.fillText(
|
|
191
193
|
key.label,
|
|
@@ -197,7 +199,31 @@ function createLegendTexture(
|
|
|
197
199
|
}
|
|
198
200
|
const texture = new THREE.CanvasTexture(canvas as HTMLCanvasElement);
|
|
199
201
|
texture.colorSpace = THREE.SRGBColorSpace;
|
|
200
|
-
texture.anisotropy =
|
|
202
|
+
texture.anisotropy = 8;
|
|
203
|
+
return texture;
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
/** Speaker grille: a fine field of dark perforations on a transparent texture. */
|
|
207
|
+
function createGrilleTexture(widthMm: number, depthMm: number) {
|
|
208
|
+
const pxPerMm = 12;
|
|
209
|
+
const width = Math.ceil(widthMm * pxPerMm);
|
|
210
|
+
const height = Math.ceil(depthMm * pxPerMm);
|
|
211
|
+
const canvas = createCanvas(width, height);
|
|
212
|
+
const context = canvas?.getContext("2d") as CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D | null | undefined;
|
|
213
|
+
if (!canvas || !context) return null;
|
|
214
|
+
context.clearRect(0, 0, width, height);
|
|
215
|
+
context.fillStyle = "rgba(6, 6, 8, 0.85)";
|
|
216
|
+
const pitch = 1.15 * pxPerMm;
|
|
217
|
+
for (let y = pitch / 2, row = 0; y < height; y += pitch * 0.87, row++) {
|
|
218
|
+
for (let x = pitch / 2 + (row % 2) * (pitch / 2); x < width; x += pitch) {
|
|
219
|
+
context.beginPath();
|
|
220
|
+
context.arc(x, y, 0.32 * pxPerMm, 0, Math.PI * 2);
|
|
221
|
+
context.fill();
|
|
222
|
+
}
|
|
223
|
+
}
|
|
224
|
+
const texture = new THREE.CanvasTexture(canvas as HTMLCanvasElement);
|
|
225
|
+
texture.colorSpace = THREE.SRGBColorSpace;
|
|
226
|
+
texture.anisotropy = 8;
|
|
201
227
|
return texture;
|
|
202
228
|
}
|
|
203
229
|
|
|
@@ -220,40 +246,48 @@ function createLogoGeometry(width: number) {
|
|
|
220
246
|
function createMaterials(finishColor: THREE.ColorRepresentation) {
|
|
221
247
|
const finish = new THREE.Color(finishColor);
|
|
222
248
|
const { l: lightness } = finish.getHSL({ h: 0, s: 0, l: 0 });
|
|
223
|
-
|
|
249
|
+
// Space black and darker finishes count as dark.
|
|
250
|
+
const isDark = lightness < 0.4;
|
|
224
251
|
return {
|
|
252
|
+
// Bead-blasted anodised aluminium: soft, wide highlights, the finish's own colour in the shadows.
|
|
253
|
+
// Dark finishes (space black) reflect much less of the studio, like real dark anodising: otherwise a
|
|
254
|
+
// low camera facing the deck sees the bright environment and the black washes out to light grey.
|
|
225
255
|
aluminum: new THREE.MeshPhysicalMaterial({
|
|
226
256
|
color: finish,
|
|
227
|
-
metalness: 0.
|
|
228
|
-
roughness: 0.
|
|
229
|
-
clearcoat: 0.
|
|
230
|
-
clearcoatRoughness: 0.
|
|
257
|
+
metalness: isDark ? 0.55 : 0.85,
|
|
258
|
+
roughness: isDark ? 0.48 : 0.34,
|
|
259
|
+
clearcoat: isDark ? 0.04 : 0.18,
|
|
260
|
+
clearcoatRoughness: 0.4,
|
|
261
|
+
envMapIntensity: isDark ? 0.3 : 0.75,
|
|
231
262
|
}),
|
|
232
263
|
edge: new THREE.MeshPhysicalMaterial({
|
|
233
264
|
color: finish.clone().lerp(new THREE.Color(0xffffff), isDark ? 0.08 : 0.2),
|
|
234
|
-
metalness: 1,
|
|
235
|
-
roughness: 0.22,
|
|
265
|
+
metalness: isDark ? 0.85 : 1,
|
|
266
|
+
roughness: isDark ? 0.3 : 0.22,
|
|
267
|
+
envMapIntensity: isDark ? 0.55 : 1,
|
|
236
268
|
}),
|
|
237
269
|
trackpad: new THREE.MeshPhysicalMaterial({
|
|
238
|
-
color: finish.clone().lerp(new THREE.Color(0x000000), 0.
|
|
239
|
-
metalness: 0.
|
|
240
|
-
roughness: 0.
|
|
241
|
-
clearcoat: 0.6,
|
|
270
|
+
color: finish.clone().lerp(new THREE.Color(0x000000), isDark ? 0.12 : 0.06),
|
|
271
|
+
metalness: isDark ? 0.4 : 0.5,
|
|
272
|
+
roughness: isDark ? 0.36 : 0.28,
|
|
273
|
+
clearcoat: isDark ? 0.25 : 0.6,
|
|
242
274
|
clearcoatRoughness: 0.18,
|
|
275
|
+
envMapIntensity: isDark ? 0.28 : 0.6,
|
|
243
276
|
}),
|
|
244
277
|
well: new THREE.MeshStandardMaterial({
|
|
245
278
|
color: 0x050506,
|
|
246
279
|
roughness: 0.85,
|
|
247
280
|
metalness: 0,
|
|
248
|
-
|
|
281
|
+
envMapIntensity: 0.06,
|
|
249
282
|
}),
|
|
250
283
|
key: new THREE.MeshPhysicalMaterial({
|
|
251
|
-
color:
|
|
252
|
-
roughness: 0.
|
|
284
|
+
color: 0x0a0a0c,
|
|
285
|
+
roughness: 0.7,
|
|
253
286
|
metalness: 0.05,
|
|
254
|
-
clearcoat: 0.
|
|
255
|
-
|
|
287
|
+
clearcoat: 0.05,
|
|
288
|
+
envMapIntensity: 0.16,
|
|
256
289
|
}),
|
|
290
|
+
grille: new THREE.MeshBasicMaterial({ transparent: true, depthWrite: false }),
|
|
257
291
|
legends: new THREE.MeshBasicMaterial({
|
|
258
292
|
transparent: true,
|
|
259
293
|
depthWrite: false,
|
|
@@ -272,7 +306,7 @@ function createMaterials(finishColor: THREE.ColorRepresentation) {
|
|
|
272
306
|
metalness: 0.8,
|
|
273
307
|
roughness: 0.35,
|
|
274
308
|
}),
|
|
275
|
-
rubber: new THREE.MeshStandardMaterial({ color: 0x18181a, roughness: 0.9 }),
|
|
309
|
+
rubber: new THREE.MeshStandardMaterial({ color: 0x18181a, roughness: 0.9, envMapIntensity: 0.2 }),
|
|
276
310
|
logo: new THREE.MeshPhysicalMaterial({
|
|
277
311
|
color: finish
|
|
278
312
|
.clone()
|
|
@@ -404,6 +438,27 @@ export function createMacbookModel(options: MacbookModelOptions = {}) {
|
|
|
404
438
|
legends.renderOrder = 2;
|
|
405
439
|
}
|
|
406
440
|
|
|
441
|
+
// ── Speaker grilles either side of the keyboard ─────────────────────
|
|
442
|
+
const sideRoom = (BASE.w - keyboardBounds.w) / 2;
|
|
443
|
+
const grilleW = Math.min(12, sideRoom - 6);
|
|
444
|
+
const grilleTexture = grilleW > 3 ? createGrilleTexture(grilleW, keyboardBounds.d) : null;
|
|
445
|
+
if (grilleTexture) {
|
|
446
|
+
materials.grille.map = grilleTexture;
|
|
447
|
+
for (const side of [-1, 1]) {
|
|
448
|
+
const grille = add(
|
|
449
|
+
"laptop-speaker-grille",
|
|
450
|
+
new THREE.Mesh(new THREE.PlaneGeometry(mm(grilleW), mm(keyboardBounds.d)).rotateX(-Math.PI / 2), materials.grille),
|
|
451
|
+
);
|
|
452
|
+
grille.castShadow = false;
|
|
453
|
+
grille.position.set(
|
|
454
|
+
side * mm(keyboardBounds.w / 2 + sideRoom / 2),
|
|
455
|
+
mm(0.3),
|
|
456
|
+
mm(keyboardBounds.z + keyboardBounds.d / 2),
|
|
457
|
+
);
|
|
458
|
+
grille.renderOrder = 2;
|
|
459
|
+
}
|
|
460
|
+
}
|
|
461
|
+
|
|
407
462
|
// ── Trackpad and front lip ──────────────────────────────────────────
|
|
408
463
|
const trackpadCenterZ =
|
|
409
464
|
keyboardBounds.z + keyboardBounds.d + TRACKPAD.gap + TRACKPAD.h / 2;
|
|
@@ -15,6 +15,7 @@ export type VideoDeviceModelId =
|
|
|
15
15
|
| "procedural-iphone"
|
|
16
16
|
| "iphone-16-pro-max"
|
|
17
17
|
| "procedural-macbook"
|
|
18
|
+
| "macbook-pro-14"
|
|
18
19
|
| "procedural-display";
|
|
19
20
|
|
|
20
21
|
export interface VideoDeviceModelConfig {
|
|
@@ -27,6 +28,10 @@ export interface VideoDeviceModelConfig {
|
|
|
27
28
|
screenMeshName?: string;
|
|
28
29
|
screenMaterialName?: string;
|
|
29
30
|
screenUvMirrorX: boolean;
|
|
31
|
+
/** Keep the screen mesh's own UVs (they already map a full screen image) instead of reprojecting. */
|
|
32
|
+
keepScreenUvs?: boolean;
|
|
33
|
+
/** Not bundled (its licence forbids redistribution): the scene must pass its own copy as modelSrc. */
|
|
34
|
+
external?: boolean;
|
|
30
35
|
shadowMode: "silhouette" | "base";
|
|
31
36
|
shadowSilhouetteMeshNames?: string[];
|
|
32
37
|
mappingVersion: number;
|
|
@@ -331,6 +336,29 @@ export const VIDEO_DEVICE_MODEL_CONFIGS: Record<
|
|
|
331
336
|
cameraY: 0.05,
|
|
332
337
|
credit: "Original ScreenSlick procedural model",
|
|
333
338
|
},
|
|
339
|
+
"macbook-pro-14": {
|
|
340
|
+
id: "macbook-pro-14",
|
|
341
|
+
name: "MacBook Pro 14-inch",
|
|
342
|
+
category: "laptop",
|
|
343
|
+
// Sketchfab "MacBook Pro 14-inch M5" (Standard licence): users bring their own copy (modelSrc).
|
|
344
|
+
external: true,
|
|
345
|
+
// 3024 × 1964 Liquid Retina XDR.
|
|
346
|
+
screenAspect: 3024 / 1964,
|
|
347
|
+
screenFit: "cover",
|
|
348
|
+
screenMaterialName: "HlQwFCAPWzetDQy",
|
|
349
|
+
screenUvMirrorX: false,
|
|
350
|
+
keepScreenUvs: true,
|
|
351
|
+
shadowMode: "silhouette",
|
|
352
|
+
mappingVersion: 1,
|
|
353
|
+
// glTF UVs put the image's top at v = 0.
|
|
354
|
+
textureFlipY: false,
|
|
355
|
+
textureMirrorX: false,
|
|
356
|
+
targetSize: 2,
|
|
357
|
+
rotation: [0, 0, 0],
|
|
358
|
+
cameraZ: 4.2,
|
|
359
|
+
cameraY: 0.05,
|
|
360
|
+
credit: "MacBook Pro 14-inch (M5) model",
|
|
361
|
+
},
|
|
334
362
|
"procedural-display": {
|
|
335
363
|
id: "procedural-display",
|
|
336
364
|
name: "Studio Display",
|
|
@@ -353,8 +381,8 @@ export const VIDEO_DEVICE_MODEL_CONFIGS: Record<
|
|
|
353
381
|
|
|
354
382
|
const MODEL_FALLBACK_ORIGIN = "https://agentcut.synteq.app";
|
|
355
383
|
|
|
356
|
-
const templatePromises = new Map<
|
|
357
|
-
const templates = new Map<
|
|
384
|
+
const templatePromises = new Map<string, Promise<THREE.Group>>();
|
|
385
|
+
const templates = new Map<string, THREE.Group>();
|
|
358
386
|
|
|
359
387
|
function cloneModelTemplate(template: THREE.Group) {
|
|
360
388
|
const clone = template.clone(true);
|
|
@@ -464,33 +492,48 @@ function projectScreenUvs(screen: THREE.Mesh, config: VideoDeviceModelConfig) {
|
|
|
464
492
|
screen.userData.ownsVideoScreenGeometry = true;
|
|
465
493
|
}
|
|
466
494
|
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
495
|
+
/** Cache key: a model id, plus the file when the caller brings its own (modelSrc). */
|
|
496
|
+
const templateKey = (id: VideoDeviceModelId, source?: string) => (source ? `${id}|${source}` : id);
|
|
497
|
+
|
|
498
|
+
/** The GLB a model loads: the caller's own file (bring-your-own models), else the bundled one. */
|
|
499
|
+
function modelSource(id: VideoDeviceModelId, sourceOverride?: string) {
|
|
500
|
+
return sourceOverride || VIDEO_DEVICE_MODEL_CONFIGS[id]?.source || "";
|
|
501
|
+
}
|
|
502
|
+
|
|
503
|
+
export async function preloadVideoDeviceModel(id: VideoDeviceModelId, sourceOverride?: string) {
|
|
504
|
+
const config = VIDEO_DEVICE_MODEL_CONFIGS[id];
|
|
505
|
+
if (!config) return;
|
|
506
|
+
const source = modelSource(id, sourceOverride);
|
|
507
|
+
if (!source) {
|
|
508
|
+
if (config.external) {
|
|
509
|
+
throw new Error(
|
|
510
|
+
`The ${config.name} model isn't bundled with Agentcut (its licence doesn't allow redistribution): pass your own copy with modelSrc.`,
|
|
511
|
+
);
|
|
512
|
+
}
|
|
513
|
+
return;
|
|
514
|
+
}
|
|
515
|
+
const key = templateKey(id, sourceOverride);
|
|
516
|
+
if (templates.has(key)) return;
|
|
517
|
+
const existing = templatePromises.get(key);
|
|
470
518
|
if (existing) {
|
|
471
519
|
await existing;
|
|
472
520
|
return;
|
|
473
521
|
}
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
const
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
(
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
templatePromises.delete(id);
|
|
490
|
-
throw error;
|
|
491
|
-
},
|
|
492
|
-
);
|
|
493
|
-
templatePromises.set(id, promise);
|
|
522
|
+
// The studio serves bundled models from its own origin; a local render (no /models there) fetches
|
|
523
|
+
// them from the public site. A model the user brings is loaded only from where they put it.
|
|
524
|
+
const first = new GLTFLoader().loadAsync(source);
|
|
525
|
+
const promise = (sourceOverride ? first : first.catch(() => new GLTFLoader().loadAsync(`${MODEL_FALLBACK_ORIGIN}${source}`))).then(
|
|
526
|
+
(gltf) => {
|
|
527
|
+
templates.set(key, gltf.scene);
|
|
528
|
+
return gltf.scene;
|
|
529
|
+
},
|
|
530
|
+
(error: unknown) => {
|
|
531
|
+
// Forget the failure so the next device (or a retry) loads again instead of failing for good.
|
|
532
|
+
templatePromises.delete(key);
|
|
533
|
+
throw error;
|
|
534
|
+
},
|
|
535
|
+
);
|
|
536
|
+
templatePromises.set(key, promise);
|
|
494
537
|
await promise;
|
|
495
538
|
}
|
|
496
539
|
|
|
@@ -498,10 +541,11 @@ export function createPreloadedVideoDeviceModel(
|
|
|
498
541
|
id: VideoDeviceModelId,
|
|
499
542
|
screenMaterial: THREE.Material,
|
|
500
543
|
finishColor?: THREE.ColorRepresentation,
|
|
544
|
+
sourceOverride?: string,
|
|
501
545
|
): LoadedVideoDeviceModel | null {
|
|
502
546
|
const config = VIDEO_DEVICE_MODEL_CONFIGS[id];
|
|
503
547
|
if (!config) return null;
|
|
504
|
-
if (!config.
|
|
548
|
+
if (!modelSource(id, sourceOverride) && !config.external) {
|
|
505
549
|
const root =
|
|
506
550
|
id === "procedural-iphone"
|
|
507
551
|
? createIphoneVideoMockupModel({ screenMaterial, finishColor })
|
|
@@ -524,7 +568,7 @@ export function createPreloadedVideoDeviceModel(
|
|
|
524
568
|
};
|
|
525
569
|
}
|
|
526
570
|
|
|
527
|
-
const template = templates.get(id);
|
|
571
|
+
const template = templates.get(templateKey(id, sourceOverride));
|
|
528
572
|
if (!template) return null;
|
|
529
573
|
const modelRoot = cloneModelTemplate(template);
|
|
530
574
|
const screen = findScreenMesh(modelRoot, config);
|
|
@@ -533,7 +577,7 @@ export function createPreloadedVideoDeviceModel(
|
|
|
533
577
|
return null;
|
|
534
578
|
}
|
|
535
579
|
modelRoot.updateMatrixWorld(true);
|
|
536
|
-
projectScreenUvs(screen, config);
|
|
580
|
+
if (!config.keepScreenUvs) projectScreenUvs(screen, config);
|
|
537
581
|
const previousScreenMaterials = Array.isArray(screen.material)
|
|
538
582
|
? screen.material
|
|
539
583
|
: [screen.material];
|
|
@@ -557,9 +601,10 @@ export async function loadVideoDeviceModel(
|
|
|
557
601
|
id: VideoDeviceModelId,
|
|
558
602
|
screenMaterial: THREE.Material,
|
|
559
603
|
finishColor?: THREE.ColorRepresentation,
|
|
604
|
+
sourceOverride?: string,
|
|
560
605
|
) {
|
|
561
|
-
await preloadVideoDeviceModel(id);
|
|
562
|
-
return createPreloadedVideoDeviceModel(id, screenMaterial, finishColor);
|
|
606
|
+
await preloadVideoDeviceModel(id, sourceOverride);
|
|
607
|
+
return createPreloadedVideoDeviceModel(id, screenMaterial, finishColor, sourceOverride);
|
|
563
608
|
}
|
|
564
609
|
|
|
565
610
|
export function disposeVideoDeviceModel(model: LoadedVideoDeviceModel) {
|
|
@@ -82,6 +82,8 @@ export async function createDeviceRenderer(
|
|
|
82
82
|
canvas: HTMLCanvasElement,
|
|
83
83
|
id: VideoDeviceModelId,
|
|
84
84
|
finishColor?: string,
|
|
85
|
+
/** A GLB the user brings (in place of the bundled model, or required for external models). */
|
|
86
|
+
modelSrc?: string,
|
|
85
87
|
): Promise<DeviceRenderer> {
|
|
86
88
|
const renderer = new THREE.WebGLRenderer({ canvas, alpha: true, antialias: true, preserveDrawingBuffer: true });
|
|
87
89
|
renderer.setPixelRatio(1);
|
|
@@ -102,15 +104,20 @@ export async function createDeviceRenderer(
|
|
|
102
104
|
});
|
|
103
105
|
pmrem.dispose();
|
|
104
106
|
scene.environment = environment;
|
|
107
|
+
// Laptops and displays are big flat aluminium and black keys: a softer, darker studio keeps the
|
|
108
|
+
// anodised finish and the keyboard from washing out. Phones keep the brighter rig.
|
|
109
|
+
const studio = id === "procedural-macbook" || id === "macbook-pro-14" || id === "procedural-display";
|
|
110
|
+
scene.environmentIntensity = studio ? 0.6 : 1;
|
|
111
|
+
const baseExposure = studio ? 0.98 : 1.12;
|
|
105
112
|
|
|
106
113
|
const camera = new THREE.PerspectiveCamera(24, 16 / 9, 1, 100000);
|
|
107
114
|
scene.add(camera);
|
|
108
|
-
scene.add(new THREE.HemisphereLight(0xf1f5ff, 0x14161b, 1.4));
|
|
115
|
+
scene.add(new THREE.HemisphereLight(0xf1f5ff, 0x14161b, studio ? 0.35 : 1.4));
|
|
109
116
|
// Lights ride with the camera so every angle stays product-lit (ScreenSlick's rig).
|
|
110
117
|
for (const [color, intensity, position] of [
|
|
111
|
-
[0xfff4e7, 5.2, [-2.8, 3.4, 4.4]],
|
|
112
|
-
[0x86aaff, 3.1, [3.5, 1.5, -3.2]],
|
|
113
|
-
[0xffffff, 1.4, [1.8, -1.4, 3.2]],
|
|
118
|
+
[0xfff4e7, studio ? 3.4 : 5.2, [-2.8, 3.4, 4.4]],
|
|
119
|
+
[0x86aaff, studio ? 2.4 : 3.1, [3.5, 1.5, -3.2]],
|
|
120
|
+
[0xffffff, studio ? 0.6 : 1.4, [1.8, -1.4, 3.2]],
|
|
114
121
|
] as const) {
|
|
115
122
|
const light = new THREE.DirectionalLight(color, intensity);
|
|
116
123
|
light.position.set(position[0], position[1], position[2]);
|
|
@@ -135,7 +142,7 @@ export async function createDeviceRenderer(
|
|
|
135
142
|
|
|
136
143
|
let model: LoadedVideoDeviceModel | null = null;
|
|
137
144
|
try {
|
|
138
|
-
model = await loadVideoDeviceModel(id, screenMaterial, finishColor);
|
|
145
|
+
model = await loadVideoDeviceModel(id, screenMaterial, finishColor, modelSrc);
|
|
139
146
|
if (!model) throw new Error(`Couldn't load the ${id} device model.`);
|
|
140
147
|
} catch (error) {
|
|
141
148
|
// Free the GPU side before giving up: a failed load must not keep a WebGL context alive.
|
|
@@ -163,7 +170,9 @@ export async function createDeviceRenderer(
|
|
|
163
170
|
if (imageAspect > screenAspect) repeatX = screenAspect / imageAspect;
|
|
164
171
|
else repeatY = imageAspect / screenAspect;
|
|
165
172
|
const offsetX = (1 - repeatX) / 2;
|
|
166
|
-
const
|
|
173
|
+
const s = Math.min(1, Math.max(0, scroll));
|
|
174
|
+
// flipY puts the image's top at v = 1; without it (glTF UVs) the top is at v = 0.
|
|
175
|
+
const offsetY = (1 - repeatY) * (model.config.textureFlipY ? 1 - s : s);
|
|
167
176
|
const mirror = model.config.textureMirrorX;
|
|
168
177
|
return { tx: mirror ? 1 - offsetX : offsetX, ty: offsetY, sx: mirror ? -repeatX : repeatX, sy: repeatY };
|
|
169
178
|
};
|
|
@@ -191,9 +200,9 @@ export async function createDeviceRenderer(
|
|
|
191
200
|
holder.updateMatrixWorld(true);
|
|
192
201
|
relative.copy(holder.matrixWorld).invert().multiply(model.screen.matrixWorld);
|
|
193
202
|
const f = uvFit(scroll);
|
|
194
|
-
//
|
|
203
|
+
// With flipY image v runs up (the top of the screenshot is v = 1); without it, v runs down.
|
|
195
204
|
const u = (x - f.tx) / f.sx;
|
|
196
|
-
const v = (1 - y - f.ty) / f.sy;
|
|
205
|
+
const v = ((model.config.textureFlipY ? 1 - y : y) - f.ty) / f.sy;
|
|
197
206
|
const frame = model.screenFrame;
|
|
198
207
|
point.copy(frame.origin).addScaledVector(frame.du, u).addScaledVector(frame.dv, v).applyMatrix4(relative);
|
|
199
208
|
return [point.x, point.y, point.z];
|
|
@@ -221,7 +230,7 @@ export async function createDeviceRenderer(
|
|
|
221
230
|
renderer.setPixelRatio(p.pixelRatio);
|
|
222
231
|
renderer.setSize(p.width, p.height, false);
|
|
223
232
|
}
|
|
224
|
-
renderer.toneMappingExposure =
|
|
233
|
+
renderer.toneMappingExposure = baseExposure * p.exposure;
|
|
225
234
|
if (p.scroll !== lastScroll) fitTexture(p.scroll);
|
|
226
235
|
if (id === "procedural-macbook") setMacbookLidAngle(model.root, p.lidAngle);
|
|
227
236
|
|
|
@@ -40,12 +40,12 @@ narrower moves).
|
|
|
40
40
|
tilt small (5–20) with some `turn` and `roll`.
|
|
41
41
|
- `fov`: 15–25 flat telephoto (default 24, product look), 35 natural, 50–70 dramatic close-ups.
|
|
42
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
|
|
43
|
+
the target. `aperture`: 0 none, 0.4 subtle, 1 strong, 2.5–4 macro (see Macro focus), 6+ a razor line. Focus and aperture animate: a rack
|
|
44
44
|
focus is two keys with different `focus` points.
|
|
45
45
|
- `shiftX`, `shiftY`: move the subject off-center (fractions of the frame) to leave room for a title.
|
|
46
46
|
- `float` 0–1: handheld drift (0.3–0.6 on holds keeps them alive). `motionBlur` 0–1: blur on fast moves.
|
|
47
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`), `
|
|
48
|
+
`videoProps` for `volume`, `loop`, `trimBefore`…) or `children` (live React UI) in a device. `kind`: `browser` (+ `url`), `iphone`, `ipad`,
|
|
49
49
|
`monitor`, `none`. `width` is the SCREEN width. Set `aspect` to the screenshot's width/height when it
|
|
50
50
|
differs from the device (or `imageAspect` + `scroll` 0→1 to scroll a tall page). `finish`: `black` /
|
|
51
51
|
`silver` (hardware), `light` / `dark` (browser). Extras: `shadow` (0.7), `reflection` (0–0.5 on dark
|
|
@@ -53,14 +53,27 @@ narrower moves).
|
|
|
53
53
|
- `<Device3D model src size lifts ...placement>` — **real 3D hardware**, and the default for every phone,
|
|
54
54
|
laptop and desktop shot (three.js, drawn through the same camera, studio-lit with real reflections):
|
|
55
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-
|
|
56
|
+
`lidAngle` 0→110), `display` (Studio Display on its foot), `iphone-color` (a modern iPhone in colour: `finish` `graphite` (default), `lavender`, `mist-blue`,
|
|
57
|
+
`white`, `cosmic-orange`, or the brand's hex; pick a colour that suits the palette, show the back in
|
|
58
|
+
orbits and turn-arounds, and use several colours side by side for "for everyone" shots). `src` is the screenshot
|
|
57
59
|
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` `
|
|
60
|
+
largest dimension in world px (defaults 760 / 1250 / 1150), `finish` `space-black` (MacBook default) `space-gray` `silver` `starlight`
|
|
59
61
|
`midnight` `black` (MacBook, display), `exposure`, `shadow`. `lifts`: pieces of the screenshot that rise
|
|
60
62
|
off the device's screen, `[{ box: [x, y, w, h] (fractions of the SCREENSHOT), z, scale, radius }]` —
|
|
61
63
|
they follow the screen's angle, even on an opening lid. Devices blur as a whole with the lens. Credit
|
|
62
64
|
the iPhone model in the hand-off: "iPhone 16 Pro Max model by MajdyModels, CC BY 4.0".
|
|
63
|
-
|
|
65
|
+
**Better laptop if the workspace has one:** check `library/models/` for a user-supplied GLB (e.g.
|
|
66
|
+
`macbook-pro-14.glb`, a Sketchfab "MacBook Pro 14-inch M5" under a licence that forbids bundling it).
|
|
67
|
+
If it's there, prefer `model="macbook-pro" modelSrc={asset("library:models/macbook-pro-14.glb")}` for
|
|
68
|
+
laptop shots: it's far more detailed than the built-in `macbook`. Its lid doesn't open (`lidAngle` is
|
|
69
|
+
ignored), so use the built-in `macbook` for lid-opening shots. Never copy such a model into a project's
|
|
70
|
+
assets or anywhere it would be shared. If it isn't there and the user wants the most realistic laptop,
|
|
71
|
+
tell them they can download it free (their own Sketchfab "Free Standard" licence, fine for their
|
|
72
|
+
videos) from https://sketchfab.com/3d-models/macbook-pro-14-inch-m5-652a992f4f244122ae251f9cbb81da1e
|
|
73
|
+
(the "glb · Original format" download) and save it as `library/models/macbook-pro-14.glb` in the
|
|
74
|
+
workspace. Use `modelSrc` only with `macbook-pro` (or `iphone` with a copy of the same GLB): the
|
|
75
|
+
built-in `macbook`, `display`, `iphone-color` and `iphone-classic` are drawn in code and can't take a GLB.
|
|
76
|
+
- **Never** use the flat `Screen` `iphone` / `ipad` / `monitor` frames when the shot shows the
|
|
64
77
|
device: they look like clip-art next to the 3D models. Flat `Screen` is for browser windows
|
|
65
78
|
(`kind="browser"`), frameless UI (`kind="none"`), giant readable close-ups where the hardware is off
|
|
66
79
|
frame, and tall pages you fly over with `scroll`.
|
|
@@ -113,6 +126,7 @@ narrower moves).
|
|
|
113
126
|
| Hero push | same angle, zoom +15–25 % over the shot, `inOut`, `float 0.4` |
|
|
114
127
|
| Rack focus | camera still or drifting; `focus` from region A to B over 20–30 f, `aperture 0.9–1.3` |
|
|
115
128
|
| 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 |
|
|
129
|
+
| Macro focus | see "Macro focus" below: a flat screen seen at a grazing angle, one line sharp, everything else melted; slow drift only |
|
|
116
130
|
| Push to detail | zoom 1→2.2–3 on a hero region (`x, y` = its world center), aperture up as you go in |
|
|
117
131
|
| Fly-over | low `tilt 55–65`, camera `y` travels down the page, `fov 35`, long screenshot with `scroll` |
|
|
118
132
|
| Orbit | `Device3D` iPhone: camera `turn` −35 → +25, `tilt` 5–12, `fov 28–32`, a dark backdrop with a glow behind |
|
|
@@ -133,6 +147,27 @@ Find the brand colours first (logo, UI, website) and build the palette from them
|
|
|
133
147
|
and type, not only in camera moves: write the rotation in the shot list, and check notes.md for what
|
|
134
148
|
the last take used.
|
|
135
149
|
|
|
150
|
+
## Macro focus (an occasional signature shot)
|
|
151
|
+
|
|
152
|
+
The extreme close-up where the camera skims the screen, one line of UI is crisp and everything in front
|
|
153
|
+
and behind melts into blur (the look of a macro lens). Use it **once or twice per film at most**, for a
|
|
154
|
+
detail worth savouring: a key number, a headline, a list. It is not the default framing.
|
|
155
|
+
|
|
156
|
+
- **Keep the screen flat** (no `tilt` on the Screen/Group) and get the angle from the **camera**:
|
|
157
|
+
`tilt 60–70`, `turn ±15–30`, `roll ±10–20`, `fov 30–36`, `zoom 2.5–3.2`, `aperture 2.5–4`
|
|
158
|
+
(6+ shrinks the sharp band to a line, only for a brief accent).
|
|
159
|
+
- **Focus on the surface:** `x, y` and `focus: [x, y, 0]` = the world point of the hero line on the flat
|
|
160
|
+
screen (measure it from the screenshot like a hero region). With a tilted screen a point `[x, y, 0]` is
|
|
161
|
+
off the surface and nothing comes out sharp.
|
|
162
|
+
- **The sharp area is a band, not a dot:** real depth of field is a slice across the surface at one
|
|
163
|
+
distance. Aim the band along the line of text you want (turn/roll set its direction). **Never** cut a
|
|
164
|
+
plane into tiles or stack copies to fake a focus point: the blurred tiles leave a visible grid.
|
|
165
|
+
- **Move slowly.** A macro shot is a slow, almost still drift: over 3–5 s, the camera's `x`/`y` travel at
|
|
166
|
+
most 60–120 world px and its angles at most 3–5°, with `inOut` or `linear` keys (no `expo`, `back`
|
|
167
|
+
or `whip`), `float 0.2–0.4`, no motion blur. Optionally a slow rack: `focus` slides 80–200 px along the
|
|
168
|
+
line over the whole shot. Fast moves at this magnification look like a glitch, not a lens.
|
|
169
|
+
- Cut into and out of it on a calm beat; the shots around it should be wider so the close-up lands.
|
|
170
|
+
|
|
136
171
|
## Taste rules
|
|
137
172
|
|
|
138
173
|
- **The hero is always sharp.** Put `focus` on it; blur is for what's around it. Never blur text the
|