abstract-3d 4.0.0-beta.2 → 4.0.0-beta.7

package/src/renderers/three/geometry/geometry.test.ts

@@ -17,6 +17,8 @@ const bounds = (mesh: Mesh): ReadonlyArray<number> => {
   return [...geometry.boundingBox!.min.toArray(), ...geometry.boundingBox!.max.toArray()].map((v) => Math.round(v * 1000) / 1000 + 0);
 };
 
+const bevel = (mesh: Mesh): ReadonlyArray<number> => [...new Set(createSolidGeometry(mesh.geometry).getAttribute("bevel").array)];
+
 describe("getSolidShape", () => {
   it("shares unit geometries between primitives of any size, scaled by the local matrix", () => {
     expect(key(box(vec3(1, 2, 3), m))).toBe(key(box(vec3(4, 5, 6), m)));
@@ -74,9 +76,21 @@ describe("createSolidGeometry", () => {
     meshes.forEach((mesh) => {
       const geometry = createSolidGeometry(mesh.geometry);
       expect(geometry.index!.count).toBeGreaterThan(0);
-      expect(Object.keys(geometry.attributes).sort()).toEqual(["normal", "position", "uv"]);
+      expect(Object.keys(geometry.attributes).sort()).toEqual(["bevel", "normal", "position", "uv"]);
     });
   });
+
+  it("gives boxes with a radius it as the radius their edges are shaded rounded by, with a geometry per radius", () => {
+    expect(bevel(box(vec3(1, 1, 1), m, vec3Zero, vec3Zero, [], 4))).toEqual([4]);
+    expect(key(box(vec3(1, 1, 1), m, vec3Zero, vec3Zero, [], 4))).toBe(key(box(vec3(9, 9, 9), m, vec3Zero, vec3Zero, [], 4)));
+    expect(key(box(vec3(1, 1, 1), m, vec3Zero, vec3Zero, [], 4))).not.toBe(key(box(vec3(1, 1, 1), m)));
+  });
+
+  it("keeps boxes without a radius, with holes, and other shapes sharp", () => {
+    expect(bevel(box(vec3(1, 1, 1), m))).toEqual([0]);
+    expect(bevel(box(vec3(1, 1, 1), m, vec3Zero, vec3Zero, [roundHole(vec2(0, 0), 0.1)], 4))).toEqual([0]);
+    expect(bevel(sphere(1, m))).toEqual([0]);
+  });
 });
 
 describe("keepGeometries", () => {

package/src/renderers/three/geometry/geometry.ts

@@ -42,7 +42,7 @@ export function getSolidShape(g: Mesh["geometry"]): SolidShape | undefined {
       const size = g.type === "Box" ? g.size : vec3(g.size.x, g.size.y, 1);
       return g.holes?.some((h) => !holeIsZero(h))
         ? { key: JSON.stringify([g.type, g.size, g.holes]), local: transform(g.pos, g.rot) }
-        : { key: g.type, local: transform(g.pos, g.rot, undefined, size) };
+        : { key: g.type === "Box" && g.radius ? `Box ${g.radius}` : g.type, local: transform(g.pos, g.rot, undefined, size) };
     }
     case "Image":
       return { key: "Plane", local: transform(g.pos, g.rot, undefined, vec3(g.size.x, g.size.y, 1)) };
@@ -86,8 +86,11 @@ export function createSolidGeometry(g: Mesh["geometry"]): BufferGeometry {
   if (!geometry.hasAttribute("uv")) {
     geometry.setAttribute("uv", new Float32BufferAttribute(new Float32Array(count * 2), 2));
   }
+  // The radius a unit box's edges are shaded as rounded by, 0 for sharp; every geometry has it, as a batch's geometries share their attributes
+  const radius = geometry instanceof BoxGeometry && g.type === "Box" ? (g.radius ?? 0) : 0;
+  geometry.setAttribute("bevel", new Float32BufferAttribute(new Float32Array(count).fill(radius), 1));
   Object.keys(geometry.attributes).forEach((name) => {
-    if (name !== "position" && name !== "normal" && name !== "uv") {
+    if (name !== "position" && name !== "normal" && name !== "uv" && name !== "bevel") {
       geometry.deleteAttribute(name);
     }
   });

package/src/renderers/three/quality/quality.test.ts

@@ -30,8 +30,8 @@ describe("recordFrame", () => {
 });
 
 describe("getPixelRatio", () => {
-  it("caps the screen's pixel ratio by the tier", () => {
-    expect([getPixelRatio("low", 3), getPixelRatio("medium", 3), getPixelRatio("high", 3)]).toEqual([1, 1.5, 2]);
+  it("caps the screen's pixel ratio by the tier, and high is the screen's own, as the r3f renderer's", () => {
+    expect([getPixelRatio("low", 3), getPixelRatio("medium", 3), getPixelRatio("high", 3)]).toEqual([1, 1.5, 3]);
     expect(getPixelRatio("high", 1)).toBe(1);
   });
 });

package/src/renderers/three/quality/quality.ts

@@ -1,6 +1,7 @@
 /**
- * Quality tiers by resolution, the cheapest lever on a weak GPU: low renders a pixel per CSS pixel, medium up to 1.5 and high up to 2 on high-density
- * screens. `auto` starts high and drops to low for good once moving frames are slow, as model viewers lower their resolution under load
+ * Quality tiers by resolution, the cheapest lever on a weak GPU: low renders a pixel per CSS pixel, medium up to 1.5, and high, the default, the
+ * screen's own pixel ratio as the r3f renderer. `auto` starts high and drops to low for good once moving frames are slow, as model viewers lower
+ * their resolution under load
  */
 
 export type Tier = "low" | "medium" | "high";
@@ -9,7 +10,7 @@ export type Quality = Tier | "auto";
 /** `auto` starts at high, and drops to low for good once moving frames average slower than 40 per second */
 export type TierGovernor = { readonly quality: Quality; tier: Tier; sum: number; count: number };
 
-const pixelRatioCaps: Record<Tier, number> = { low: 1, medium: 1.5, high: 2 };
+const pixelRatioCaps: Record<Tier, number> = { low: 1, medium: 1.5, high: Infinity };
 const windowSize = 30;
 const slowFrameMs = 25;
 /** Longer intervals are pauses between moves, not slow frames */

package/src/renderers/three/shadow/key-light.ts

@@ -0,0 +1,41 @@
+import { DirectionalLight, Group, Sphere, Vector3 } from "three";
+import type { BuiltScene } from "../build/build.js";
+import { getShadowCasters } from "./shadow.js";
+
+/**
+ * A key light from the upper left front, on top of the studio's soft light, that casts the solids' shadows on themselves, e.g. under a roof or behind
+ * a profile. Its shadow map is rendered once per build, as the scene doesn't move, so a frame only samples it; the casters are the ground shadow's
+ */
+
+const direction = new Vector3(-1, 2, 1.2).normalize();
+const intensity = 3.5;
+const mapSize = 2048;
+
+/** The light and its target, to add to the scene, with or without shadows; undefined for a scene without solids */
+export function createKeyLight(built: BuiltScene, shadows: boolean): Group | undefined {
+  const { bounds } = getShadowCasters(built);
+  if (bounds.isEmpty()) {
+    return undefined;
+  }
+  const { center, radius } = bounds.getBoundingSphere(new Sphere());
+  const light = new DirectionalLight(0xffffff, intensity);
+  light.position.copy(center).addScaledVector(direction, radius * 2);
+  light.target.position.copy(center);
+  light.castShadow = shadows;
+  // The shadow camera just encloses the scene, so the map's texels are as small as they can be
+  Object.assign(light.shadow.camera, { left: -radius, right: radius, top: radius, bottom: -radius, near: radius, far: radius * 3 });
+  light.shadow.camera.updateProjectionMatrix();
+  light.shadow.mapSize.set(mapSize, mapSize);
+  // Offsets along the normal by three texels, against shadow acne on the lit faces
+  Object.assign(light.shadow, { bias: -0.0005, normalBias: (radius * 6) / mapSize, radius: 3 });
+  return new Group().add(light, light.target);
+}
+
+export function disposeKeyLight(key: Group): void {
+  key.removeFromParent();
+  key.children.forEach((child) => {
+    if (child instanceof DirectionalLight) {
+      child.shadow.dispose();
+    }
+  });
+}

package/src/renderers/three/shadow/shadow.ts

@@ -1,7 +1,9 @@
 import {
+  type BatchedMesh,
   Box3,
+  CanvasTexture,
+  HalfFloatType,
   type Scene,
-  Matrix4,
   Mesh,
   MeshBasicMaterial,
   MeshDepthMaterial,
@@ -24,53 +26,67 @@ import type { BuiltScene } from "../build/build.js";
  * ContactShadows with `frames={1}`
  */
 
-export type GroundShadow = { readonly mesh: Mesh<PlaneGeometry, MeshBasicMaterial>; readonly target: WebGLRenderTarget };
+export type GroundShadow = {
+  readonly mesh: Mesh<PlaneGeometry, MeshBasicMaterial>;
+  readonly floor: Mesh<PlaneGeometry, MeshBasicMaterial>;
+  readonly target: WebGLRenderTarget;
+};
 
 /** The layer the solids are drawn on for the shadow, so text, lines, images and dimensions don't cast one */
 const shadowLayer = 1;
 /** Of the texture's longer side */
 const resolution = 512;
-/** How far behind (-z) a part's shadow falls per unit of its height, as from a light in front and above */
-const lean = 0.5;
 /** The blur's reach, of the solids' height */
-const softness = 0.15;
-const opacity = 0.8;
+const softness = 0.22;
+const opacity = 1;
+/** A pool of light on the floor the shadow lies in, so it shows on a dark background, which a shadow alone can't darken; on white it's invisible */
+const floorLight = 0.06;
+/** The pool's reach beyond the solids, of their height */
+const floorReach = 1;
 
-/** Undefined for a scene without solids; renders with `renderer`, and leaves its render target as it was */
-export function createGroundShadow(renderer: WebGLRenderer, scene: Scene, built: BuiltScene): GroundShadow | undefined {
+/** The batches of solids that cast shadows, with their bounds: opaque ones whose material doesn't turn it off, not text, lines, images or dimensions */
+export function getShadowCasters(built: BuiltScene): { readonly casters: ReadonlyArray<BatchedMesh>; readonly bounds: Box3 } {
+  const casters: Array<BatchedMesh> = [];
   const bounds = new Box3();
   built.parts.forEach((part) => {
-    if (part.kind === "solid" && part.object.parent !== built.dimensions && part.object.boundingBox) {
-      part.object.layers.enable(shadowLayer);
+    if (part.kind === "solid" && part.object.castShadow && part.object.parent !== built.dimensions && part.object.boundingBox) {
+      casters.push(part.object);
       bounds.union(part.object.boundingBox);
     }
   });
+  return { casters, bounds };
+}
+
+/** Undefined for a scene without solids; renders with `renderer`, and leaves its render target as it was */
+export function createGroundShadow(renderer: WebGLRenderer, scene: Scene, built: BuiltScene): GroundShadow | undefined {
+  const { casters, bounds } = getShadowCasters(built);
   if (bounds.isEmpty()) {
     return undefined;
   }
+  casters.forEach((caster) => caster.layers.enable(shadowLayer));
   const size = bounds.getSize(new Vector3());
-  // The plane reaches past the solids by twice the blur's reach, and behind them as far as their tops' shadows fall
-  const [reach, behind] = [softness * size.y, lean * size.y];
-  const [width, depth] = [size.x + reach * 4, size.z + reach * 4 + behind];
-  const center = new Vector3((bounds.min.x + bounds.max.x) / 2, bounds.min.y, (bounds.min.z + bounds.max.z - behind) / 2);
+  // The plane reaches past the solids by twice the blur's reach on every side
+  const reach = softness * size.y;
+  const [width, depth] = [size.x + reach * 4, size.z + reach * 4];
+  const center = new Vector3((bounds.min.x + bounds.max.x) / 2, bounds.min.y, (bounds.min.z + bounds.max.z) / 2);
   const [texelsX, texelsZ] =
     width > depth ? [resolution, Math.ceil((resolution * depth) / width)] : [Math.ceil((resolution * width) / depth), resolution];
-  const [target, blurred] = [new WebGLRenderTarget(texelsX, texelsZ), new WebGLRenderTarget(texelsX, texelsZ)];
+  // Half float, so the blur's soft falloff isn't rounded into steps
+  const halfFloat = { type: HalfFloatType };
+  const [target, blurred] = [new WebGLRenderTarget(texelsX, texelsZ, halfFloat), new WebGLRenderTarget(texelsX, texelsZ, halfFloat)];
 
-  // Looks up from the ground, seeing as far as the solids are high; the shear moves what's at height h back by lean·h. Up is +z on its screen, and
-  // a height h is -h in its view space
+  // Looks up from the ground, seeing as far as the solids are high
   const camera = new OrthographicCamera(-width / 2, width / 2, depth / 2, -depth / 2, 0, size.y);
   camera.position.copy(center);
   camera.rotation.x = Math.PI / 2;
   camera.layers.set(shadowLayer);
   camera.updateMatrixWorld();
-  camera.projectionMatrix.multiply(new Matrix4().set(1, 0, 0, 0, 0, 1, lean, 0, 0, 0, 1, 0, 0, 0, 0, 1));
   // Depth tested, so at each point the surface closest to the ground darkens it, not the last one drawn
   const darkness = new MeshDepthMaterial();
   darkness.onBeforeCompile = (shader) => {
     shader.fragmentShader = shader.fragmentShader.replace(
       "gl_FragColor = vec4( vec3( 1.0 - fragCoordZ ), opacity );",
-      "gl_FragColor = vec4( vec3( 0.0 ), 1.0 - fragCoordZ );"
+      "gl_FragColor = vec4( vec3( 0.0 ), sqrt( 1.0 - fragCoordZ ) );"
     );
   };
   const previous = renderer.getRenderTarget();
@@ -100,17 +116,55 @@ export function createGroundShadow(renderer: WebGLRenderer, scene: Scene, built:
   // The plane faces down as the camera looked up, so its texture lines up, and is mirrored to face up
   const mesh = new Mesh(
     new PlaneGeometry(width, depth).rotateX(Math.PI / 2),
-    new MeshBasicMaterial({ map: target.texture, transparent: true, depthWrite: false, opacity })
+    ditherAlpha(new MeshBasicMaterial({ map: target.texture, transparent: true, depthWrite: false, opacity }), 2)
   );
   mesh.position.copy(center);
   mesh.scale.y = -1;
-  scene.add(mesh);
-  return { mesh, target };
+  // The floor's pool of light first, then the shadow in it, both before other transparent objects
+  const floor = new Mesh(
+    new PlaneGeometry(size.x + size.y * floorReach * 2, size.z + size.y * floorReach * 2).rotateX(-Math.PI / 2),
+    ditherAlpha(new MeshBasicMaterial({ alphaMap: createPool(), transparent: true, depthWrite: false, opacity: floorLight }), 1)
+  );
+  floor.position.copy(center);
+  Object.assign(floor, { renderOrder: -2 });
+  Object.assign(mesh, { renderOrder: -1 });
+  scene.add(floor, mesh);
+  return { mesh, floor, target };
+}
+
+/** A radial falloff from the center to the edges, as a spotlight's pool on the floor */
+function createPool(): CanvasTexture {
+  const canvas = Object.assign(document.createElement("canvas"), { width: 128, height: 128 });
+  const ctx = canvas.getContext("2d")!;
+  const gradient = ctx.createRadialGradient(64, 64, 0, 64, 64, 64);
+  gradient.addColorStop(0, "#fff");
+  gradient.addColorStop(0.3, "#999");
+  gradient.addColorStop(0.7, "#222");
+  gradient.addColorStop(1, "#000");
+  Object.assign(ctx, { fillStyle: gradient }).fillRect(0, 0, 128, 128);
+  return new CanvasTexture(canvas);
 }
 
 export function disposeGroundShadow(shadow: GroundShadow): void {
-  shadow.mesh.removeFromParent();
-  shadow.mesh.geometry.dispose();
-  shadow.mesh.material.dispose();
+  [shadow.mesh, shadow.floor].forEach((mesh) => {
+    mesh.removeFromParent();
+    mesh.geometry.dispose();
+    mesh.material.alphaMap?.dispose();
+    mesh.material.dispose();
+  });
   shadow.target.dispose();
 }
+
+/**
+ * Jitters the alpha by about `levels` of the screen's 256 per pixel, so a faint gradient blended over the background doesn't show the 8-bit steps of
+ * the blend; three's `dithering` jitters the color, which these blends' steps don't come from
+ */
+function ditherAlpha(material: MeshBasicMaterial, levels: number): MeshBasicMaterial {
+  material.onBeforeCompile = (shader) => {
+    shader.fragmentShader = shader.fragmentShader.replace(
+      "#include <dithering_fragment>",
+      `gl_FragColor.a = clamp( gl_FragColor.a + ( rand( gl_FragCoord.xy ) - 0.5 ) * ${(levels / 255).toFixed(5)}, 0.0, 1.0 );`
+    );
+  };
+  return material;
+}

package/src/renderers/three/viewer/options.ts

@@ -1,4 +1,4 @@
-import type { Object3D, Texture } from "three";
+import type { Object3D } from "three";
 import type { Group, Relation, Scene, Vec3, View } from "../../../abstract-3d.js";
 import type { MaterialState } from "../appearance/appearance.js";
 import type { BufferZones, CameraOptions } from "../camera/camera.js";
@@ -34,21 +34,22 @@ export type ViewerOptions<Content> = {
    */
   readonly activeRelations?: ReadonlyArray<string>;
   readonly showDimensions?: boolean;
-  /** View, buffer zones and padding are read when the scene is fitted: first, and for a new camera or canvas size */
+  /** View, buffer zones and padding are read when the scene is fitted: first, and for a new camera or canvas aspect */
   readonly camera?: CameraOptions;
   readonly view?: View;
   readonly bufferZones?: BufferZones;
   readonly fitPadding?: number;
   readonly controls?: ControlsOptions;
   readonly gizmo?: ControlsHelper;
-  /** Replace the default lights, a weak ambient light, a key light from the upper left and two fills */
+  /** Lights added to the photographed studio and key light that light the scene; none by default */
   readonly lights?: ReadonlyArray<Object3D> | ((scene: Scene) => ReadonlyArray<Object3D>);
-  /** Lights faces by which way they turn and gives metal reflections: `studio` by default, `room` for three's RoomEnvironment, or null for none */
-  readonly environment?: Texture | "studio" | "room" | null;
+  /** Of the studio's light, 0.5 by default, the key light giving the rest */
   readonly environmentIntensity?: number;
   /** A soft shadow on the ground under the scene, rendered once per build; on by default */
   readonly groundShadow?: boolean;
-  /** The resolution: `low` 1, `medium` up to 1.5 and `high` up to 2 pixels per CSS pixel; `auto` by default, high until moving gets slow */
+  /** The solids' shadows on themselves, e.g. under a roof, cast by the key light from the upper left front; on by default */
+  readonly shadows?: boolean;
+  /** The resolution: `low` 1 and `medium` up to 1.5 pixels per CSS pixel, `high`, the default, the screen's; `auto` high until moving gets slow */
   readonly quality?: Quality;
   readonly useAlphaTest?: boolean;
   readonly materialStateImages?: Record<string, string>;
@@ -88,9 +89,9 @@ export const effects: { readonly [K in keyof ViewerOptions<unknown>]-?: Readonly
   controls: ["controls"],
   gizmo: ["gizmo"],
   lights: ["lights"],
-  environment: ["lights"],
   environmentIntensity: ["lights"],
   groundShadow: ["shadow"],
+  shadows: ["shadow"],
   quality: ["quality"],
   popovers: ["overlays"],
   getTooltips: ["overlays"],

package/src/renderers/three/viewer/viewer.ts

@@ -1,25 +1,17 @@
 import {
-  AmbientLight,
   type BufferGeometry,
-  CanvasTexture,
-  DirectionalLight,
-  EquirectangularReflectionMapping,
   Group,
   NeutralToneMapping,
-  type Object3D,
   OrthographicCamera,
   PerspectiveCamera,
-  PMREMGenerator,
   Raycaster,
   Scene as ThreeScene,
-  SRGBColorSpace,
   type Texture,
   Vector2,
   Vector3,
   WebGLRenderer,
 } from "three";
 import type { ViewportGizmo } from "three-viewport-gizmo";
-import { RoomEnvironment } from "three/addons/environments/RoomEnvironment.js";
 import type { StructureState } from "../appearance/appearance.js";
 import type { BuiltScene } from "../build/build.js";
 import { animateScene, buildScene, cullScene, disposeScene, getPickables, getPickedItem, paintScene } from "../build/build.js";
@@ -34,6 +26,7 @@ import type { CompiledScene } from "../compile/compile.js";
 import { compileScene } from "../compile/compile.js";
 import type { TierGovernor } from "../quality/quality.js";
 import { getPixelRatio, recordFrame } from "../quality/quality.js";
+import { createKeyLight, disposeKeyLight } from "../shadow/key-light.js";
 import type { GroundShadow } from "../shadow/shadow.js";
 import { createGroundShadow, disposeGroundShadow } from "../shadow/shadow.js";
 import type { GlyphAtlas } from "../text/text.js";
@@ -80,8 +73,11 @@ export type Viewer<Content> = {
   built?: BuiltScene;
   gizmo?: ViewportGizmo;
   shadow?: GroundShadow;
+  /** The key light that casts the solids' shadows on themselves */
+  keyLight?: Group;
   governor?: TierGovernor;
-  readonly environments: Partial<Record<"studio" | "room", Texture>>;
+  /** The studio environment, loading and once loaded */
+  readonly studio: { loading?: Promise<unknown>; texture?: Texture };
   /** The scene is built and its shaders compiled */
   loaded: boolean;
   fitted: boolean;
@@ -103,6 +99,8 @@ export function createViewer<Content>(container: HTMLElement, options: ViewerOpt
   const renderer = new WebGLRenderer({ canvas, antialias: true, alpha: true });
   Object.assign(renderer, { toneMapping: NeutralToneMapping });
   renderer.setClearColor(0x000000, 0);
+  // Rendered when the scene is built, not each frame
+  Object.assign(renderer.shadowMap, { enabled: true, autoUpdate: false });
   renderer.info.autoReset = false;
   const cameras = { Perspective: new PerspectiveCamera(45), Orthographic: new OrthographicCamera() };
   const camera = cameras[options.camera?.type ?? "Perspective"];
@@ -128,7 +126,7 @@ export function createViewer<Content>(container: HTMLElement, options: ViewerOpt
     pending: new Set(["compile", "build", "camera", "controls", "gizmo", "lights", "quality", "paint", "overlays"]),
     stats: { frames: 0, frameMs: 0, drawCalls: 0, pickMs: 0, paintMs: 0 },
     structure: { activeComponents: options.activeComponents, relationsActive: options.activeRelations !== undefined },
-    environments: {},
+    studio: {},
     loaded: false,
     fitted: false,
     disposed: false,
@@ -172,7 +170,10 @@ export function disposeViewer<Content>(v: Viewer<Content>): void {
   if (v.shadow) {
     disposeGroundShadow(v.shadow);
   }
-  Object.values(v.environments).forEach((e) => e.dispose());
+  if (v.keyLight) {
+    disposeKeyLight(v.keyLight);
+  }
+  v.studio.texture?.dispose();
   v.geometries.forEach((g) => g.dispose());
   v.atlas.texture.dispose();
   disposeTextures(v.textures);
@@ -198,17 +199,26 @@ function apply<Content>(v: Viewer<Content>, changes: ReadonlySet<Change>): void
       disposeGroundShadow(v.shadow);
     }
     v.shadow = v.built && options.groundShadow !== false ? createGroundShadow(v.renderer, v.scene, v.built) : undefined;
+    if (v.keyLight) {
+      disposeKeyLight(v.keyLight);
+    }
+    v.keyLight = v.built ? createKeyLight(v.built, options.shadows !== false) : undefined;
+    if (v.keyLight) {
+      v.scene.add(v.keyLight);
+    }
+    // The shadow map is rendered once, as the scene doesn't move, or each frame while something animates
+    Object.assign(v.renderer.shadowMap, { needsUpdate: true, autoUpdate: !!v.built && v.built.animatedItems.length > 0 });
   }
   if (changes.has("camera")) {
     const { near = 0.1, far = 2000, ...rest } = options.camera ?? { type: "Perspective" };
     v.camera = v.cameras[rest.type];
-    Object.assign(v.camera, { near, far, ...("fov" in rest && rest.fov !== undefined ? { fov: rest.fov } : {}) });
+    Object.assign(v.camera, { near, far, ...(rest.type === "Perspective" ? { fov: rest.fov ?? 45 } : {}) });
     v.controls.orbit.object = v.camera;
   }
   if (changes.has("controls")) {
     configureControls(v.controls, options.controls ?? {});
   }
-  // As the r3f renderer, the scene is fitted at first, and for a new camera or canvas size
+  // As the r3f renderer, the scene is fitted at first, and for a new camera or canvas aspect
   if ((changes.has("build") && !v.fitted) || changes.has("camera")) {
     fitPose(v);
   }
@@ -219,7 +229,7 @@ function apply<Content>(v: Viewer<Content>, changes: ReadonlySet<Change>): void
     updateLights(v);
   }
   if (changes.has("quality")) {
-    const quality = options.quality ?? "auto";
+    const quality = options.quality ?? "high";
     v.governor = { quality, tier: quality === "auto" ? "high" : quality, sum: 0, count: 0 };
     v.renderer.setPixelRatio(getPixelRatio(v.governor.tier, window.devicePixelRatio));
   }
@@ -260,9 +270,10 @@ function rebuild<Content>(v: Viewer<Content>): void {
   if (v.built) {
     v.scene.add(v.built.root);
     v.built.dimensions.visible = options.showDimensions ?? true;
-    // Compiled in parallel where the driver can, as three.js's compileAsync example
-    v.renderer
-      .compileAsync(v.scene, v.camera)
+    // Compiled in parallel where the driver can, as three.js's compileAsync example, and after the studio arrived, which they use
+    loadStudio(v)
+      .catch(() => undefined)
+      .then(() => v.renderer.compileAsync(v.scene, v.camera))
       .then(() => onLoaded(v))
       .catch(() => undefined);
   }
@@ -315,21 +326,32 @@ function renderFrame<Content>(v: Viewer<Content>, now: number): void {
   }
 }
 
+/** As the r3f renderer, a resize refits only when the canvas' aspect changes */
 function onResize<Content>(v: Viewer<Content>, rect: DOMRectReadOnly): void {
+  const aspectChanged = rect.width / rect.height !== v.size.width / v.size.height;
   Object.assign(v.size, { width: rect.width, height: rect.height });
   v.renderer.setSize(rect.width, rect.height, false);
   v.overlays.renderer.setSize(rect.width, rect.height);
   v.gizmo?.update();
-  fitPose(v);
-  invalidate(v);
+  if (aspectChanged) {
+    fitPose(v);
+  }
+  // Resizing cleared the canvas; rendered now, before the browser paints, instead of the next frame, so it never shows blank
+  if (v.loop.frame) {
+    cancelAnimationFrame(v.loop.frame);
+    v.loop.frame = 0;
+  }
+  if (rect.width > 0 && rect.height > 0 && !v.disposed) {
+    renderFrame(v, performance.now());
+  }
 }
 
-/** Fits the projection to the scene, and moves the camera to look at it from the view */
+/** Fits the projection to the scene, and moves the camera to look from the view; as the r3f renderer, the target stays where it was panned to */
 function fitPose<Content>(v: Viewer<Content>): void {
   const placement = fitScene(v);
   if (placement) {
     const { x, y, z } = placement.direction;
-    setPose(v.controls, new Vector3(x, y, z).multiplyScalar(placement.distance), new Vector3());
+    setPose(v.controls, new Vector3(x, y, z).multiplyScalar(placement.distance), v.controls.orbit.target);
     v.fitted = true;
   }
 }
@@ -345,6 +367,19 @@ function updateGizmo<Content>(v: Viewer<Content>): void {
   v.gizmo = gizmo && createGizmo(v.camera, v.renderer, v.container, gizmo).attachControls(v.controls.orbit);
   v.gizmo?.addEventListener("change", () => invalidate(v));
   v.gizmo?.addEventListener("start", () => onGizmoStart(v));
+  // Its labels are drawn once, so ones drawn before the page's web fonts loaded are redrawn when they have
+  const created = v.gizmo;
+  if (created && document.fonts.status !== "loaded") {
+    document.fonts.ready.then(() => redrawGizmo(v, created)).catch(() => undefined);
+  }
+}
+
+/** Unless the gizmo was replaced or the viewer disposed meanwhile */
+function redrawGizmo<Content>(v: Viewer<Content>, gizmo: ViewportGizmo): void {
+  if (v.gizmo === gizmo && !v.disposed) {
+    gizmo.set(gizmo.options);
+    invalidate(v);
+  }
 }
 
 /**
@@ -459,63 +494,26 @@ function getGroupArgs<Content>(
   }
 }
 
+/** The scene is lit by a photographed studio as its environment; apps can add their own lights */
 function updateLights<Content>(v: Viewer<Content>): void {
-  const { scene, lights, environment = "studio", environmentIntensity = 1 } = v.options;
+  const { scene, lights, environmentIntensity = studioIntensity } = v.options;
   v.lights.clear();
-  const objects = typeof lights === "function" ? (scene ? lights(scene) : []) : (lights ?? createLights());
-  objects.forEach((o) => v.lights.add(o));
-  if (typeof environment === "string") {
-    v.environments[environment] ??= createEnvironment(environment, v.renderer);
-  }
-  Object.assign(v.scene, { environment: typeof environment === "string" ? v.environments[environment] : environment, environmentIntensity });
+  (typeof lights === "function" ? (scene ? lights(scene) : []) : (lights ?? [])).forEach((o) => v.lights.add(o));
+  v.scene.environmentIntensity = environmentIntensity;
+  loadStudio(v).catch(() => undefined);
 }
 
-/**
- * A weak ambient light, so the environment lights faces by which way they turn, with a key light from the upper left for shading and highlights and
- * two fills. Directional lights shine towards the origin, the scene's center, so only their positions' directions matter
- */
-function createLights(): ReadonlyArray<Object3D> {
-  const directional = [
-    [-1.9, 1, 0, 3],
-    [0, 1, 0.94, 1.2],
-    [3.9, 0, 1, 0.3],
-  ] as const;
-  return [
-    new AmbientLight(0xffffff, 0.2),
-    ...directional.map(([x, y, z, i]) => {
-      const light = new DirectionalLight(0xffffff, i);
-      light.position.set(x, y, z);
-      return light;
-    }),
-  ];
-}
-
-/**
- * Studio: an equirectangular gradient from a white ceiling to a dark floor, with three softboxes 20-50° up, so faces are brighter from above than
- * from below and metal profiles and panels get reflections. Room: three.js's RoomEnvironment through PMREM, as its examples light models
- */
-function createEnvironment(kind: "studio" | "room", renderer: WebGLRenderer): Texture {
-  if (kind === "room") {
-    const pmrem = new PMREMGenerator(renderer);
-    const texture = pmrem.fromScene(new RoomEnvironment(), 0.04).texture;
-    pmrem.dispose();
-    return texture;
-  }
-  const canvas = Object.assign(document.createElement("canvas"), { width: 1024, height: 512 });
-  const ctx = canvas.getContext("2d")!;
-  const gradient = ctx.createLinearGradient(0, 0, 0, 512);
-  gradient.addColorStop(0, "#ffffff");
-  gradient.addColorStop(0.45, "#d8d8d8");
-  gradient.addColorStop(0.55, "#8a8a8a");
-  gradient.addColorStop(1, "#5a5a5a");
-  Object.assign(ctx, { fillStyle: gradient }).fillRect(0, 0, 1024, 512);
-  ctx.fillStyle = "#ffffff";
-  [
-    [80, 120],
-    [400, 90],
-    [700, 140],
-  ].forEach(([x, width]) => ctx.fillRect(x!, 110, width!, 90));
-  return Object.assign(new CanvasTexture(canvas), { mapping: EquirectangularReflectionMapping, colorSpace: SRGBColorSpace });
+/** The studio, loaded once, its own chunk; set when it arrives, so the scene's shaders are compiled after it, with it */
+function loadStudio<Content>(v: Viewer<Content>): Promise<unknown> {
+  v.studio.loading ??= import("../environment/studio.js")
+    .then(({ loadStudio: load }) => load())
+    .then((texture) => {
+      v.studio.texture = texture;
+      v.scene.environment = texture;
+      invalidate(v);
+      return texture;
+    });
+  return v.studio.loading;
 }
 
 function updateOverlays<Content>(v: Viewer<Content>): void {
@@ -539,5 +537,8 @@ function updateOverlays<Content>(v: Viewer<Content>): void {
   setOverlays(v.overlays, overlays, options.onOverlays);
 }
 
+/** The studio's share of the light, the key light giving the rest, so the key light's shadows show */
+const studioIntensity = 0.5;
+
 const raycaster = new Raycaster();
 const ndc = new Vector2();