@volter/blender-engine 0.1.8 → 0.1.10

package/browser/three/blender-runtime-lighting.ts

@@ -214,33 +214,37 @@ export function aimLight(light: THREE.Light, node: THREE.Object3D): void {
  * parented to the camera. `smooth` is the wrap factor; see
  * {@link ViewportLighting} for how it becomes three's lambert.
  *
- * `specular_color` is deliberately NOT carried: three's own BRDF produces the
- * material's highlight from the same light colour, and a second colour for it
- * would be a second specular model beside the one already shading the model.
+ * `specular` is each light's `specular_color`, which Blender's own shading function uses
+ * (`blender-workbench-material.ts`); the three.js light rig below does not.
  */
-const SOLID_LIGHTS: readonly {
+export const SOLID_LIGHTS: readonly {
   readonly direction: readonly [number, number, number];
   readonly diffuse: readonly [number, number, number];
+  readonly specular: readonly [number, number, number];
   readonly smooth: number;
 }[] = [
   {
     direction: [-0.352546, 0.170931, -0.920051],
     diffuse: [0.033103, 0.033103, 0.033103],
+    specular: [0.266761, 0.266761, 0.266761],
     smooth: 0.52662,
   },
   {
     direction: [-0.408163, 0.346939, 0.844415],
     diffuse: [0.521083, 0.538226, 0.538226],
+    specular: [0.59903, 0.59903, 0.59903],
     smooth: 0.0,
   },
   {
     direction: [0.521739, 0.826087, 0.212999],
     diffuse: [0.038403, 0.034357, 0.04953],
+    specular: [0.106102, 0.125981, 0.158523],
     smooth: 0.478261,
   },
   {
     direction: [0.624519, -0.562067, -0.542269],
     diffuse: [0.090838, 0.08208, 0.072255],
+    specular: [0.106535, 0.084771, 0.06608],
     smooth: 0.2,
   },
 ];
@@ -260,7 +264,7 @@ const SOLID_LIGHTS: readonly {
  * and AgX within 3, so the curve is NOT what row 1's 13-vs-30 spread was made
  * of and the stage keeps its own operator).
  *
- * THE ROUNDS, on a `model-editor create` scaffold driven through `vgai
+ * THE ROUNDS, on a `model-editor create` scaffold driven through `volter-model-editor
  * screenshot editor`, 30x30 means (std 0 — every patch inside one flat face)
  * of the factory cube's three visible faces against Blender 5.2's own frame,
  * (141,143,145) top / (129,131,131) left / (111,112,113) front:
@@ -282,6 +286,17 @@ const SOLID_LIGHTS: readonly {
  * no such coupling, nor a second colour per light to carry
  * `specular_color`. Closing that is a shader of our own, not a light rig.
  */
+/*
+ * SURFACES NO LONGER TAKE THIS RIG IN SOLID: they are drawn by Blender's own function
+ * (`blender-workbench-material.ts`), which reproduces Blender on the faces a single gain could
+ * not (a face square to the view: 158-160 against Blender's 161, where this rig gave 143). The rig
+ * still lights what that function does not draw (volume boxes). WHAT THE MEASUREMENT SHOWED about
+ * the rounds above: the three-face reference frames match Blender's function under the STANDARD
+ * view transform (function: 147/136/116 against 144/132/113; under AgX, 151/142/126), so they were
+ * made under Standard, and the gain was absorbing a view-transform difference, not a shading one.
+ * Blender's factory transform is AgX (`--factory-startup`: `view_transform` AgX), which the stage
+ * uses.
+ */
 const SOLID_STUDIO_GAIN = 0.69;
 
 /**

package/browser/three/blender-runtime-view.ts

@@ -32,6 +32,16 @@ import { type CompiledGraph, compileMaterialGraph, graphSeeThrough, materialGrap
 import {worldMedium, WorldVolumePass} from './blender-world-volume';
 import { BlenderTextureSamplers } from './blender-texture-samplers';
 import { WeightOverlay, weightsSchema } from './blender-runtime-weights';
+import { CursorOverlay, type CursorPlacement, cursorSchema } from './blender-runtime-cursor';
+import { emptySchema, ExtrasOverlay } from './blender-runtime-extras';
+import {
+  type BlenderCameraView,
+  blenderCameraView,
+  CAMERA_ZOOM,
+  cameraDataSchema,
+  panCameraView,
+} from './blender-runtime-camera-view';
+import { DEFAULT_VIEWPORT_DISPLAY, workbenchMaterial } from './blender-workbench-material';
 
 const scalar = z.number().finite();
 const point = z.tuple([scalar, scalar, scalar]);
@@ -255,7 +265,11 @@ function loadPngTexture(png: Uint8Array): { texture: THREE.Texture; ready: Promi
   // `three/src/textures/Texture.js:274` (0.180.0), "this property has no
   // effect when using `ImageBitmap`. You need to configure the flip on bitmap
   // creation instead."
-  const decoding = createImageBitmap(blob, { imageOrientation: 'flipY' })
+  //
+  // Its alpha is asked for here too: the browser's `default` premultiplies (Chrome's does), and
+  // every reader of this texture takes the file's own texels, straight unless the image says it
+  // stores them premultiplied, which the reader then undoes.
+  const decoding = createImageBitmap(blob, { imageOrientation: 'flipY', premultiplyAlpha: 'none' })
     .then((bitmap) => {
       if (disposed) {
         bitmap.close();
@@ -422,6 +436,12 @@ const materialSchema = z
      *  `blender-node-graph.ts`. The constants above still apply to every
      *  input the graph does not carry. */
     graph: materialGraphSchema.optional(),
+    /** The material's VIEWPORT DISPLAY (`Material.diffuse_color`, `roughness`, `metallic`), what
+     *  Blender's Solid shading colours it by (`blender-workbench-material.ts`). */
+    viewport: z
+      .object({ color: z.tuple([scalar, scalar, scalar, scalar]), roughness: scalar, metallic: scalar })
+      .strict()
+      .optional(),
   })
   .strict();
 /** THE FRAME CONTRACT, and the reason it is exported: the C++ export door
@@ -503,9 +523,84 @@ export const frameSchema = z
     /** The active object's active vertex group, per vertex
      *  (`blender-runtime-weights.ts`); null when nothing is painted. */
     weights: weightsSchema.nullable().default(null),
+    /** `Scene.cursor.matrix` (`blender-runtime-cursor.ts`); absent from an
+     *  engine that does not report it. */
+    cursor: cursorSchema.optional(),
+    /** What a camera view looks through (`session.py`): the scene's camera, the view layer's
+     *  cameras in order, and the render's shape with its pixel aspect. */
+    camera_view: z
+      .object({
+        scene_camera: z.string().nullable(),
+        view_layer_cameras: z.array(z.string()),
+        aspect: z.number().finite().positive(),
+      })
+      .optional(),
+    /** Each light datablock's clip start and cut-off distance (`blender-runtime-extras.ts`). */
+    light_distances: z.record(z.string(), z.tuple([z.number().finite(), z.number().finite()])).default({}),
+    /** Each empty's display type and size (`blender-runtime-extras.ts`). */
+    empties: z.record(z.string(), emptySchema).default({}),
+    /** The 3D View the file saved (`session.py` `_saved_view`), null when it holds none. */
+    view: z
+      .object({
+        location: z.tuple([z.number(), z.number(), z.number()]),
+        rotation: z.tuple([z.number(), z.number(), z.number(), z.number()]),
+        distance: z.number().finite(),
+        perspective: z.enum(['PERSP', 'ORTHO', 'CAMERA']),
+        lens: z.number().finite().positive().default(50),
+      })
+      .nullable()
+      .optional(),
+    /** The viewport's subject line as Blender composes it (`draw_selected_name`), less the
+     *  frame and its marker, with the scene's markers in list order. */
+    subject: z
+      .object({
+        frame: z.number().int(),
+        body: z.string(),
+        markers: z.array(z.tuple([z.number().int(), z.string()])),
+      })
+      .optional(),
+    /** `Scene.unit_settings`: the length system and scale the grid's step is named in. */
+    units: z
+      .object({ system: z.enum(['NONE', 'METRIC', 'IMPERIAL']), scale_length: z.number().finite() })
+      .optional(),
   })
   .strict();
 type Frame = z.infer<typeof frameSchema>;
+
+/** `BKE_scene_find_marker_name`: the list walked from both ends at once, the front one asked
+ *  first, so of several markers on one frame the answer is not simply the first. */
+function markerAt(markers: readonly (readonly [number, string])[], frame: number): string | null {
+  for (let front = 0, back = markers.length - 1; front < markers.length && back >= 0; front++, back--) {
+    if (markers[front]![0] === frame) return markers[front]![1];
+    if (front === back) break;
+    if (markers[back]![0] === frame) return markers[back]![1];
+  }
+  return null;
+}
+
+/** Blender's length units, smallest first, with their display names (`unit.cc`
+ *  `buMetricLenDef`, `buImperialLenDef`; nano- and picometres are compiled out there). */
+const LENGTH_UNITS: Readonly<Record<'METRIC' | 'IMPERIAL', readonly (readonly [number, string])[]>> = {
+  METRIC: [
+    [0.000001, 'Micrometers'],
+    [0.001, 'Millimeters'],
+    [0.01, 'Centimeters'],
+    [0.1, '10 Centimeters'],
+    [1, 'Meters'],
+    [10, '10 Meters'],
+    [100, '100 Meters'],
+    [1000, 'Kilometers'],
+  ],
+  IMPERIAL: [
+    [0.0000254, 'Thou'],
+    [0.0254, 'Inches'],
+    [0.3048, 'Feet'],
+    [0.9144, 'Yards'],
+    [20.1168, 'Chains'],
+    [201.168, 'Furlongs'],
+    [1609.344, 'Miles'],
+  ],
+};
 /** One render's two poses, in Blender's own (Z-up) frame. */
 export interface PhotographRecord {
   /** `scene.camera.matrix_world`, as `session.py::_photograph` sent it. */
@@ -539,7 +634,7 @@ export class BlenderRuntimeView {
    * visibility belongs to the viewport's Helpers menu rather than to this
    * presenter, and the door for that is the host's own — a document hands
    * each group to its stage's `setHelper(kind, object)`
-   * (`@vgai/editor-sdk/host`, `EditorHostStage`), which marks it
+   * (`@volter/editor-sdk/host`, `EditorHostStage`), which marks it
    * `editorHelper`, keeps it out of the hierarchy and the raycast, and turns
    * it on and off with the kind's checkbox. `blender-runtime.document.tsx`
    * is where they are handed over.
@@ -550,13 +645,34 @@ export class BlenderRuntimeView {
    */
   private readonly armatureOverlay = new ArmatureOverlay();
   private readonly weightOverlay = new WeightOverlay();
+  private readonly cursorOverlay = new CursorOverlay();
+  /** Blender's overlay extras: cameras, lights and empties (`blender-runtime-extras.ts`). */
+  private readonly extrasOverlay = new ExtrasOverlay();
   /** The two groups the stage is handed: the Helpers menu owns THEIR
    *  `visible`, and the inner group is what a RENDER stands down (an overlay
    *  is modeling chrome and never appears in a photograph — the same
    *  distinction `applyVisibility` draws for the scene's own objects). */
   private readonly armatureRoot = new THREE.Group();
   private readonly weightRoot = new THREE.Group();
+  private readonly cursorRoot = new THREE.Group();
+  private readonly cameraExtrasRoot = new THREE.Group();
+  private readonly lightExtrasRoot = new THREE.Group();
+  private readonly emptyExtrasRoot = new THREE.Group();
   private rendered = false;
+  /** The camera the VIEWPORT is held in render lighting through (Blender's Rendered shading),
+   *  or null when the viewport shows modeling lighting. See {@link holdRendered}. */
+  private heldRendered: (() => THREE.Camera) | null = null;
+  /** What the World was last composed for ({@link worldKeyFor}), or null when it is cleared:
+   *  composing rebuilds its textures, so it happens only when the key changes. */
+  private worldApplied: string | null = null;
+  /** The frame's World, as a key, taken once per frame. */
+  private worldKey = 'null';
+  /** A render photograph is being taken: the one state in which overlays stand down. */
+  private capturing = false;
+  /** The stage draws Blender's Solid: surfaces wear Blender's own shading function
+   *  (`blender-workbench-material.ts`) over their viewport display. */
+  private workbench = false;
+  private readonly workbenchMaterials = new Map<string, THREE.Material>();
   private readonly fallback = new THREE.MeshPhysicalMaterial({ color: 0xb9bec6, roughness: 0.72 });
   /** Base Color images, by image name -- ONE texture per image however many
    *  materials read it, and the cache OWNS it: a material points at one and
@@ -676,6 +792,114 @@ export class BlenderRuntimeView {
    * allows an active object that is not selected, and the Properties editor
    * follows the ACTIVE one while the outline follows the selected set.
    */
+  /**
+   * WHERE BLENDER OPENS THIS FILE: its saved 3D View in the stage's frame — the pivot, the
+   * direction from the pivot to the eye (the view's +Z, `view_rotation` turning view space into
+   * the world: RNA's inverse of `viewquat`), the screen's up (the view's +Y), the distance and
+   * the projection. A view saved through the scene camera opens in perspective along the same
+   * axis: looking through a camera is not a view this stage has. Null before a frame or when
+   * the file saved no 3D View.
+   */
+  savedView(): {
+    readonly target: readonly [number, number, number];
+    readonly direction: readonly [number, number, number];
+    readonly up: readonly [number, number, number];
+    readonly distance: number;
+    readonly projection: 'perspective' | 'orthographic';
+    readonly lens: number;
+  } | null {
+    const saved = this.frame?.view;
+    if (!saved) return null;
+    const [w, x, y, z] = saved.rotation;
+    const rotation = new THREE.Quaternion(x, y, z, w);
+    const target = new THREE.Vector3(...saved.location).applyMatrix4(this.root.matrix);
+    const axis = (v: THREE.Vector3) => v.applyQuaternion(rotation).applyMatrix4(this.root.matrix).normalize();
+    return {
+      target: target.toArray(),
+      direction: axis(new THREE.Vector3(0, 0, 1)).toArray(),
+      up: axis(new THREE.Vector3(0, 1, 0)).toArray(),
+      distance: saved.distance,
+      projection: saved.perspective === 'ORTHO' ? 'orthographic' : 'perspective',
+      lens: saved.lens,
+    };
+  }
+
+  /**
+   * THE CAMERA A CAMERA VIEW ENTERED NOW WOULD LOOK THROUGH, as `view_camera_exec` picks it:
+   * the scene's camera, else the active object when it is a camera, else the view layer's first
+   * camera; null when there is none (Blender's operator then does nothing).
+   */
+  cameraViewCamera(): string | null {
+    const frame = this.frame;
+    const view = frame?.camera_view;
+    if (!frame || !view) return null;
+    if (view.scene_camera !== null && frame.cameras[view.scene_camera]) return view.scene_camera;
+    if (frame.active !== null && frame.cameras[frame.active]) return frame.active;
+    return view.view_layer_cameras.find((name) => frame.cameras[name]) ?? null;
+  }
+
+  /** A pose in the stage's frame back in Blender's: the location and the rotation `(w, x, y, z)`. */
+  blenderPose(
+    position: readonly [number, number, number],
+    quaternion: readonly [number, number, number, number],
+  ): { readonly location: [number, number, number]; readonly rotation: [number, number, number, number] } {
+    const toBlender = new THREE.Matrix4().copy(this.root.matrix).invert();
+    const pose = new THREE.Matrix4()
+      .compose(new THREE.Vector3(...position), new THREE.Quaternion(...quaternion), new THREE.Vector3(1, 1, 1))
+      .premultiply(toBlender);
+    const location = new THREE.Vector3();
+    const rotation = new THREE.Quaternion();
+    pose.decompose(location, rotation, new THREE.Vector3());
+    return { location: location.toArray(), rotation: [rotation.w, rotation.x, rotation.y, rotation.z] };
+  }
+
+  /** The zoom a camera view opens at and keeps within (`blender-runtime-camera-view.ts`). */
+  readonly cameraViewZoom = CAMERA_ZOOM;
+  /** `view_move` in a camera view (`panCameraView`). */
+  readonly cameraViewPan = panCameraView;
+
+  /** `camera`'s view on a region (`blenderCameraView`), or null when it is not in the frame. */
+  cameraView(
+    camera: string,
+    region: { readonly width: number; readonly height: number },
+    zoom: number,
+    offset: readonly [number, number],
+  ): BlenderCameraView | null {
+    const frame = this.frame;
+    const data = cameraDataSchema.safeParse(frame?.cameras[camera]);
+    if (!frame?.camera_view || !data.success) return null;
+    return blenderCameraView(data.data, this.root.matrix, region, zoom, offset, frame.camera_view.aspect);
+  }
+
+  /** The viewport's subject line at `frame`, `(1) Collection | Cube`: the engine's body with
+   *  the frame before it and that frame's marker after it; `frame` null is the scene's own
+   *  `frame_current`. Null before a frame or from an engine that does not report it. */
+  subjectLine(playhead: number | null): string | null {
+    const subject = this.frame?.subject;
+    if (subject === undefined) return null;
+    const frame = playhead ?? subject.frame;
+    const marker = markerAt(subject.markers, frame);
+    return `(${frame})${subject.body}${marker === null ? '' : ` <${marker}>`}`;
+  }
+
+  /**
+   * THE GRID STEP'S NAME for an axis-aligned orthographic view drawn at `worldPerDevicePixel`,
+   * as `ED_view3d_grid_view_scale` picks it (`view3d_draw.cc`): the scene's length units from
+   * the smallest up, each scaled by `1 / scale_length`, and the first longer than six device
+   * pixels (`12 / (sizex * winmat[0][0])`) is named by its display name. A scene with no unit
+   * system names none. The overlay's grid Scale (`View3DOverlay.grid_scale`, `× 0.5`) has no
+   * home here and is taken as 1.
+   */
+  gridUnitName(worldPerDevicePixel: number): string | null {
+    const units = this.frame?.units;
+    if (units === undefined || units.system === 'NONE') return null;
+    const steps = LENGTH_UNITS[units.system];
+    const reach = 6 * worldPerDevicePixel;
+    const scale = 1 / (units.scale_length || 1);
+    const step = steps.find(([size]) => size * scale > reach) ?? steps[steps.length - 1]!;
+    return step[1];
+  }
+
   blenderSelection(): { readonly selected: readonly string[]; readonly active: string | null } {
     const frame = this.frame;
     if (frame === null) return { selected: [], active: null };
@@ -688,7 +912,7 @@ export class BlenderRuntimeView {
   /**
    * BLENDER'S MODE, PUBLISHED ON THE DOCUMENT'S OWN CONTEXT.
    *
-   * `vgai.stage.mode` (U6's context key, `editor-host-door.ts`'s `stage()`) had
+   * `volter.stage.mode` (U6's context key, `editor-host-door.ts`'s `stage()`) had
    * no reporter at all: Edit Mesh went with the mesh kit and the Model document
    * had no mode strip, so every `when` clause that reads it was answering
    * `null`. The engine HAS a mode — `bpy.context.mode`, and `Object.mode` on the
@@ -767,6 +991,10 @@ export class BlenderRuntimeView {
     for (const [group, overlay] of [
       [this.armatureRoot, this.armatureOverlay.group],
       [this.weightRoot, this.weightOverlay.group],
+      [this.cursorRoot, this.cursorOverlay.group],
+      [this.cameraExtrasRoot, this.extrasOverlay.cameras],
+      [this.lightExtrasRoot, this.extrasOverlay.lights],
+      [this.emptyExtrasRoot, this.extrasOverlay.empties],
     ] as const) {
       group.matrixAutoUpdate = false;
       group.matrix.copy(this.root.matrix);
@@ -775,6 +1003,13 @@ export class BlenderRuntimeView {
     }
     this.armatureRoot.name = 'BlenderBones';
     this.weightRoot.name = 'BlenderWeights';
+    this.cursorRoot.name = 'Blender3DCursor';
+    this.cameraExtrasRoot.name = 'BlenderCameraExtras';
+    // The extras are picked as the objects they draw (`userData.volterPicksAs` on each part).
+    for (const root of [this.cameraExtrasRoot, this.lightExtrasRoot, this.emptyExtrasRoot])
+      root.userData['volterPickable'] = true;
+    this.lightExtrasRoot.name = 'BlenderLightExtras';
+    this.emptyExtrasRoot.name = 'BlenderEmptyExtras';
   }
 
   /**
@@ -806,9 +1041,130 @@ export class BlenderRuntimeView {
     return [
       { kind: 'skeletons', object: this.armatureRoot },
       { kind: 'weights', object: this.weightRoot },
+      // Blender's overlay popover's "3D Cursor" (`View3DOverlay.show_cursor`).
+      { kind: 'cursor', object: this.cursorRoot },
+      // The overlay's extras, under the Helpers menu's own kinds (Blender's "Extras").
+      { kind: 'cameras', object: this.cameraExtrasRoot },
+      { kind: 'lights', object: this.lightExtrasRoot },
+      { kind: 'empties', object: this.emptyExtrasRoot },
     ];
   }
 
+  /**
+   * WHERE SHIFT+RIGHT-CLICK PUTS THE 3D CURSOR, in Blender's frame, or null
+   * when the click is not on the view the cursor was drawn in. The drawn
+   * cursor moves at once; the engine's next frame confirms it.
+   */
+  placeCursor(clientX: number, clientY: number, target: EventTarget | null): CursorPlacement | null {
+    const presented = new Set(this.objects.values());
+    const placement = this.cursorOverlay.placementAt(clientX, clientY, target, this.root, (object) =>
+      presented.has(object),
+    );
+    if (placement !== null) {
+      this.cursorOverlay.show(placement);
+      presenterChanged();
+    }
+    return placement;
+  }
+
+  /**
+   * BLENDER'S RENDERED SHADING: the viewport held in the lighting a render photographs with
+   * ({@link setRendered}) — the scene's own lights, its World behind and around the model,
+   * `hide_render` visibility and shadows — seen through `drawCamera()`, the camera the stage
+   * draws with (orthographic in an orthographic view). `null` returns the viewport to modeling.
+   * A render taken meanwhile ends back in this state rather than in modeling.
+   */
+  holdRendered(drawCamera: (() => THREE.Camera) | null): void {
+    if (drawCamera === this.heldRendered) return;
+    this.heldRendered = drawCamera;
+    if (this.capturing) return;
+    this.report(drawCamera === null ? this.applyRendered(false) : this.applyRendered(true, drawCamera()));
+  }
+
+  /**
+   * Re-apply the held render lighting if the draw camera or the World changed since it was
+   * last applied. Cheap when nothing did; the stage calls it every frame it draws.
+   */
+  refreshRendered(): void {
+    // A photograph in progress keeps its own state; it returns to this one when it ends.
+    if (this.heldRendered === null || this.capturing) return;
+    const camera = this.heldRendered();
+    if (this.worldKeyFor(camera) === this.worldApplied) return;
+    this.report(this.applyRendered(true, camera));
+  }
+
+  /**
+   * What the World is composed for: the camera, the frame's World, and for an orthographic
+   * camera its direction too, which an orthographic backdrop is sampled along
+   * (`WorldBackground.compose`).
+   */
+  private worldKeyFor(camera: THREE.Camera): string {
+    const ortho = (camera as THREE.OrthographicCamera).isOrthographicCamera;
+    // Coarse, so an orbit recomposes a handful of times rather than every frame.
+    const turn = ortho ? camera.getWorldDirection(new THREE.Vector3()).toArray().map((v) => v.toFixed(1)).join(',') : '';
+    return `${camera.uuid}:${turn}:${this.worldKey}`;
+  }
+
+  private report(work: Promise<void>): void {
+    void work.then(presenterChanged, (error: unknown) =>
+      // biome-ignore lint/suspicious/noConsole: the editor console captures console.error session-wide; this is the report channel.
+      console.error(`Rendered shading could not be applied: ${error instanceof Error ? error.message : String(error)}`),
+    );
+  }
+
+  /**
+   * BLENDER'S SOLID SHADING ON OR OFF: while on, every presented surface is drawn by Blender's
+   * Solid function over its material's viewport display; a render photograph, Material Preview
+   * and Rendered draw the authored materials.
+   */
+  setWorkbench(on: boolean): void {
+    if (on === this.workbench) return;
+    this.workbench = on;
+    this.applyWorkbench();
+    presenterChanged();
+  }
+
+  /** Each surface's material for the state: authored, or Solid's, derived from the frame every
+   *  time so a replaced node (the skin's) is never left wearing the other. */
+  private applyWorkbench(): void {
+    const solid = this.workbench && !this.rendered;
+    const used = new Set<string>();
+    for (const obj of this.frame?.objects ?? []) {
+      if (obj.mesh === null || obj.volume) continue;
+      const mesh = this.objects.get(obj.id) as THREE.Mesh | undefined;
+      if (!mesh?.isMesh) continue;
+      const slots: readonly (string | null)[] = obj.materials.length ? obj.materials : [null];
+      const shown = slots.map((id) => {
+        const authored = id === null ? this.fallback : (this.materials.get(id) ?? this.fallback);
+        return solid ? this.workbenchFor(id, authored.side, used) : authored;
+      });
+      mesh.material = obj.materials.length ? shown : shown[0]!;
+    }
+    // Released as soon as no surface wears it: a dragged viewport colour makes one per value.
+    for (const [key, material] of this.workbenchMaterials) {
+      if (used.has(key)) continue;
+      material.dispose();
+      this.workbenchMaterials.delete(key);
+    }
+  }
+
+  private workbenchFor(id: string | null, side: THREE.Side, used: Set<string>): THREE.Material {
+    const display = (id !== null ? this.frame?.materials[id]?.viewport : undefined) ?? DEFAULT_VIEWPORT_DISPLAY;
+    const key = `${display.color.join(',')}|${display.roughness}|${display.metallic}|${side}`;
+    used.add(key);
+    let material = this.workbenchMaterials.get(key);
+    if (!material) {
+      material = workbenchMaterial(display, side);
+      this.workbenchMaterials.set(key, material);
+    }
+    return material;
+  }
+
+  /** Whether the viewport is held in render lighting (Blender's Rendered shading). */
+  renderedHeld(): boolean {
+    return this.heldRendered !== null;
+  }
+
   /**
    * Light the model the way a RENDER is lit — by the scene's own lights —
    * rather than the way modeling is, by the studio key. `bpy.ops.render.render()`
@@ -816,6 +1172,14 @@ export class BlenderRuntimeView {
    * distinction Blender draws between its solid viewport and a render.
    */
   async setRendered(rendered: boolean, camera?: THREE.Camera): Promise<void> {
+    this.capturing = rendered;
+    // A render ends by returning to what the viewport holds, which in Rendered shading is the
+    // same render lighting, seen through the viewport's own camera again.
+    if (!rendered && this.heldRendered !== null) return this.applyRendered(true, this.heldRendered());
+    return this.applyRendered(rendered, camera);
+  }
+
+  private async applyRendered(rendered: boolean, camera?: THREE.Camera): Promise<void> {
     const extinction = (rendered ? worldMedium(this.frame?.world)?.extinction : null) ?? new THREE.Vector3();
     for (const material of [...this.materials.values(), this.fallback]) applyWorldExtinction(material, extinction);
     // An area light cannot be DRAWN until its lookup tables are uploaded, and a
@@ -827,9 +1191,13 @@ export class BlenderRuntimeView {
     this.lighting.setRendered(rendered);
     // The scene's world is what a render sees past the geometry AND its
     // ambient light; modeling keeps the document's own backdrop and fill.
-    if (rendered) this.world.apply(this.root, this.frame?.world ?? null, camera);
-    else this.world.clear();
+    // A photograph always composes its own; the viewport recomposes only when the key changed.
+    const worldKey = rendered && camera ? this.worldKeyFor(camera) : null;
+    if (!rendered) this.world.clear();
+    else if (this.capturing || worldKey !== this.worldApplied) this.world.apply(this.root, this.frame?.world ?? null, camera);
+    this.worldApplied = this.capturing ? null : worldKey;
     this.applyVisibility();
+    this.applyWorkbench();
     this.applyShadows(rendered, camera);
     // AFTER the applies, because they are what REGISTERS the work. Awaiting
     // first made every one of these a no-op on the first render: `apply` had
@@ -925,9 +1293,68 @@ export class BlenderRuntimeView {
       next.weights ? blenderMatrix(next.weights.object) : null,
     );
     if (weightWarning !== null) warnings.push(weightWarning);
+    this.cursorOverlay.apply(next.cursor);
+    this.applyExtras(next);
     return warnings;
   }
 
+  /** Pictures the extras asked for before they had decoded. */
+  private readonly awaitedImages = new Set<string>();
+  /** The camera a camera view is looking through, which the extras do not draw. */
+  private lookingThrough: string | null = null;
+
+  /** Told by the document which camera its stage's camera view is looking through. */
+  setCameraViewShowing(camera: string | null): void {
+    if (this.lookingThrough === camera) return;
+    this.lookingThrough = camera;
+    if (this.frame) this.applyExtras(this.frame);
+    presenterChanged();
+  }
+
+  private applyExtras(next: Frame): void {
+    const cameras: Record<string, z.infer<typeof cameraDataSchema>> = {};
+    for (const [name, data] of Object.entries(next.cameras)) {
+      const parsed = cameraDataSchema.safeParse(data);
+      if (parsed.success) cameras[name] = parsed.data;
+    }
+    this.extrasOverlay.apply({
+      lookingThrough: this.lookingThrough,
+      lightDistances: next.light_distances,
+      objects: next.objects.filter((object) => object.visible),
+      active: next.active,
+      cameras,
+      lights: next.lights,
+      empties: next.empties,
+      sceneCamera: next.camera_view?.scene_camera ?? null,
+      renderAspect: next.camera_view?.aspect ?? 1,
+      presented: (name) => {
+        const row = next.objects.find((object) => object.name === name);
+        return row ? (this.objects.get(row.id) ?? null) : null;
+      },
+      image: (name) => {
+        const held = this.textures.get(name);
+        if (!held) return null;
+        const bitmap = held.texture.image as { width?: number; height?: number } | null;
+        const width = held.width || bitmap?.width || 0;
+        const height = held.height || bitmap?.height || 0;
+        // A picture still decoding is drawn again when it has decoded.
+        if ((width === 0 || height === 0) && held.ready && !this.awaitedImages.has(name)) {
+          this.awaitedImages.add(name);
+          // A failed decode leaves the frame alone; the next frame asks again.
+          held.ready.then(
+            () => {
+              this.awaitedImages.delete(name);
+              if (this.frame) this.applyExtras(this.frame);
+              presenterChanged();
+            },
+            () => this.awaitedImages.delete(name),
+          );
+        }
+        return { texture: held.texture, width, height };
+      },
+    });
+  }
+
   private applyVisibility(): void {
     for (const obj of this.frame?.objects ?? []) {
       const object = this.objects.get(obj.id);
@@ -942,8 +1369,12 @@ export class BlenderRuntimeView {
     // is being looked at and stand down for the one capture. It is the INNER
     // group that yields, never the group the Helpers menu owns — the two facts
     // are separate and must not overwrite each other.
-    this.armatureOverlay.group.visible = !this.rendered;
-    this.weightOverlay.group.visible = !this.rendered;
+    // Rendered SHADING keeps them, as Blender's viewport does; only the photograph drops them.
+    this.armatureOverlay.group.visible = !this.capturing;
+    this.weightOverlay.group.visible = !this.capturing;
+    this.cursorOverlay.group.visible = !this.capturing;
+    for (const group of [this.extrasOverlay.cameras, this.extrasOverlay.lights, this.extrasOverlay.empties])
+      group.visible = !this.capturing;
   }
 
   applyFrame(input: unknown) {
@@ -1335,6 +1766,10 @@ export class BlenderRuntimeView {
         this.objects.set(obj.id, object);
       }
       object.name = obj.name;
+      // A camera, a light and an empty are drawn by the overlay's extras, selection colour and
+      // all (`blender-runtime-extras.ts`); the editor's own marks for them stand down.
+      if (obj.type === 'CAMERA' || obj.type === 'LIGHT' || obj.type === 'EMPTY') object.userData['volterOwnOverlay'] = true;
+      else delete object.userData['volterOwnOverlay'];
       object.matrixAutoUpdate = false;
       object.matrix.set(...(obj.matrix.flat() as Parameters<THREE.Matrix4['set']>));
       if (obj.parent) {
@@ -1367,6 +1802,9 @@ export class BlenderRuntimeView {
           previous.dispose();
         }
         if (light.parent !== object) object.add(light);
+        // Blender's overlay draws this light (`blender-runtime-extras.ts`); the editor's own
+        // light helper stands down for it.
+        light.userData['volterOwnOverlay'] = true;
         aimLight(light, object);
         this.lights.set(obj.light, light);
       }
@@ -1413,6 +1851,7 @@ export class BlenderRuntimeView {
     // last frame held 850 MB of main-thread heap this way, measured
     // 2026-09-13). Reuse checks compare the per-mesh signatures kept above.
     this.frame = { ...next, meshes: {}, volumes: {} };
+    this.worldKey = JSON.stringify(next.world ?? null);
     // THE OVERLAYS, after the graph stands: the weight drawing is laid over
     // the presented mesh's own geometry and the bones over the armature
     // OBJECT's Blender matrix, so both need this frame's objects in place.
@@ -1421,6 +1860,10 @@ export class BlenderRuntimeView {
       this.frame = { ...this.frame, warnings: [...this.frame.warnings, ...overlayWarnings] };
     // Visibility is read off the frame, so it is applied once the frame stands.
     this.applyVisibility();
+    this.applyWorkbench();
+    // Rendered shading follows the scene: the frame's new materials, lights and shadows, and its
+    // World when that changed.
+    if (this.heldRendered !== null && !this.capturing) this.report(this.applyRendered(true, this.heldRendered()));
     // The model moved: whoever is READING the engine (the Properties sections
     // through the RNA door) re-reads now, with the new graph already standing.
     for (const listener of [...this.frameListeners]) listener();
@@ -1647,6 +2090,10 @@ export class BlenderRuntimeView {
     this.world.dispose();
     this.armatureOverlay.dispose();
     this.weightOverlay.dispose();
+    this.cursorOverlay.dispose();
+    this.extrasOverlay.dispose();
+    for (const material of this.workbenchMaterials.values()) material.dispose();
+    this.workbenchMaterials.clear();
     this.frame = null;
     this.retiredSessions.clear();
     this.submittedMeshes.clear();