abstract-3d 4.0.0-beta.0 → 4.0.0-beta.4

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

@@ -1,43 +1,56 @@
 import { Matrix4, Vector3 } from "three";
-import { describe, expect, it } from "vitest";
+import { assert, describe, expect, it } from "vitest";
 import type { Group, Scene } from "../../../abstract-3d.js";
 import { alignedDimension, box, group, line, sphere, text, vec3, vec3Zero } from "../../../abstract-3d.js";
+import type { CompiledScene, Item } from "./compile.js";
 import { compileScene, getItemMatrix } from "./compile.js";
 
 const red = { normal: "rgb(255, 0, 0)" };
 const scene = (groups: ReadonlyArray<Group>, rest: Partial<Scene> = {}): Scene => ({ size_deprecated: vec3(1, 1, 1), groups, ...rest });
-const apply = (m: Matrix4, x: number, y: number, z: number): ReadonlyArray<number> =>
-  new Vector3(x, y, z)
+const apply = (m: Matrix4 | undefined, x: number, y: number, z: number): ReadonlyArray<number> => {
+  assert(m);
+  return new Vector3(x, y, z)
     .applyMatrix4(m)
     .toArray()
     .map((v) => Math.round(v * 1000) / 1000 + 0);
+};
+const getItem = (compiled: CompiledScene, index: number): Item => {
+  const item = compiled.items.at(index);
+  assert(item);
+  return item;
+};
+// Destructured, as the build's and lint's compiler options disagree on reading an index signature by dot or bracket
+const groupId = (g: Group): string => {
+  const { id = "" }: Record<string, string | undefined> = g.data ?? {};
+  return id;
+};
 
 describe("compileScene", () => {
   it("flattens nested groups into items with world matrices", () => {
     const inner = group([sphere(1, red)], vec3(0, 10, 0));
     const compiled = compileScene(scene([group([box(vec3(1, 1, 1), red)], vec3(100, 0, 0), vec3Zero, [inner])]));
     expect(compiled.items.map((i) => i.role)).toEqual(["solid", "solid"]);
-    expect(apply(compiled.items[0].matrix, 0, 0, 0)).toEqual([100, 0, 0]);
-    expect(apply(compiled.items[1].matrix, 0, 0, 0)).toEqual([100, 10, 0]);
+    expect(apply(compiled.items.at(0)?.matrix, 0, 0, 0)).toEqual([100, 0, 0]);
+    expect(apply(compiled.items.at(1)?.matrix, 0, 0, 0)).toEqual([100, 10, 0]);
   });
 
   it("applies group rotation before the group's position", () => {
     const compiled = compileScene(scene([group([box(vec3(1, 1, 1), red)], vec3(5, 0, 0), vec3(0, 0, Math.PI / 2))]));
-    expect(apply(compiled.items[0].matrix, 1, 0, 0)).toEqual([5, 1, 0]);
+    expect(apply(compiled.items.at(0)?.matrix, 1, 0, 0)).toEqual([5, 1, 0]);
   });
 
   it("rotates the scene by its deprecated rotation, then moves it by minus its deprecated center", () => {
     const g = group([box(vec3(1, 1, 1), red)], vec3(10, 0, 0));
     const centered = compileScene(scene([g], { center_deprecated: vec3(10, 0, 0) }));
-    expect(apply(centered.items[0].matrix, 0, 0, 0)).toEqual([0, 0, 0]);
+    expect(apply(centered.items.at(0)?.matrix, 0, 0, 0)).toEqual([0, 0, 0]);
     const rotated = compileScene(scene([g], { center_deprecated: vec3(-10, 0, 0), rotation_deprecated: vec3(0, Math.PI, 0) }));
-    expect(apply(rotated.items[0].matrix, 1, 0, 0)).toEqual([-1, 0, 0]);
+    expect(apply(rotated.items.at(0)?.matrix, 1, 0, 0)).toEqual([-1, 0, 0]);
   });
 
   it("gives every item of a top-level group that group's target, and the data of the group it's in", () => {
     const inner = group([sphere(1, red)], vec3Zero, vec3Zero, [], { part: "motor" });
     const fan = group([box(vec3(1, 1, 1), red)], vec3Zero, vec3Zero, [inner], { id: "fan" });
-    const compiled = compileScene(scene([fan, group([box(vec3(1, 1, 1), red)], vec3Zero, vec3Zero, [], { id: "coil" })]), (g) => g.data?.id ?? "");
+    const compiled = compileScene(scene([fan, group([box(vec3(1, 1, 1), red)], vec3Zero, vec3Zero, [], { id: "coil" })]), groupId);
     expect(compiled.targets).toEqual([
       { kind: "group", id: "fan", root: 0, rootData: { id: "fan" } },
       { kind: "group", id: "coil", root: 1, rootData: { id: "coil" } },
@@ -70,9 +83,9 @@ describe("compileScene", () => {
     );
     const compiled = compileScene(scene([group([], vec3(10, 0, 0), vec3Zero, [fan])]));
     expect(compiled.animations).toHaveLength(1);
-    expect(compiled.animations[0].speed).toEqual(vec3(0, 0, Math.PI));
-    expect(compiled.items[0].animation).toBe(0);
-    const world = (seconds: number): ReadonlyArray<number> => apply(getItemMatrix(compiled, compiled.items[0], seconds, new Matrix4()), 1, 0, 0);
+    expect(compiled.animations.at(0)?.speed).toEqual(vec3(0, 0, Math.PI));
+    expect(compiled.items.at(0)?.animation).toBe(0);
+    const world = (seconds: number): ReadonlyArray<number> => apply(getItemMatrix(compiled, getItem(compiled, 0), seconds, new Matrix4()), 1, 0, 0);
     expect(world(0)).toEqual([11, 5, 0]);
     expect(world(0.5)).toEqual([10, 6, 0]);
   });
@@ -82,8 +95,8 @@ describe("compileScene", () => {
     const inner = group([box(vec3(1, 1, 1), red)], vec3(1, 0, 0), vec3Zero, [], {}, spin);
     const compiled = compileScene(scene([group([], vec3Zero, vec3Zero, [inner], {}, spin)]));
     expect(compiled.animations.map((a) => a.parent)).toEqual([undefined, 0]);
-    expect(apply(getItemMatrix(compiled, compiled.items[0], 0.5, new Matrix4()), 0, 0, 0)).toEqual([0, 1, 0]);
-    expect(apply(getItemMatrix(compiled, compiled.items[0], 0.5, new Matrix4()), 1, 0, 0)).toEqual([-1, 1, 0]);
+    expect(apply(getItemMatrix(compiled, getItem(compiled, 0), 0.5, new Matrix4()), 0, 0, 0)).toEqual([0, 1, 0]);
+    expect(apply(getItemMatrix(compiled, getItem(compiled, 0), 0.5, new Matrix4()), 1, 0, 0)).toEqual([-1, 1, 0]);
   });
 
   it("converts aligned dimensions to dimension items with a target per dimension", () => {
@@ -92,22 +105,22 @@ describe("compileScene", () => {
     const items = compiled.items.filter((i) => i.style === "dimension");
     expect(items.length).toBeGreaterThan(0);
     expect(new Set(items.map((i) => i.role))).toEqual(new Set(["line", "text", "solid"]));
-    expect(compiled.targets[items[0].target]).toEqual({ kind: "dimension", id: "fan" });
+    expect(compiled.targets[items.at(0)?.target ?? -1]).toEqual({ kind: "dimension", id: "fan" });
   });
 
   it("adds relation shapes, with an outline around their boxes", () => {
     const relation = { id: "r1", pos: vec3Zero, groups: [group([box(vec3(10, 10, 10), red), sphere(1, red)], vec3(5, 0, 0))] };
     const compiled = compileScene(scene([], { relations: [relation] }));
     expect(compiled.items.map((i) => i.style)).toEqual(["relation", "outline", "relation"]);
-    expect(compiled.targets[compiled.items[0].target]).toEqual({ kind: "relation", relation });
-    const outline = compiled.items[1].mesh.geometry;
+    expect(compiled.targets[getItem(compiled, 0).target]).toEqual({ kind: "relation", relation });
+    const outline = getItem(compiled, 1).mesh.geometry;
     expect(outline.type === "Box" && outline.size).toEqual(vec3(10.125, 10.125, 10.125));
-    expect(apply(compiled.items[0].matrix, 0, 0, 0)).toEqual([5, 0, 0]);
+    expect(apply(compiled.items.at(0)?.matrix, 0, 0, 0)).toEqual([5, 0, 0]);
   });
 
   it("keeps the world matrix of each top-level group for its tooltips", () => {
     const compiled = compileScene(scene([group([], vec3(3, 0, 0))], { center_deprecated: vec3(1, 0, 0) }));
-    expect(apply(compiled.roots[0], 0, 0, 0)).toEqual([2, 0, 0]);
+    expect(apply(compiled.roots.at(0), 0, 0, 0)).toEqual([2, 0, 0]);
     expect(apply(compiled.matrix, 0, 0, 0)).toEqual([-1, 0, 0]);
   });
 });

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

@@ -1,8 +1,8 @@
 import { describe, expect, it } from "vitest";
 import type { Quality, TierGovernor } from "./quality.js";
-import { recordFrame } from "./quality.js";
+import { getPixelRatio, recordFrame } from "./quality.js";
 
-const governor = (quality: Quality): TierGovernor => ({ quality, tier: quality === "auto" ? "medium" : quality, sum: 0, count: 0 });
+const governor = (quality: Quality): TierGovernor => ({ quality, tier: quality === "auto" ? "high" : quality, sum: 0, count: 0 });
 const record = (g: TierGovernor, intervals: ReadonlyArray<number>): ReadonlyArray<boolean> => intervals.map((ms) => recordFrame(g, ms));
 
 describe("recordFrame", () => {
@@ -19,12 +19,19 @@ describe("recordFrame", () => {
     expect(g.tier).toBe("low");
   });
 
-  it("keeps auto at medium at 60 frames per second, ignoring the pauses between moves", () => {
+  it("keeps auto at high at 60 frames per second, ignoring the pauses between moves", () => {
     const g = governor("auto");
     record(
       g,
       Array.from({ length: 100 }, (_, i) => (i % 10 === 0 ? 2000 : 16.7))
     );
-    expect(g.tier).toBe("medium");
+    expect(g.tier).toBe("high");
+  });
+});
+
+describe("getPixelRatio", () => {
+  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,35 +1,20 @@
-import { N8AOPass } from "n8ao";
-import type { OrthographicCamera, PerspectiveCamera, Scene, WebGLRenderer } from "three";
-import { EffectComposer } from "three/addons/postprocessing/EffectComposer.js";
-import { OutputPass } from "three/addons/postprocessing/OutputPass.js";
-
 /**
- * Quality tiers that spend the GPU where it shows: the camera is still most of the time, and a still frame can afford ambient occlusion that a moving
- * one can't on a weak GPU. Low renders directly; medium adds ambient occlusion at rest, faded in; high has it while moving too. Effects only at rest
- * is how progressive model viewers such as Sketchfab's stay fast; the AO is N8AO, configured as the r3f renderer's
+ * 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";
 export type Quality = Tier | "auto";
 
-/** `auto` starts at medium, and drops to low for good once moving frames average slower than 40 per second */
+/** `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 };
 
-export type RenderPath = {
-  readonly tier: Tier;
-  /** With ambient occlusion, faded in by its intensity over the first frames at rest */
-  readonly composer: EffectComposer | undefined;
-  readonly ao: { readonly configuration: { intensity: number } } | undefined;
-  readonly fade: { frame: 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 */
 const pauseMs = 250;
-const fadeFrames = 6;
-const intensity = 2;
 
 /** Records the time between two frames while the camera moves; true when that dropped the tier */
 export function recordFrame(governor: TierGovernor, intervalMs: number): boolean {
@@ -46,50 +31,6 @@ export function recordFrame(governor: TierGovernor, intervalMs: number): boolean
   return slow;
 }
 
-/** Also sets the renderer's pixel ratio, capped by the tier */
-export function createRenderPath(renderer: WebGLRenderer, scene: Scene, camera: PerspectiveCamera | OrthographicCamera, tier: Tier): RenderPath {
-  renderer.setPixelRatio(Math.min(window.devicePixelRatio, pixelRatioCaps[tier]));
-  if (tier === "low") {
-    return { tier, composer: undefined, ao: undefined, fade: { frame: 0 } };
-  }
-  const composer = new EffectComposer(renderer);
-  const ao = new N8AOPass(scene, camera);
-  Object.assign(ao.configuration, {
-    aoRadius: 40,
-    distanceFalloff: 0.2,
-    screenSpaceRadius: true,
-    halfRes: true,
-    denoiseSamples: 4,
-    gammaCorrection: false,
-  });
-  // Multisampled, as SMAA, which N8AO suggests, would lose the antialiased alpha at edges over the transparent background
-  ao.beautyRenderTarget.samples = 4;
-  composer.addPass(ao);
-  // Tone mapping and sRGB, which rendering to the screen otherwise does
-  composer.addPass(new OutputPass());
-  return { tier, composer, ao, fade: { frame: 0 } };
-}
-
-/** Renders a frame; true while the frame at rest needs more frames to fade its ambient occlusion in */
-export function renderPath(
-  path: RenderPath,
-  renderer: WebGLRenderer,
-  scene: Scene,
-  camera: PerspectiveCamera | OrthographicCamera,
-  moving: boolean
-): boolean {
-  if (!path.composer || !path.ao || (moving && path.tier === "medium")) {
-    path.fade.frame = 0;
-    renderer.render(scene, camera);
-    return false;
-  }
-  path.fade.frame = path.tier === "high" ? fadeFrames : Math.min(fadeFrames, path.fade.frame + 1);
-  path.ao.configuration.intensity = (intensity * path.fade.frame) / fadeFrames;
-  path.composer.render();
-  return path.fade.frame < fadeFrames;
-}
-
-export function disposeRenderPath(path: RenderPath): void {
-  path.composer?.passes.forEach((p) => p.dispose());
-  path.composer?.dispose();
+export function getPixelRatio(tier: Tier, devicePixelRatio: number): number {
+  return Math.min(devicePixelRatio, pixelRatioCaps[tier]);
 }

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

@@ -0,0 +1,111 @@
+import {
+  Box3,
+  type Scene,
+  Mesh,
+  MeshBasicMaterial,
+  MeshDepthMaterial,
+  OrthographicCamera,
+  PlaneGeometry,
+  ShaderMaterial,
+  UniformsUtils,
+  Vector3,
+  type WebGLRenderer,
+  WebGLRenderTarget,
+} from "three";
+import { FullScreenQuad } from "three/addons/postprocessing/Pass.js";
+import { HorizontalBlurShader } from "three/addons/shaders/HorizontalBlurShader.js";
+import { VerticalBlurShader } from "three/addons/shaders/VerticalBlurShader.js";
+import type { BuiltScene } from "../build/build.js";
+
+/**
+ * A soft shadow on the ground the scene stands on, rendered once per build: the solids seen from below by their depth, darker the closer to the
+ * ground, blurred into a texture on a plane, so a frame costs one textured quad. three.js's webgl_shadow_contact example, rendered once as drei's
+ * ContactShadows with `frames={1}`
+ */
+
+export type GroundShadow = { readonly mesh: 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;
+/** The blur's reach, of the solids' height */
+const softness = 0.15;
+const opacity = 0.8;
+
+/** 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 bounds = new Box3();
+  built.parts.forEach((part) => {
+    if (part.kind === "solid" && part.object.parent !== built.dimensions && part.object.boundingBox) {
+      part.object.layers.enable(shadowLayer);
+      bounds.union(part.object.boundingBox);
+    }
+  });
+  if (bounds.isEmpty()) {
+    return undefined;
+  }
+  const size = bounds.getSize(new Vector3());
+  // 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)];
+
+  // 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();
+  // 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 );"
+    );
+  };
+  const previous = renderer.getRenderTarget();
+  Object.assign(scene, { overrideMaterial: darkness });
+  renderer.setRenderTarget(target);
+  renderer.render(scene, camera);
+  Object.assign(scene, { overrideMaterial: null });
+
+  const horizontal = new ShaderMaterial({ ...HorizontalBlurShader, uniforms: UniformsUtils.clone(HorizontalBlurShader.uniforms) });
+  const vertical = new ShaderMaterial({ ...VerticalBlurShader, uniforms: UniformsUtils.clone(VerticalBlurShader.uniforms) });
+  const quad = new FullScreenQuad(horizontal);
+  // The blur shaders reach 4 steps; three passes of shrinking steps blend into one smooth falloff
+  const step = (reach * texelsX) / width / 4;
+  [step, step / 2, step / 4].forEach((amount) => {
+    Object.assign(horizontal.uniforms, { tDiffuse: { value: target.texture }, h: { value: amount / texelsX } });
+    quad.material = horizontal;
+    renderer.setRenderTarget(blurred);
+    quad.render(renderer);
+    Object.assign(vertical.uniforms, { tDiffuse: { value: blurred.texture }, v: { value: amount / texelsZ } });
+    quad.material = vertical;
+    renderer.setRenderTarget(target);
+    quad.render(renderer);
+  });
+  renderer.setRenderTarget(previous);
+  [blurred, darkness, horizontal, vertical, quad].forEach((d) => d.dispose());
+
+  // 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 })
+  );
+  mesh.position.copy(center);
+  mesh.scale.y = -1;
+  scene.add(mesh);
+  return { mesh, target };
+}
+
+export function disposeGroundShadow(shadow: GroundShadow): void {
+  shadow.mesh.removeFromParent();
+  shadow.mesh.geometry.dispose();
+  shadow.mesh.material.dispose();
+  shadow.target.dispose();
+}

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

@@ -34,7 +34,7 @@ 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;
@@ -46,7 +46,9 @@ export type ViewerOptions<Content> = {
   /** 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;
   readonly environmentIntensity?: number;
-  /** `low` by default, without ambient occlusion */
+  /** A soft shadow on the ground under the scene, rendered once per build; on by default */
+  readonly groundShadow?: 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>;
@@ -61,10 +63,12 @@ export type ViewerOptions<Content> = {
   readonly onHoverGroup?: (id: string | undefined, rootData: Data, data: Data, event: SceneEvent) => void;
   readonly onContextMenuGroup?: (id: string, rootData: Data, data: Data, left: number, top: number, event: SceneEvent) => void;
   readonly onClickRelation?: (relation: Relation, event: SceneEvent) => void;
+  /** A click, not a drag, on nothing clickable, e.g. the background; r3f's Canvas event of the same name */
+  readonly onPointerMissed?: (event: MouseEvent) => void;
 };
 
 /** What an update has to redo, in the order it's redone */
-export type Change = "compile" | "build" | "camera" | "controls" | "gizmo" | "lights" | "quality" | "paint" | "dimensions" | "overlays";
+export type Change = "compile" | "build" | "shadow" | "camera" | "controls" | "gizmo" | "lights" | "quality" | "paint" | "dimensions" | "overlays";
 
 /** What passing each option redoes; callbacks and what's read later need nothing */
 export const effects: { readonly [K in keyof ViewerOptions<unknown>]-?: ReadonlyArray<Change> } = {
@@ -86,6 +90,7 @@ export const effects: { readonly [K in keyof ViewerOptions<unknown>]-?: Readonly
   lights: ["lights"],
   environment: ["lights"],
   environmentIntensity: ["lights"],
+  groundShadow: ["shadow"],
   quality: ["quality"],
   popovers: ["overlays"],
   getTooltips: ["overlays"],
@@ -95,4 +100,5 @@ export const effects: { readonly [K in keyof ViewerOptions<unknown>]-?: Readonly
   onHoverGroup: [],
   onContextMenuGroup: [],
   onClickRelation: [],
+  onPointerMissed: [],
 };

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

@@ -32,8 +32,10 @@ import { configureControls, createControls, setPose } from "../camera/controls.j
 import { createGizmo } from "../camera/gizmo.js";
 import type { CompiledScene } from "../compile/compile.js";
 import { compileScene } from "../compile/compile.js";
-import type { RenderPath, TierGovernor } from "../quality/quality.js";
-import { createRenderPath, disposeRenderPath, recordFrame, renderPath } from "../quality/quality.js";
+import type { TierGovernor } from "../quality/quality.js";
+import { getPixelRatio, recordFrame } from "../quality/quality.js";
+import type { GroundShadow } from "../shadow/shadow.js";
+import { createGroundShadow, disposeGroundShadow } from "../shadow/shadow.js";
 import type { GlyphAtlas } from "../text/text.js";
 import { createGlyphAtlas } from "../text/text.js";
 import type { Change, ViewerOptions } from "./options.js";
@@ -77,7 +79,7 @@ export type Viewer<Content> = {
   compiled?: CompiledScene;
   built?: BuiltScene;
   gizmo?: ViewportGizmo;
-  path?: RenderPath;
+  shadow?: GroundShadow;
   governor?: TierGovernor;
   readonly environments: Partial<Record<"studio" | "room", Texture>>;
   /** The scene is built and its shaders compiled */
@@ -164,12 +166,12 @@ export function disposeViewer<Content>(v: Viewer<Content>): void {
   v.resizeObserver.disconnect();
   v.controls.orbit.dispose();
   v.gizmo?.dispose();
-  if (v.path) {
-    disposeRenderPath(v.path);
-  }
   if (v.built) {
     disposeScene(v.built);
   }
+  if (v.shadow) {
+    disposeGroundShadow(v.shadow);
+  }
   Object.values(v.environments).forEach((e) => e.dispose());
   v.geometries.forEach((g) => g.dispose());
   v.atlas.texture.dispose();
@@ -191,16 +193,22 @@ function apply<Content>(v: Viewer<Content>, changes: ReadonlySet<Change>): void
     v.structure = { activeComponents: options.activeComponents, relationsActive: options.activeRelations !== undefined };
     rebuild(v);
   }
+  if (changes.has("shadow") || changes.has("build")) {
+    if (v.shadow) {
+      disposeGroundShadow(v.shadow);
+    }
+    v.shadow = v.built && options.groundShadow !== false ? createGroundShadow(v.renderer, v.scene, v.built) : undefined;
+  }
   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);
   }
@@ -211,11 +219,9 @@ function apply<Content>(v: Viewer<Content>, changes: ReadonlySet<Change>): void
     updateLights(v);
   }
   if (changes.has("quality")) {
-    const quality = options.quality ?? "low";
-    v.governor = { quality, tier: quality === "auto" ? "medium" : quality, sum: 0, count: 0 };
-  }
-  if (changes.has("quality") || changes.has("camera")) {
-    updateRenderPath(v);
+    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));
   }
   if ((changes.has("paint") || changes.has("build")) && v.built) {
     const start = performance.now();
@@ -284,7 +290,7 @@ function renderFrame<Content>(v: Viewer<Content>, now: number): void {
   renderer.info.reset();
   const moving = v.controls.orbit.update(Math.min(interval / 1000, 0.1)) || !!gizmo?.animating;
   if (moving && loop.wasMoving && v.governor && recordFrame(v.governor, interval)) {
-    updateRenderPath(v);
+    renderer.setPixelRatio(getPixelRatio(v.governor.tier, window.devicePixelRatio));
   }
   loop.wasMoving = moving;
   const animated = !!built && built.animatedItems.length > 0;
@@ -296,33 +302,38 @@ function renderFrame<Content>(v: Viewer<Content>, now: number): void {
   if (built) {
     cullScene(built, camera.position);
   }
-  const fading = v.loaded && v.path ? renderPath(v.path, renderer, v.scene, camera, moving || animated) : false;
+  if (v.loaded) {
+    renderer.render(v.scene, camera);
+  }
   gizmo?.render();
   v.overlays.renderer.render(v.overlays.scene, camera);
   Object.assign(v.stats, { frames: v.stats.frames + 1, frameMs: performance.now() - start, drawCalls: renderer.info.render.calls });
-  if (moving || animated || fading) {
+  if (moving || animated) {
     invalidate(v);
   } else {
     loop.last = 0;
   }
 }
 
+/** 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.path?.composer?.setSize(rect.width, rect.height);
   v.overlays.renderer.setSize(rect.width, rect.height);
   v.gizmo?.update();
-  fitPose(v);
+  if (aspectChanged) {
+    fitPose(v);
+  }
   invalidate(v);
 }
 
-/** 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;
   }
 }
@@ -369,13 +380,16 @@ function hoverAtPointer<Content>(v: Viewer<Content>): void {
 
 function onClick<Content>(v: Viewer<Content>, event: MouseEvent): void {
   const { down } = v.pointer;
-  const hit = down && Math.hypot(event.clientX - down.x, event.clientY - down.y) <= clickTolerance ? pick(v, event) : undefined;
+  const clicked = !!down && Math.hypot(event.clientX - down.x, event.clientY - down.y) <= clickTolerance;
+  const hit = clicked ? pick(v, event) : undefined;
   const target = hit && v.compiled!.targets[hit.target];
   const args = hit && getGroupArgs(v, hit);
   if (hit && target?.kind === "relation") {
     v.options.onClickRelation?.(target.relation, { nativeEvent: event, point: hit.point });
   } else if (hit && args) {
     v.options.onClickGroup?.(...args, { nativeEvent: event, point: hit.point });
+  } else if (clicked) {
+    v.options.onPointerMissed?.(event);
   }
 }
 
@@ -529,12 +543,5 @@ function updateOverlays<Content>(v: Viewer<Content>): void {
   setOverlays(v.overlays, overlays, options.onOverlays);
 }
 
-function updateRenderPath<Content>(v: Viewer<Content>): void {
-  if (v.path) {
-    disposeRenderPath(v.path);
-  }
-  v.path = createRenderPath(v.renderer, v.scene, v.camera, v.governor?.tier ?? "low");
-}
-
 const raycaster = new Raycaster();
 const ndc = new Vector2();

package/src/custom_typings/n8ao.d.ts

@@ -1,11 +0,0 @@
-declare module "n8ao" {
-  import type { Camera, Scene, WebGLRenderTarget } from "three";
-  import type { Pass } from "three/addons/postprocessing/Pass.js";
-
-  type AOPass = Pass & {
-    readonly configuration: Record<string, unknown> & { intensity: number };
-    readonly beautyRenderTarget: WebGLRenderTarget;
-  };
-
-  export const N8AOPass: new (scene: Scene, camera: Camera, width?: number, height?: number) => AOPass;
-}