agentcut 0.2.5 → 0.2.6

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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agentcut",
3
- "version": "0.2.5",
3
+ "version": "0.2.6",
4
4
  "description": "Local helper for Agentcut: runs your coding agent (Claude Code or Codex), your video workspace and live preview bundles for the Agentcut studio page.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -592,13 +592,14 @@ export function Plane({
592
592
 
593
593
  // ─── Devices and screens ─────────────────────────────────────────────────────────────────────────
594
594
 
595
- export type DeviceKind = "none" | "browser" | "macbook" | "iphone" | "ipad" | "monitor";
595
+ // No flat MacBook: laptops are 3D (Device3D "macbook" / "macbook-pro"). A scene that still passes
596
+ // kind="macbook" gets a frameless screen.
597
+ export type DeviceKind = "none" | "browser" | "iphone" | "ipad" | "monitor";
596
598
 
597
599
  /** Screen aspect (width / height) each device shows by default. */
598
600
  export const DEVICE_ASPECT: Record<DeviceKind, number> = {
599
601
  none: 16 / 10,
600
602
  browser: 16 / 10,
601
- macbook: 16 / 10,
602
603
  iphone: 9 / 19.5,
603
604
  ipad: 3 / 4,
604
605
  monitor: 16 / 9,
@@ -632,15 +633,6 @@ export function deviceGeometry(kind: DeviceKind, screenWidth: number, aspect = D
632
633
  radius: w * 0.06,
633
634
  };
634
635
  }
