@pascal-app/editor 1.0.4 → 1.0.6

package/src/components/editor/thumbnail-generator.test.ts

@@ -1,14 +1,56 @@
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
-import { type AnyNode, sceneRegistry, useScene } from '@pascal-app/core'
-import { BuildingNode, CeilingNode, LevelNode, WallNode } from '@pascal-app/core/schema'
-import { hideFromScene, SCENE_LAYER, useViewer } from '@pascal-app/viewer'
-import { Group, Layers, Mesh, OrthographicCamera, PerspectiveCamera, Vector2 } from 'three'
+import {
+  type AnyNode,
+  type AnyNodeId,
+  createTerrainField,
+  emitter,
+  encodeTerrainField,
+  getLevelElevations,
+  sceneRegistry,
+  useScene,
+} from '@pascal-app/core'
+import { type SceneViewPose, sceneViewPlan } from '@pascal-app/core/agent-operations'
+import {
+  BuildingNode,
+  CeilingNode,
+  LevelNode,
+  SiteNode,
+  SlabNode,
+  WallNode,
+} from '@pascal-app/core/schema'
+import {
+  groundWindowBoxNow,
+  hideFromScene,
+  SCENE_LAYER,
+  SITE_GROUND,
+  setGroundWindow,
+  useViewer,
+} from '@pascal-app/viewer'
+import {
+  Group,
+  Layers,
+  Mesh,
+  type Object3D,
+  OrthographicCamera,
+  PerspectiveCamera,
+  PlaneGeometry,
+  Raycaster,
+  Scene,
+  Vector2,
+  Vector3,
+} from 'three'
 import { CanvasTarget, ClippingGroup, type WebGPURenderer } from 'three/webgpu'
+import hillside from '../../../../core/src/lib/__fixtures__/owner-hillside-grade.json'
+import victorSeattle from '../../lib/__fixtures__/owner-victor-seattle-parking.json'
+import villaAurelia from '../../lib/__fixtures__/owner-villa-aurelia-basement.json'
 import {
   atCaptureSize,
+  captureDimensions,
   capturesOrthographically,
+  exteriorGroundForCapture,
   interiorCutaway,
   presentFinished,
+  presentWhileCapturing,
   pumpFrames,
   tileGrid,
 } from './thumbnail-generator'
