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.
@@ -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
- /** Hardware color: silver, starlight, space-gray, midnight, black, or a hex (MacBook, display, classic iPhone). */
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
- const finishColor = finish ? (DEVICE_FINISHES[finish] ?? finish) : undefined;
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 standing = model === "macbook" || model === "display";
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={model === "macbook" ? deviceSize * 0.12 : 0}
235
+ z={laptop ? deviceSize * 0.12 : 0}
211
236
  tilt={90}
212
- width={deviceSize * (model === "macbook" ? 1.02 : 0.5)}
213
- height={deviceSize * (model === "macbook" ? 0.72 : 0.3)}
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
- const pxPerMm = 9;
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
- context.fillStyle = "rgba(236, 238, 242, 0.92)";
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 = `500 ${Math.round(2.3 * pxPerMm)}px -apple-system, "SF Pro Text", "Helvetica Neue", Arial, sans-serif`;
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.4 : 3.6;
188
- context.font = `500 ${Math.round(fontSize * pxPerMm)}px -apple-system, "SF Pro Text", "Helvetica Neue", Arial, sans-serif`;
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 = 4;
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
- const isDark = lightness < 0.35;
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.92,
228
- roughness: 0.4,
229
- clearcoat: 0.12,
230
- clearcoatRoughness: 0.5,
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.04),
239
- metalness: 0.55,
240
- roughness: 0.3,
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
- userData: { envMapIntensity: 0.1 },
281
+ envMapIntensity: 0.06,
249
282
  }),
250
283
  key: new THREE.MeshPhysicalMaterial({
251
- color: 0x0c0c0e,
252
- roughness: 0.62,
284
+ color: 0x0a0a0c,
285
+ roughness: 0.7,
253
286
  metalness: 0.05,
254
- clearcoat: 0.08,
255
- userData: { envMapIntensity: 0.3 },
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<VideoDeviceModelId, Promise<THREE.Group>>();
357
- const templates = new Map<VideoDeviceModelId, THREE.Group>();
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
- export async function preloadVideoDeviceModel(id: VideoDeviceModelId) {
468
- if (!VIDEO_DEVICE_MODEL_CONFIGS[id]?.source || templates.has(id)) return;
469
- const existing = templatePromises.get(id);
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
- const config = VIDEO_DEVICE_MODEL_CONFIGS[id];
475
- if (!config.source) return;
476
- const source = config.source;
477
- // The studio serves models from its own origin; a local render (no /models there) fetches them from
478
- // the public site.
479
- const promise = new GLTFLoader()
480
- .loadAsync(source)
481
- .catch(() => new GLTFLoader().loadAsync(`${MODEL_FALLBACK_ORIGIN}${source}`))
482
- .then(
483
- (gltf) => {
484
- templates.set(id, gltf.scene);
485
- return gltf.scene;
486
- },
487
- (error: unknown) => {
488
- // Forget the failure so the next device (or a retry) loads again instead of failing for good.
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.source) {
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 offsetY = (1 - repeatY) * (1 - Math.min(1, Math.max(0, scroll)));
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
- // Image v runs up (flipY): the top of the screenshot is v = 1.
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 = 1.12 * p.exposure;
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`), `macbook`, `iphone`, `ipad`,
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-classic`. `src` is the screenshot
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` `silver` `starlight` `space-gray`
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
- - **Never** use the flat `Screen` `iphone` / `macbook` / `ipad` / `monitor` frames when the shot shows the
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