635
- case "macbook": {
636
- const b = w * 0.022;
637
- const base = w * 0.034;
638
- return {
639
- outer: { width: w * 1.16, height: h + b * 2.6 + base },
640
- screen: { left: w * 0.08, top: b * 1.3, width: w, height: h, radius: w * 0.004 },
641
- radius: w * 0.02,
642
- };
643
- }
644
636
  case "monitor": {
645
637
  const b = w * 0.012;
646
638
  return {
@@ -677,11 +669,11 @@ export interface DeviceProps {
677
669
  screenBackground?: string;
678
670
  }
679
671
 
680
- /** A flat device frame (iPhone, MacBook, iPad, monitor, browser window) around its screen content. */
672
+ /** A flat device frame (iPhone, iPad, monitor, browser window) around its screen content. */
681
673
  export function Device({ kind, screenWidth, aspect, finish, url, children, screenBackground = "#ffffff" }: DeviceProps) {
682
674
  const g = deviceGeometry(kind, screenWidth, aspect);
683
675
  const w = screenWidth;
684
- const dark = finish === "dark" || finish === "black" || (finish === undefined && (kind === "iphone" || kind === "macbook"));
676
+ const dark = finish === "dark" || finish === "black" || (finish === undefined && kind === "iphone");
685
677
  const metal = finish === "silver" ? "#d9dce1" : "#1d1e22";
686
678
  const screen = (
687
679
  <div
@@ -733,43 +725,6 @@ export function Device({ kind, screenWidth, aspect, finish, url, children, scree
733
725
  </div>
734
726
  );
735
727
  }
736
- if (kind === "macbook") {
737
- const lidH = g.screen.height + g.screen.top * 2;
738
- const lidW = w * 1.04;
739
- const baseH = g.outer.height - lidH;
740
- const lidColor = finish === "silver" ? "#c9ccd1" : "#0d0d0f";
741
- return (
742
- <div style={{ position: "relative", width: g.outer.width, height: g.outer.height }}>
743
- <div
744
- style={{
745
- position: "absolute",
746
- left: (g.outer.width - lidW) / 2,
747
- top: 0,
748
- width: lidW,
749
- height: lidH,
750
- borderRadius: `${w * 0.022}px ${w * 0.022}px ${w * 0.006}px ${w * 0.006}px`,
751
- background: lidColor,
752
- border: `${w * 0.0016}px solid ${finish === "silver" ? "#aeb2b8" : "#3a3b40"}`,
753
- }}
754
- />
755
- <div style={{ position: "absolute", left: g.outer.width / 2 - w * 0.06, top: g.screen.top * 0.1, width: w * 0.12, height: g.screen.top * 0.9, borderRadius: `0 0 ${w * 0.01}px ${w * 0.01}px`, background: lidColor }} />
756
- {screen}
757
- <div
758
- style={{
759
- position: "absolute",
760
- left: 0,
761
- top: lidH,
762
- width: g.outer.width,
763
- height: baseH,
764
- borderRadius: `${w * 0.004}px ${w * 0.004}px ${w * 0.05}px ${w * 0.05}px / ${w * 0.004}px ${w * 0.004}px ${baseH * 0.9}px ${baseH * 0.9}px`,
765
- background: finish === "silver" || finish === undefined ? "linear-gradient(180deg, #e9ebee 0%, #b9bdc3 55%, #8e9298 100%)" : "linear-gradient(180deg, #4a4b50 0%, #2a2b2f 60%, #151517 100%)",
766
- }}
767
- >
768
- <div style={{ position: "absolute", left: "50%", top: 0, width: w * 0.16, height: baseH * 0.32, marginLeft: -w * 0.08, borderRadius: `0 0 ${w * 0.012}px ${w * 0.012}px`, background: alpha("#000000", 0.18) }} />
769
- </div>
770
- </div>
771
- );
772
- }
773
728
  const frameColor = kind === "iphone" || kind === "ipad" ? metal : dark ? "#111214" : "#e4e6ea";
774
729
  return (
775
730
  <div
@@ -858,14 +813,13 @@ export function Screen({
858
813
  {...placement}
859
814
  width={g.outer.width}
860
815
  height={g.outer.height}
861
- radius={kind === "macbook" ? 0 : g.radius}
816
+ radius={g.radius}
862
817
  shadow={shadow}
863
818
  shadowDepth={shadowDepth}
864
819
  reflection={reflection}
865
820
  rim={rim}
866
821
  dof={dof}
867
822
  opacity={opacity}
868
- style={{ overflow: kind === "macbook" ? "visible" : "hidden" }}
869
823
  >
870
824
  <Device kind={kind} screenWidth={width} aspect={aspect} finish={finish} url={url} screenBackground={screenBackground}>
871
825
  {src ? (
@@ -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": "#565457",
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
 
@@ -222,12 +248,14 @@ function createMaterials(finishColor: THREE.ColorRepresentation) {
222
248
  const { l: lightness } = finish.getHSL({ h: 0, s: 0, l: 0 });
223
249
  const isDark = lightness < 0.35;
224
250
  return {
251
+ // Bead-blasted anodised aluminium: soft, wide highlights, the finish's own colour in the shadows.
225
252
  aluminum: new THREE.MeshPhysicalMaterial({
226
253
  color: finish,
227
- metalness: 0.92,
228
- roughness: 0.4,
229
- clearcoat: 0.12,
230
- clearcoatRoughness: 0.5,
254
+ metalness: 0.85,
255
+ roughness: 0.34,
256
+ clearcoat: 0.18,
257
+ clearcoatRoughness: 0.4,
258
+ envMapIntensity: 0.75,
231
259
  }),
232
260
  edge: new THREE.MeshPhysicalMaterial({
233
261
  color: finish.clone().lerp(new THREE.Color(0xffffff), isDark ? 0.08 : 0.2),
@@ -235,25 +263,27 @@ function createMaterials(finishColor: THREE.ColorRepresentation) {
235
263
  roughness: 0.22,
236
264
  }),
237
265
  trackpad: new THREE.MeshPhysicalMaterial({
238
- color: finish.clone().lerp(new THREE.Color(0x000000), 0.04),
239
- metalness: 0.55,
240
- roughness: 0.3,
266
+ color: finish.clone().lerp(new THREE.Color(0x000000), 0.06),
267
+ metalness: 0.5,
268
+ roughness: 0.28,
241
269
  clearcoat: 0.6,
242
270
  clearcoatRoughness: 0.18,
271
+ envMapIntensity: 0.6,
243
272
  }),
244
273
  well: new THREE.MeshStandardMaterial({
245
274
  color: 0x050506,
246
275
  roughness: 0.85,
247
276
  metalness: 0,
248
- userData: { envMapIntensity: 0.1 },
277
+ envMapIntensity: 0.06,
249
278
  }),
250
279
  key: new THREE.MeshPhysicalMaterial({
251
- color: 0x0c0c0e,
252
- roughness: 0.62,
280
+ color: 0x0a0a0c,
281
+ roughness: 0.7,
253
282
  metalness: 0.05,
254
- clearcoat: 0.08,
255
- userData: { envMapIntensity: 0.3 },
283
+ clearcoat: 0.05,
284
+ envMapIntensity: 0.16,
256
285
  }),
286
+ grille: new THREE.MeshBasicMaterial({ transparent: true, depthWrite: false }),
257
287
  legends: new THREE.MeshBasicMaterial({
258
288
  transparent: true,
259
289
  depthWrite: false,
@@ -272,7 +302,7 @@ function createMaterials(finishColor: THREE.ColorRepresentation) {
272
302
  metalness: 0.8,
273
303
  roughness: 0.35,
274
304
  }),
275
- rubber: new THREE.MeshStandardMaterial({ color: 0x18181a, roughness: 0.9 }),
305
+ rubber: new THREE.MeshStandardMaterial({ color: 0x18181a, roughness: 0.9, envMapIntensity: 0.2 }),
276
306
  logo: new THREE.MeshPhysicalMaterial({
277
307
  color: finish
278
308
  .clone()
@@ -404,6 +434,27 @@ export function createMacbookModel(options: MacbookModelOptions = {}) {
404
434
  legends.renderOrder = 2;
405
435
  }
406
436
 
437
+ // ── Speaker grilles either side of the keyboard ─────────────────────
438
+ const sideRoom = (BASE.w - keyboardBounds.w) / 2;
439
+ const grilleW = Math.min(12, sideRoom - 6);
440
+ const grilleTexture = grilleW > 3 ? createGrilleTexture(grilleW, keyboardBounds.d) : null;
441
+ if (grilleTexture) {
442
+ materials.grille.map = grilleTexture;
443
+ for (const side of [-1, 1]) {
444
+ const grille = add(
445
+ "laptop-speaker-grille",
446
+ new THREE.Mesh(new THREE.PlaneGeometry(mm(grilleW), mm(keyboardBounds.d)).rotateX(-Math.PI / 2), materials.grille),
447
+ );
448
+ grille.castShadow = false;
449
+ grille.position.set(
450
+ side * mm(keyboardBounds.w / 2 + sideRoom / 2),
451
+ mm(0.3),
452
+ mm(keyboardBounds.z + keyboardBounds.d / 2),
453
+ );
454
+ grille.renderOrder = 2;
455
+ }
456
+ }
457
+
407
458
  // ── Trackpad and front lip ──────────────────────────────────────────
408
459
  const trackpadCenterZ =
409
460
  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
 
@@ -45,7 +45,7 @@ narrower moves).
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`.