@@ -47,6 +89,34 @@ function fakeRenderer(canvas: FakeCanvas, pixelRatio: number) {
 }
 
 describe('supersampled capture', () => {
+  test('an explicit camera renders at the requested resolution and aspect without resizing the pane', () => {
+    const live: FakeCanvas = { width: 800, height: 1000, style: {} }
+    const renderer = fakeRenderer(live, 1)
+    const position: [number, number, number] = [2, 1, 3]
+    const target: [number, number, number] = [0, 0, 0]
+    for (const pose of [
+      { perspective: { position, target, fov: 35 } },
+      { ortho: { position, target, viewWidth: 4 } },
+    ]) {
+      const size = captureDimensions(
+        [800, 1000],
+        { ...pose, standardSize: { w: 1920, h: 1280 } },
+        24_000_000,
+      )
+      expect(size).toEqual([1920, 1280])
+      const buffer = atCaptureSize(renderer, ...size, () =>
+        renderer.getDrawingBufferSize(new Vector2()).toArray(),
+      )
+      expect(buffer).toEqual([1920, 1280])
+      expect([live.width, live.height]).toEqual([800, 1000])
+    }
+    expect(
+      captureDimensions([800, 1000], { standardSize: { w: 1920, h: 1280 } }, 24_000_000),
+    ).toEqual([800, 1000])
+    expect(captureDimensions([800, 1000], { supersample: 2 }, 24_000_000)).toEqual([1600, 2000])
+    expect(captureDimensions([6000, 4000], { supersample: 2 }, 6_000_000)).toEqual([3000, 2000])
+  })
+
   test('renders at its own size while the live canvas keeps its size', () => {
     // a 1.5 dpr screen: the old capture resized the live canvas with drawing
     // buffer pixels where CSS pixels were due — 3× during the capture, 1.5×
@@ -177,6 +247,46 @@ describe('a sheet capture session', () => {
     unsubscribe()
     expect(writes).toBe(0)
   })
+
+  // A sheet's pictures and an agent's view can overlap: the user's view is the one before the
+  // first, never a run's finished presentation.
+  test('runs that overlap present once and put the view back after the last', () => {
+    const session = (owner: string, active: boolean) =>
+      emitter.emit('camera-controls:capture-session', { owner, active })
+    const steps: string[] = []
+    const stop = presentWhileCapturing(() => {
+      steps.push('present')
+      return () => steps.push('restore')
+    })
+    session('sheets-a', true)
+    session('view-b', true)
+    session('sheets-a', false)
+    expect(steps).toEqual(['present'])
+    session('nobody', false)
+    session('view-b', false)
+    expect(steps).toEqual(['present', 'restore'])
+    session('view-c', true)
+    stop()
+    expect(steps).toEqual(['present', 'restore', 'present', 'restore'])
+    session('view-c', false)
+    expect(steps).toHaveLength(4)
+  })
+
+  // The generator mounted while a sheet captures (a remount, the editor opened mid-run): the run's
+  // finished presentation from the first frame, the user's view back at its end.
+  test('a run already on when the generator mounts is presented at once', () => {
+    emitter.emit('camera-controls:capture-session', { owner: 'sheets-early', active: true })
+    const steps: string[] = []
+    const stop = presentWhileCapturing(() => {
+      steps.push('present')
+      return () => steps.push('restore')
+    })
+    expect(steps).toEqual(['present'])
+    emitter.emit('camera-controls:capture-session', { owner: 'sheets-early', active: false })
+    expect(steps).toEqual(['present', 'restore'])
+    stop()
+    expect(steps).toEqual(['present', 'restore'])
+  })
 })
 
 describe('a print-size picture past one render pass', () => {
@@ -289,6 +399,242 @@ describe('an interior view of a floor', () => {
   })
 })
 
+// What a capture's own camera sees of the ground, on the owner's scenes (13 and 14 Oct, trimmed to
+// their levels, slabs and walls) and a review's plate: the basement's floor and not the lawn, the
+// window opened for the frame (and the person's own given back), and nothing opened from the
+// garden side. Each test runs the cutaway as the capture does, looks, and restores.
+describe('what a capture sees of the ground', () => {
+  let previousScene: ReturnType<typeof useScene.getState>
+  beforeEach(() => {
+    previousScene = useScene.getState()
+  })
+  afterEach(() => {
+    sceneRegistry.clear()
+    useScene.setState(previousScene, true)
+  })
+
+  /**
+   * The scene as the editor holds it: every level's object at its height, a floor in `basement`, and
+   * the site's lawn (wider than any frame) with its veil, hidden. The veil is never picked, as
+   * GroundVeil mounts it: the ray below sees through it.
+   */
+  function editorScene(
+    nodes: Record<AnyNodeId, AnyNode>,
+    basement?: string,
+    siteId = 'site_owner',
+  ) {
+    useScene.setState({ nodes } as never)
+    const scene = new Scene()
+    for (const [levelId, { baseY }] of getLevelElevations(nodes)) {
+      const level = new Group()
+      level.position.y = baseY
+      scene.add(level)
+      sceneRegistry.nodes.set(levelId, level)
+    }
+    const floor = new Mesh(new PlaneGeometry(400, 400).rotateX(-Math.PI / 2))
+    if (basement) sceneRegistry.nodes.get(basement)?.add(floor)
+    const ground = new Mesh(new PlaneGeometry(400, 400).rotateX(-Math.PI / 2))
+    ground.userData[SITE_GROUND] = 'solid'
+    const veil = new Mesh(ground.geometry)
+    veil.userData[SITE_GROUND] = 'veil'
+    veil.visible = false
+    veil.raycast = () => {}
+    const lotLine = new Mesh()
+    const site = new Group().add(ground, veil, lotLine)
+    scene.add(site)
+    sceneRegistry.nodes.set(siteId, site)
+    sceneRegistry.byType.site?.add(siteId)
+    return { scene, floor, ground, veil, lotLine }
+  }
+
+  /** Opens the capture's ground cutaway, runs `look`, restores in reverse; returns what `look` returns. */
+  function whileCut<T>(open: (add: (restore: () => void) => void) => void, look: () => T): T {
+    const restorers: (() => void)[] = []
+    open((restore) => restorers.push(restore))
+    try {
+      return look()
+    } finally {
+      for (const restore of restorers.reverse()) restore()
+    }
+  }
+
+  /** The first thing the capture camera draws on the line from its eye to its aim. */
+  function firstSeen(scene: Scene, pose: SceneViewPose): Object3D | undefined {
+    const eye = new Vector3(...pose.position)
+    const ray = new Raycaster(eye, new Vector3(...pose.target).sub(eye).normalize())
+    ray.layers.set(SCENE_LAYER)
+    scene.updateMatrixWorld(true)
+    const drawn = (object: Object3D | null): boolean =>
+      !object || (object.visible && drawn(object.parent))
+    return ray.intersectObject(scene, true).find((hit) => drawn(hit.object))?.object
+  }
+
+  const cameraAt = (position: [number, number, number]) => {
+    const camera = new PerspectiveCamera()
+    camera.position.set(...position)
+    return camera
+  }
+  const persons = {
+    min: [-6, 0, -7] as [number, number, number],
+    max: [6, 3, 7] as [number, number, number],
+  }
+
+  // The villa's Lower Ground 3.35 m under the lawn, the Victor's parking 2.61 m under it and past
+  // its west lot line.
+  test.each([
+    ['the villa Aurelia', villaAurelia, 'level_68jf2zqaukfjof3m', 'level_ztimtvrgdzzd6c9f'],
+    ['the Victor Seattle', victorSeattle, 'level_q209tmgwuzcahwzj', 'level_wj5tz664u03eolux'],
+  ] as const)(
+    "the agent's picture of %s's basement sees its floor, not the lawn; a floor at grade is pictured on solid ground, even veiled",
+    (_, owner, basement, atGrade) => {
+      const nodes = owner.nodes as unknown as Record<AnyNodeId, AnyNode>
+      const plan = sceneViewPlan(nodes, { target: basement })
+      const { scene, floor, ground, veil, lotLine } = editorScene(nodes, basement)
+      expect(firstSeen(scene, plan.pose)).toBe(ground)
+      whileCut(
+        (add) => interiorCutaway(basement, add),
+        () => {
+          expect(firstSeen(scene, plan.pose)).toBe(floor)
+          expect(veil.visible).toBe(true)
+          expect(lotLine.layers.isEnabled(SCENE_LAYER)).toBe(true)
+        },
+      )
+      expect(firstSeen(scene, plan.pose)).toBe(ground)
+      expect(veil.visible).toBe(false)
+
+      // A floor at grade while the person has the ground veiled and aside.
+      hideFromScene(ground, 'ground-aside')
+      veil.visible = true
+      whileCut(
+        (add) => interiorCutaway(atGrade, add),
+        () => {
+          expect(ground.layers.isEnabled(SCENE_LAYER)).toBe(true)
+          expect(veil.visible).toBe(false)
+        },
+      )
+      expect(ground.layers.isEnabled(SCENE_LAYER)).toBe(false)
+      expect(veil.visible).toBe(true)
+    },
+  )
+
+  // The owner's hillside house (14 Oct): no floor buried, a 6 m plateau on the street side. A
+  // capture from the street sees the house through the ground window, from its own camera,
+  // whatever the person's view holds; from the garden side the ground stands solid.
+  describe('on the hillside house', () => {
+    const nodes = hillside.nodes as unknown as Record<AnyNodeId, AnyNode>
+    const garden = Object.values(nodes).find(
+      (node) => node.type === 'level' && node.name === 'Garden level · walk-out',
+    )
+    if (!garden) throw new Error('the hillside fixture is missing its garden level')
+
+    test('from the street side the window opens for the frame and closes after it, the solid ground staying drawn; from the garden side none opens', () => {
+      const { ground, veil } = editorScene(nodes, undefined, 'site_hillside')
+      whileCut(
+        (add) => interiorCutaway(garden.id, add, cameraAt([0, 7, -20])),
+        () => {
+          expect(groundWindowBoxNow()).not.toBeNull()
+          expect(veil.visible).toBe(true)
+          // Its window is cut per fragment, not by hiding it.
+          expect(ground.layers.isEnabled(SCENE_LAYER)).toBe(true)
+        },
+      )
+      expect(groundWindowBoxNow()).toBeNull()
+      expect(veil.visible).toBe(false)
+      whileCut(
+        (add) => interiorCutaway(garden.id, add, cameraAt([0, 3, 20])),
+        () => {
+          expect(groundWindowBoxNow()).toBeNull()
+          expect(veil.visible).toBe(false)
+        },
+      )
+    })
+
+    // Both agent lanes ask with a perspective/orthographic pose of their own, not a cameraPose:
+    // the posed exterior frame decides its window from its own eye, not the person's closed one.
+    test('a posed exterior capture decides its own window and gives the person’s back; an unposed one decides none', () => {
+      const { veil } = editorScene(nodes, undefined, 'site_hillside')
+      whileCut(
+        (add) => exteriorGroundForCapture(add, true, cameraAt([0, 7, -20])),
+        () => {
+          expect(groundWindowBoxNow()).not.toBeNull()
+          expect(veil.visible).toBe(true)
+        },
+      )
+      expect(groundWindowBoxNow()).toBeNull()
+      expect(veil.visible).toBe(false)
+      // The person's window, open for their eye, closes for a garden-side frame and returns; an
+      // unposed capture leaves it alone.
+      setGroundWindow(persons)
+      whileCut(
+        (add) => exteriorGroundForCapture(add, true, cameraAt([0, 3, 20])),
+        () => expect(groundWindowBoxNow()).toBeNull(),
+      )
+      expect(groundWindowBoxNow()).toBe(persons)
+      whileCut(
+        (add) => exteriorGroundForCapture(add, false, cameraAt([0, 3, 20])),
+        () => expect(groundWindowBoxNow()).toBe(persons),
+      )
+      expect(groundWindowBoxNow()).toBe(persons)
+      setGroundWindow(null)
+    })
+  })
+
+  // The review's plate (14 Oct): [-5,5] × [-4,4] at Y 0.2, terrain 2 m only inside x 0…4, z -3…3.
+  // An interior capture from overhead opens the window over the buried eastern rooms: partly below
+  // grade has no wholesale veil to fall back on.
+  test('from overhead the window opens over the buried rooms of a floor partly below grade, and closes after', () => {
+    const field = createTerrainField({ cols: 25, rows: 25, spacing: 1, origin: [-12, -12] })
+    const heights = new Int16Array(field.heights)
+    for (let row = 0; row < field.rows; row += 1)
+      for (let col = 0; col < field.cols; col += 1) {
+        const x = field.origin[0] + col * field.spacing
+        const z = field.origin[1] + row * field.spacing
+        if (x >= 0 && x <= 4 && z >= -3 && z <= 3) heights[row * field.cols + col] = 200
+      }
+    const list: AnyNode[] = [
+      SiteNode.parse({
+        id: 'site_a',
+        children: ['building_a'],
+        terrain: encodeTerrainField({ ...field, heights }),
+      }),
+      BuildingNode.parse({ id: 'building_a', parentId: 'site_a', children: ['level_0'] }),
+      LevelNode.parse({
+        id: 'level_0',
+        level: 0,
+        height: 3,
+        parentId: 'building_a',
+        children: ['slab_0'],
+      }),
+      SlabNode.parse({
+        id: 'slab_0',
+        parentId: 'level_0',
+        elevation: 0.2,
+        polygon: [
+          [-5, -4],
+          [5, -4],
+          [5, 4],
+          [-5, 4],
+        ],
+      }),
+    ]
+    const { ground, veil } = editorScene(
+      Object.fromEntries(list.map((node) => [node.id, node])) as Record<AnyNodeId, AnyNode>,
+      undefined,
+      'site_a',
+    )
+    whileCut(
+      (add) => interiorCutaway('level_0', add, cameraAt([0, 15, 0])),
+      () => {
+        expect(groundWindowBoxNow()).not.toBeNull()
+        expect(veil.visible).toBe(true)
+        expect(ground.layers.isEnabled(SCENE_LAYER)).toBe(true)
+      },
+    )
+    expect(groundWindowBoxNow()).toBeNull()
+    expect(veil.visible).toBe(false)
+  })
+})
+
 describe("a capture's projection", () => {
   const user = { ortho: new OrthographicCamera(), perspective: new PerspectiveCamera() }
   const view = { position: [8, 6, 8], target: [0, 1, 0] } as never

package/src/components/editor/thumbnail-generator.tsx

@@ -1,6 +1,14 @@
 'use client'
 
-import { emitter, sceneRegistry, type ThumbnailGenerateEvent, useScene } from '@pascal-app/core'
+import {
+  emitter,
+  isCaptureSessionOn,
+  levelGradeStanding,
+  sceneRegistry,
+  subscribeCaptureSessions,
+  type ThumbnailGenerateEvent,
+  useScene,
+} from '@pascal-app/core'
 import { sceneViewInterior } from '@pascal-app/core/agent-operations'
 import {
   computeHeroFraming,
@@ -9,6 +17,7 @@ import {
   heroCameraPose,
   holdLiveFrame,
   pendingSceneBuildCount,
+  presentLevelsForCapture,
   refreshIsolation,
   SNAPSHOT_MAX_EDGE,
   SNAPSHOT_MIME,
@@ -17,9 +26,12 @@ import {
   snapLevelsToTruePositions,
   THUMBNAIL_HEIGHT,
   THUMBNAIL_WIDTH,
+  temporarilyGroundWindowForCapture,
   temporarilyHideNodeTypes,
   temporarilyShowPresentation,
   temporarilyShowShadowOnly,
+  temporarilyVeilGround,
+  temporarilyWithoutAmbiance,
   useSceneAtmosphere,
   useViewer,
 } from '@pascal-app/viewer'
@@ -48,6 +60,7 @@ export interface SnapshotCameraData {
   zoom?: number
   captureMode?: 'standard' | 'viewport' | 'area'
   resolution?: { w: number; h: number }
+  presentation?: ThumbnailGenerateEvent['presentation']
 }
 
 interface ThumbnailGeneratorProps {
@@ -69,6 +82,25 @@ const TILE_OVERLAP = 96
 
 type CaptureLimits = { passEdge: number; maxPixels: number; software: boolean }
 
+export function captureDimensions(
+  canvasSize: readonly [number, number],
+  event: Pick<ThumbnailGenerateEvent, 'ortho' | 'perspective' | 'standardSize' | 'supersample'>,
+  maxPixels: number,
+): [number, number] {
+  const supersample = event.supersample ?? 1
+  // A requested camera must not inherit the editor pane's aspect or be upscaled from its crop.
+  const size =
+    (event.ortho || event.perspective) && event.standardSize && supersample === 1
+      ? [event.standardSize.w, event.standardSize.h]
+      : canvasSize
+  const scale = Math.min(
+    Math.max(1, supersample),
+    MAX_CAPTURE_EDGE / Math.max(size[0], size[1]),
+    Math.sqrt(maxPixels / (size[0] * size[1])),
+  )
+  return [Math.round(size[0] * scale), Math.round(size[1] * scale)]
+}
+
 /**
  * What one capture may ask of this GPU: a pass no larger than its biggest
  * texture (and MAX_PASS_EDGE), and — on a software renderer, where a big
@@ -443,6 +475,29 @@ export function presentFinished(): () => void {
   }
 }
 
+/**
+ * The pictures' scene while a capture session is on (core's `isCaptureSessionOn`, runs that overlap
+ * counted once): `present` when the first starts, and what it returns, which puts the user's view
+ * back, when the last ends. Returns the stop, which puts the view back if a session is still on.
+ */
+export function presentWhileCapturing(present: () => () => void): () => void {
+  let restore: (() => void) | null = null
+  const follow = () => {
+    if (isCaptureSessionOn() && !restore) restore = present()
+    else if (!isCaptureSessionOn() && restore) {
+      restore()
+      restore = null
+    }
+  }
+  follow()
+  const unsubscribe = subscribeCaptureSessions(follow)
+  return () => {
+    unsubscribe()
+    restore?.()
+    restore = null
+  }
+}
+
 /** A yield to the next macrotask through a MessageChannel — unlike a timer, never throttled in a hidden tab. */
 function macrotask(): Promise<void> {
   return new Promise((resolve) => {
@@ -492,10 +547,18 @@ function clipSceneFor(
  * floors and this floor's roofs and ceilings out of the picture, everything
  * on it cut where core says (sceneViewInterior, from the scene as this editor
  * has it) and its shadows with it, and whatever the user's solo or isolation
- * holds back on it shown.
+ * holds back on it shown. The site's ground follows this floor, not the
+ * user's: veiled wholesale over a floor below grade; over one only partly
+ * below grade, or at grade behind a hillside, veiled only where it stands
+ * between this frame's camera and the floor (the ground window).
  */
-export function interiorCutaway(levelId: string, restore: (callback: () => void) => void) {
-  const { cutHeight, hiddenIds } = sceneViewInterior(useScene.getState().nodes, levelId)
+export function interiorCutaway(
+  levelId: string,
+  restore: (callback: () => void) => void,
+  camera?: THREE.Camera,
+) {
+  const { nodes } = useScene.getState()
+  const { cutHeight, hiddenIds } = sceneViewInterior(nodes, levelId)
   const floor = sceneRegistry.nodes.get(levelId)
   if (!floor) throw new Error('The floor to look inside is not built yet. Try again.')
   for (const id of hiddenIds) {
@@ -508,6 +571,29 @@ export function interiorCutaway(levelId: string, restore: (callback: () => void)
   }
   restore(temporarilyShowPresentation(floor))
   restore(clipSceneFor(floor, [{ normal: [0, -1, 0], constant: cutHeight }], true))
+  const standing = levelGradeStanding(nodes, levelId)
+  if (standing === 'below-grade' || !camera) {
+    restore(temporarilyVeilGround(standing !== 'at-grade'))
+  } else {
+    restore(temporarilyVeilGround(false))
+    restore(temporarilyGroundWindowForCapture(camera, nodes, levelId))
+  }
+}
+
+/**
+ * The ground of an exterior picture, for one render: solid, whatever level the person is
+ * on — but a posed frame (an authored snapshot pose, or the caller's own perspective or
+ * orthographic view, which is how both agent lanes ask) decides its own ground window from
+ * its own camera, never inheriting the person's. An unposed frame (the person's viewport,
+ * the hero shot) makes no such decision: the window is the person's to hold.
+ */
+export function exteriorGroundForCapture(
+  restore: (callback: () => void) => void,
+  posed: boolean,
+  camera: THREE.Camera,
+) {
+  restore(temporarilyVeilGround(false))
+  if (posed) restore(temporarilyGroundWindowForCapture(camera, useScene.getState().nodes))
 }
 
 /**
@@ -670,21 +756,12 @@ export const ThumbnailGenerator = ({ onThumbnailCapture }: ThumbnailGeneratorPro
           // a supersampled frame renders at a multiple of the canvas' size into
           // the capture's own targets; the live canvas is never resized
           const canvasSize: [number, number] = [gl.domElement.width, gl.domElement.height]
+          const pose = ortho ?? perspective
           const limits = captureLimits(gl)
-          const scale = Math.max(
-            1,
-            Math.min(
-              supersample,
-              MAX_CAPTURE_EDGE / Math.max(canvasSize[0], canvasSize[1]),
-              Math.sqrt(limits.maxPixels / (canvasSize[0] * canvasSize[1])),
-            ),
-          )
-          const width = Math.round(canvasSize[0] * scale)
-          const height = Math.round(canvasSize[1] * scale)
+          const [width, height] = captureDimensions(canvasSize, event, limits.maxPixels)
           // a supersampled picture is encoded at the size it could render (the
           // caller asked for canvas × supersample, maybe past this GPU's limits)
           const encodeSize = supersample > 1 ? { w: width, h: height } : standardSize
-          const pose = ortho ?? perspective
           // a background tab draws no frames and (on the WebGL backend) never
           // finishes a readback: a sheet's capture says so at once
           if (pose && isTabHidden()) throw new Error(HIDDEN_TAB)
@@ -783,7 +860,7 @@ export const ThumbnailGenerator = ({ onThumbnailCapture }: ThumbnailGeneratorPro
             }
 
             pipeline?.applyEnvironment({
-              theme: useViewer.getState().sceneTheme,
+              theme: useViewer.getState().sceneAppearance,
               transparent,
               grade: useViewer.getState().shading === 'rendered',
               edges,
@@ -836,6 +913,10 @@ export const ThumbnailGenerator = ({ onThumbnailCapture }: ThumbnailGeneratorPro
             // the scene as the picture wants it, for one render; `restore` puts
             // every change back right after it
             const setUp = (restore: (callback: () => void) => void) => {
+              // A picture is read for its rooms, taken in the world's own light: the earth the
+              // person's view turns to under the ground (sky, fog, vignette, the sky's lights)
+              // is not in it.
+              restore(temporarilyWithoutAmbiance())
               if (snapLevels) {
                 const prevMode = useViewer.getState().levelMode
                 if (prevMode !== 'stacked') {
@@ -876,7 +957,7 @@ export const ThumbnailGenerator = ({ onThumbnailCapture }: ThumbnailGeneratorPro
                   thumbnailCamera.lookAt(hero.target[0], hero.target[1], hero.target[2])
                   thumbnailCamera.updateMatrixWorld()
                   pipeline?.applyEnvironment({
-                    theme: useViewer.getState().sceneTheme,
+                    theme: useViewer.getState().sceneAppearance,
                     transparent,
                     grade: useViewer.getState().shading === 'rendered',
                     edges,
@@ -904,9 +985,15 @@ export const ThumbnailGenerator = ({ onThumbnailCapture }: ThumbnailGeneratorPro
               // those meshes before either snapshot render path submits them,
               // and restore fog afterwards so the atmosphere never leaks in.
               restore(refreshIsolation(scene))
+              if (event.presentation) {
+                restore(presentLevelsForCapture(event.presentation))
+                cameraData.presentation = event.presentation
+              }
               if (interior) {
-                interiorCutaway(interior.levelId, restore)
+                interiorCutaway(interior.levelId, restore, thumbnailCamera)
                 restore(lightInterior(scene, thumbnailCamera))
+              } else if (snapLevels || pose || cameraPose) {
+                exteriorGroundForCapture(restore, Boolean(cameraPose || pose), thumbnailCamera)
               }
             }
             // The scene pass is a FRAME-updated node: it renders once per node
@@ -943,7 +1030,7 @@ export const ThumbnailGenerator = ({ onThumbnailCapture }: ThumbnailGeneratorPro
                   restore(() => thumbnailCamera.clearViewOffset())
                   thumbnailCamera.updateMatrixWorld()
                   pipeline.applyEnvironment({
-                    theme: useViewer.getState().sceneTheme,
+                    theme: useViewer.getState().sceneAppearance,
                     transparent,
                     grade: useViewer.getState().shading === 'rendered',
                     edges,
@@ -1008,7 +1095,8 @@ export const ThumbnailGenerator = ({ onThumbnailCapture }: ThumbnailGeneratorPro
               }
               // a sheet's picture (or a supersampled one) is never drawn into
               // the live canvas the viewport shows
-              if (pose || scale > 1) throw new Error('Snapshot renderer is not ready. Try again.')
+              if (pose || width !== canvasSize[0] || height !== canvasSize[1])
+                throw new Error('Snapshot renderer is not ready. Try again.')
               // Fallback: plain render directly to the canvas
               if (transparent) {
                 const clearColor = (
@@ -1140,7 +1228,7 @@ export const ThumbnailGenerator = ({ onThumbnailCapture }: ThumbnailGeneratorPro
             if (transparent || edgesOverride !== undefined || ortho !== undefined) {
               try {
                 pipelineRef.current?.applyEnvironment({
-                  theme: useViewer.getState().sceneTheme,
+                  theme: useViewer.getState().sceneAppearance,
                   transparent: false,
                   grade: useViewer.getState().shading === 'rendered',
                   edges: useViewer.getState().edges,
@@ -1158,39 +1246,25 @@ export const ThumbnailGenerator = ({ onThumbnailCapture }: ThumbnailGeneratorPro
     [gl, scene, getThree, orthoPipeline, advance, clock],
   )
 
-  // A sheet's run of captures sets the shared scene
-  // up for its pictures — the finished presentation, the ground hidden — so
-  // for the run the viewport keeps its last frame and the viewer shows the
-  // finished house whatever view the user was in; `active: false` puts the
-  // user's view back, then (a few commits later) the viewport resumes.
-  // `camera-controls:capture-session` `{ owner, active }`.
-  useEffect(() => {
-    const sessions = new Map<string, () => void>()
-    const end = (owner: string) => {
-      sessions.get(owner)?.()
-      sessions.delete(owner)
-    }
-    const onSession = (event: { owner?: string; active?: boolean }) => {
-      if (!event?.owner) return
-      end(event.owner)
-      if (!event.active) return
-      const releaseLiveFrame = holdLiveFrame(HOLD_MAX_MS)
-      const restorePresentation = presentFinished()
-      sessions.set(event.owner, () => {
-        restorePresentation()
-        setTimeout(releaseLiveFrame, SESSION_RESUME_MS)
-      })
-    }
-    const bus = emitter as unknown as {
-      on: (name: string, handler: typeof onSession) => void
-      off: (name: string, handler: typeof onSession) => void
-    }
-    bus.on('camera-controls:capture-session', onSession)
-    return () => {
-      bus.off('camera-controls:capture-session', onSession)
-      for (const owner of [...sessions.keys()]) end(owner)
-    }
-  }, [])
+  // A run of captures (a sheet's pictures, an agent's view) sets the shared
+  // scene up for its pictures — the finished presentation, the ground hidden —
+  // so while any run is on the viewport keeps its last frame and the viewer
+  // shows the finished house whatever view the user was in; the last run's
+  // end puts the user's view back, then (a few commits later) the viewport
+  // resumes. Runs overlap (a sheet and an agent's view): the user's view is
+  // the one before the first, never a run's finished presentation.
+  useEffect(
+    () =>
+      presentWhileCapturing(() => {
+        const releaseLiveFrame = holdLiveFrame(HOLD_MAX_MS)
+        const restorePresentation = presentFinished()
+        return () => {
+          restorePresentation()
+          setTimeout(releaseLiveFrame, SESSION_RESUME_MS)
+        }
+      }),
+    [],
+  )
 
   // Thumbnail request via emitter. Two call shapes:
   //  - user-driven capture: `{ projectId, captureMode, cropRegion }` — captures