@volter/blender-engine 0.1.147 → 0.1.149

package/browser/three/blender-display-transform.ts

@@ -13,7 +13,8 @@ export interface BlenderDisplaySettings {
 
 export function blenderDisplaySettingsForRender(render: Pick<RenderRequest, 'toneMapping' | 'look' | 'exposure' | 'gamma'>): BlenderDisplaySettings {
   return {
-    transform: {none: 'Standard', filmic: 'Filmic', agx: 'AgX', neutral: 'Khronos PBR Neutral'}[render.toneMapping],
+    transform: {none: 'Standard', filmic: 'Filmic', agx: 'AgX', neutral: 'Khronos PBR Neutral',
+      aces13: 'ACES 1.3', aces20: 'ACES 2.0'}[render.toneMapping],
     look: render.look ?? 'None', exposure: render.exposure, gamma: render.gamma ?? 1,
   };
 }

package/browser/three/blender-frame-columns.ts

@@ -1,18 +1,10 @@
 /**
- * THE RUNTIME FRAME'S COLUMN CONTRACT — the typed arrays a `runtime_present`
- * ships and `drawArraysFromColumns` draws from.
+ * Typed columns transferred in a Blender frame and drawn by `drawArraysFromColumns`.
  *
- * WHERE IT CAME FROM, and why it lives here now. The columns are Blender's
- * own export arena (`@volter/blender-engine`'s `browser/session-frame.mts`, `columnsToTypedArrays`):
- * `{offset, length, dtype, count, stride}` descriptors into one transferable
- * buffer, decoded on this side into the arrays below. The presenter was typed
- * against the retired mesh kit's `mesh-store.ts` because that store happened to
- * hold the same layout — Blender's — and the two were in one package. They
- * are not the same contract: the kit's store is MODELING STATE it mutates
- * (selection, hide flags, creases, an allocator per attribute type), while
- * this is the READ-ONLY shape of one presented frame. This file is the second
- * half only, so `@volter/editor-blender` names no modeling package (WORK.md §Blender in
- * the tab is Blender, "The mesh kit retires", M1).
+ * The columns are Blender's own export arena (`@volter/blender-engine`'s
+ * `browser/session-frame.mts`, `columnsToTypedArrays`): `{offset, length, dtype, count, stride}`
+ * descriptors into one transferable buffer, decoded on this side into the arrays below. This is
+ * the read-only shape of one presented frame, independent of editable modeling state.
  *
  * Layout (Blender's own): positions `co` (3 per vertex); faces as CSR —
  * `faceStart` (nf+1) into `corner` (one vertex index per loop), a loop's edge

package/browser/three/blender-graph-material.ts

@@ -28,7 +28,7 @@ interface Binding {
   borrowedFrom?: Binding;
   borrowedSource?: THREE.MeshPhysicalMaterial;
   objectInfoUniforms?: {color: THREE.IUniform<THREE.Vector4>; indexRandom: THREE.IUniform<THREE.Vector2>; particleRandom: THREE.IUniform<number>};
-  palette?: {indices: Int32Array; sources: readonly THREE.MeshPhysicalMaterial[]};
+  palette?: true;
 }
 const bindings = new WeakMap<THREE.MeshPhysicalMaterial, Binding>();
 /** Graph structures whose program the GPU refused. A material whose graph is
@@ -88,7 +88,7 @@ export function bindPaletteGraph(material: THREE.MeshPhysicalMaterial, compiled:
       if (source[name]) values[`bp${index}_${name}`] = {value: source[name]};
     }
   }
-  bindings.set(material, {compiled, uniforms: values, ramps: [], channels: channelsFor(compiled, geometry), palette: {indices, sources}});
+  bindings.set(material, {compiled, uniforms: values, ramps: [], channels: channelsFor(compiled, geometry), palette: true});
   material.needsUpdate = true;
   return true;
 }
@@ -108,6 +108,15 @@ interface Pending {
   started: boolean;
 }
 const pendings = new WeakMap<THREE.MeshPhysicalMaterial, Pending>();
+
+/**
+ * For a viewport photograph, bind and compile pending graph materials on the capture draw.
+ * prepareDraw’s photograph flag selects this synchronous path.
+ */
+let photographing = false;
+export function photographGraphs(on: boolean): void {
+  photographing = on;
+}
 /** The proxy material a swapped-in program was compiled through, disposed
  *  once the material itself holds that program (its second draw after). */
 const retiring = new WeakMap<THREE.MeshPhysicalMaterial, {shadow: THREE.Material; draws: number}>();
@@ -324,7 +333,13 @@ export function bindGraphDraw(material: THREE.MeshPhysicalMaterial, geometry: TH
     retiring.delete(material);
   }
   const waiting = pendings.get(material);
-  if (waiting && !waiting.started) {
+  if (waiting && photographing) {
+    pendings.delete(material);
+    for (const ramp of bindings.get(material)?.ramps ?? []) ramp.dispose();
+    waiting.binding.channels = channelsFor(waiting.binding.compiled, geometry);
+    bindings.set(material, waiting.binding);
+    material.needsUpdate = true;
+  } else if (waiting && !waiting.started) {
     waiting.started = true;
     waiting.binding.channels = channelsFor(waiting.binding.compiled, geometry);
     const shadow = shadowOf(material);

package/browser/three/blender-node-graph.ts

@@ -212,20 +212,12 @@ function prop<T>(node: GraphNode, name: string): T {
   return node.props[name] as T;
 }
 
-/** What EEVEE's node library reads from EEVEE itself, transcribed: the
- *  shading globals `g_data` (`init_globals`: N faces the viewer, Ng the true
- *  normal), the object/view matrix accessors `transform_utils` calls, the
- *  object's negative-scale flag, `coordinate_incoming` (toward the eye; the
- *  view axis in orthographic), `derivative_scale_get` (1 at full resolution)
- *  and codegen's precise `dF_impl`, which the bump sub-function evaluates
- *  with its derivative flag set (`gpu_shader_codegen_lib.glsl`).
- *  BLENDER'S WORLD IS Z-UP: the presenter's model root maps it into three's
- *  Y-up world by the exact permutation (x, y, z) -> (x, z, -y)
- *  (`blender-runtime-view.ts`), so every world-space quantity handed to the
- *  library goes back through `blender_from_three`, and a normal the graph
- *  returns comes out through its transpose. A transmissive material's fragment shader already
- *  declares `modelMatrix` (three's `transmission_pars_fragment`), so the prelude yields it there:
- *  declared twice, the Stoneguard file's water failed to compile ("'modelMatrix' : redefinition"). */
+/**
+ * Provide the EEVEE node library’s shading globals, object and view accessors, scale flags,
+ * incoming coordinates and derivative helpers. Transform world quantities through the model root’s
+ * exact Z-up to Y-up permutation before passing them to Blender’s code, and transform returned
+ * normals back. Yield modelMatrix when three’s transmission shader already declares it.
+ */
 const EEVEE_GLOBALS = `
 #define GPU_FRAGMENT_SHADER
 #define FrontFacing gl_FrontFacing
@@ -837,8 +829,7 @@ class Compiler {
           uniform, node: key, name: image.name, revision: image.revision, extension,
           closest: interpolation === 'Closest',
           mipmap: projection !== 'SPHERE' && projection !== 'TUBE',
-          // EEVEE samples tiles only through a flat projection; any other
-          // treats the first tile as the image (#141776).
+          // EEVEE samples tiles only through flat projection; other projections sample the first tile.
           tiled: projection === 'FLAT' && node.props['image_tiled'] === true,
         });
         const tiled = this.s.images.at(-1)!.tiled;
@@ -866,13 +857,7 @@ class Compiler {
           if (extension === 'CLIP')
             body.push(`if (any(lessThan(${co}.xy, vec2(0.0))) || any(greaterThan(${co}.xy, vec2(1.0)))) { ${color} = vec4(0.0); ${alpha} = 0.0; }`);
         }
-        // node_shader_gpu_tex_image's Color output over the file's own texels (straight, or
-        // premultiplied for a PREMUL image, as Blender's GPU texture holds them): alpha cleared for
-        // ignored, packed or data alpha; otherwise straight when Alpha is used, so a factor does
-        // not multiply it in twice, and premultiplied when it is not. Measured in Blender 5.2's
-        // EEVEE: a straight red texel at alpha 0.5 emits 0.502 with Alpha unused, 1.0 with it used.
-        // A PREMUL sRGB image differs: the sampler decodes the premultiplied bytes, `decode(r·a)`,
-        // where Blender's texture holds `linear(r)·a`, so its partly transparent texels read darker.
+        // Match node_shader_gpu_tex_image alpha handling: ignore packed/data alpha; use straight colour when Alpha is linked and premultiplied colour otherwise. PREMUL sRGB decoding retains the file’s premultiplied-byte convention.
         const mode = prop<string>(node, 'image_alpha_mode');
         const alphaUsed = this.uses(key, 1);
         const c = outs([0]);
@@ -1007,16 +992,7 @@ class Compiler {
   }
 }
 
-/**
- * ONLY THE FUNCTIONS THE GRAPH REACHES, as Blender's codegen links only the
- * functions a material calls. A node's file holds every variant of it (each
- * Noise type and dimension, each Voronoi feature), and a program carrying all
- * of them measured ~155 KB of GLSL for a 30-line graph -- compile time the
- * viewport spent blocked. Everything that is not a plain function definition
- * (macros, which may generate or call functions; structs; constants) is kept,
- * and a function is kept when its name appears in kept text, to a fixpoint.
- * Overloads of a kept name are all kept.
- */
+/** Keep GLSL definitions reached from the graph to a name-reference fixpoint, retaining overloads together. Keep macros, structs and constants because they may define or call functions. */
 function shakeLibrary(library: string, root: string): string {
   type Chunk = {text: string; name: string | null};
   const chunks: Chunk[] = [];
@@ -1060,12 +1036,12 @@ function shakeLibrary(library: string, root: string): string {
   return chunks.filter(c => keep.has(c)).map(c => c.text).join('');
 }
 
-/** The varying a UV layer arrives in; `''` is the render UV. */
 /** The varying a graph reads Blender attribute `name` through. */
 export function attributeVarying(name: string): string {
   return `v${graphAttributeName(name)}`;
 }
 
+/** The varying a UV layer arrives in; `''` is the render UV. */
 export function uvVarying(name: string): string {
   return name === '' ? 'vBlenderUvRender' : `vBlenderUv_${[...name].map(c => c.charCodeAt(0).toString(16)).join('')}`;
 }

package/browser/three/blender-physical-material.ts

@@ -7,7 +7,6 @@ import {z} from 'zod';
 import {applyGraphShader, bindGraphDraw, bindPaletteGraph, borrowGraphDrawBinding, graphProgramKey, graphUvChannels, setGraphViewport} from './blender-graph-material';
 import type {CompiledGraph} from './blender-node-graph';
 import {bindNamedUvChannels} from './blender-texture-samplers';
-import {WORLD_VISIBILITY,copyWorldVisibility,worldVisibilityShader,worldVisibilityUniforms} from './blender-world-visibility';
 
 const scalar = z.number().finite();
 const color = z.tuple([scalar, scalar, scalar]);
@@ -56,7 +55,6 @@ function graphShadow(material: THREE.MeshPhysicalMaterial): THREE.MeshPhysicalMa
   // which `copy` replaces with the material's own (it leaves hooks alone).
   applyPhysicalMaterial(shadow);
   shadow.copy(material);
-  copyWorldVisibility(material,shadow);
   const values = uniforms.get(shadow)!;
   if (held) {
     values.blenderCoatIor.value = held.blenderCoatIor.value;
@@ -151,7 +149,6 @@ export function syncPhysicalDrawMaterial(source: THREE.Material, target?: THREE.
     return null;
   }
   copy.copy(source);
-  copyWorldVisibility(source,copy);
   const held = uniforms.get(source)!;
   const values = uniforms.get(copy)!;
   values.blenderCoatIor.value = held.blenderCoatIor.value;
@@ -163,16 +160,6 @@ export function syncPhysicalDrawMaterial(source: THREE.Material, target?: THREE.
   return copy;
 }
 
-/** A copy of a presented material that ONE object can wear and a script can recolour (Model
- *  Play's `tint`/`setOpacity`): the same hooks, physical values, maps and private uniforms,
- *  drawn from the material's constants -- `color`, `opacity`, `map`, `emissive` -- with no
- *  node graph, since a graph's Base Color and Alpha replace those constants in the shader.
- *  Null for a material that is not one of the presenter's. The caller owns and disposes it. */
-export function ownedSurfaceMaterial(source: THREE.Material): THREE.MeshPhysicalMaterial | null {
-  if (!(source instanceof THREE.MeshPhysicalMaterial) || !uniforms.has(source) || !materialDrawHooksSupported(source)) return null;
-  return graphShadow(source);
-}
-
 export function applyPhysicalMaterial(material: THREE.MeshPhysicalMaterial, input?: Physical,
   clips: {map?: boolean; roughness?: boolean; normal?: boolean} = {}): void {
   const data = input ?? defaults;
@@ -195,7 +182,7 @@ export function applyPhysicalMaterial(material: THREE.MeshPhysicalMaterial, inpu
       blenderWorldExtinction: {value: new THREE.Vector3()}};
     uniforms.set(material, values);
     const held = values;
-    material.customProgramCacheKey = () => `blender-principled-physical-v6${WORLD_VISIBILITY ? '-atlas' : ''}${graphProgramKey(material)}`;
+    material.customProgramCacheKey = () => `blender-principled-physical-v6${graphProgramKey(material)}`;
     material.onBeforeRender = (renderer, scene, camera, geometry, object) => {
       bindNamedUvChannels(material, geometry);
       bindGraphDraw(material, geometry, renderer, scene, camera, object, graphShadow);
@@ -213,16 +200,6 @@ export function applyPhysicalMaterial(material: THREE.MeshPhysicalMaterial, inpu
         .map(i => (i <= 3 ? `#ifndef USE_UV${i}\nattribute vec2 uv${i};\n#endif` : `attribute vec2 uv${i};`))
         .join('\n') + '\n' + shader.vertexShader;
       Object.assign(shader.uniforms, held);
-      // The sky-light atlas exists in the shader only while it is on: its three
-      // samplers would count against every material's sixteen (WORLD_VISIBILITY).
-      if (WORLD_VISIBILITY) {
-        worldVisibilityUniforms(material,shader.uniforms);
-        shader.vertexShader='varying vec3 blenderWorldPosition;\n'+shader.vertexShader;
-        shader.vertexShader=shader.vertexShader.replace('#include <worldpos_vertex>',
-          '#include <worldpos_vertex>\n#if defined(USE_ENVMAP) || defined(USE_SHADOWMAP) || defined(USE_TRANSMISSION)\nblenderWorldPosition=worldPosition.xyz;\n#else\nblenderWorldPosition=(modelMatrix*vec4(transformed,1.)).xyz;\n#endif');
-        shader.fragmentShader=shader.fragmentShader.replace('#include <envmap_physical_pars_fragment>',
-          '#include <envmap_physical_pars_fragment>\n'+worldVisibilityShader);
-      }
       shader.fragmentShader = `uniform float blenderCoatIor;
         uniform vec3 blenderWorldExtinction;
         vec3 blenderInfiniteTransmission() { return vec3(
@@ -267,13 +244,7 @@ export function applyPhysicalMaterial(material: THREE.MeshPhysicalMaterial, inpu
         .replace('rectAreaLight = rectAreaLights[ i ];',
           'rectAreaLight = rectAreaLights[ i ]; rectAreaLight.color *= exp(-blenderWorldExtinction * length(rectAreaLight.position-geometryPosition));')
         .replace('getAmbientLightIrradiance( ambientLightColor )', 'getAmbientLightIrradiance( ambientLightColor ) * blenderInfiniteTransmission()');
-      const visible = WORLD_VISIBILITY ? THREE.ShaderChunk.lights_fragment_maps
-        .replace('getIBLIrradiance( geometryNormal )',
-          'blenderWorldIrradiance( geometryNormal, getIBLIrradiance( geometryNormal ) )')
-        .replaceAll(/(getIBL(?:Radiance|AnisotropyRadiance)\([^;]+\))/g,
-          '$1 * blenderWorldReflectionVisibility(geometryViewDir,geometryNormal,material.roughness)')
-        : THREE.ShaderChunk.lights_fragment_maps;
-      const environment = visible
+      const environment = THREE.ShaderChunk.lights_fragment_maps
         .replaceAll(/(getIBL(?:Irradiance|Radiance|AnisotropyRadiance)\([^;]+\))/g, '$1 * blenderInfiniteTransmission()');
       shader.fragmentShader = shader.fragmentShader.replace('#include <lights_physical_fragment>', physical)
         .replace('#include <lights_fragment_begin>', lighting)

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

@@ -1,31 +1,4 @@
-/**
- * THE ARMATURE OVERLAY — Blender's bones, drawn in three.js over the engine's
- * own data (ARCHITECTURE-CORE §Blender north star, "Inspection parity, not
- * editing parity" and "The reference is Blender's SOURCE as well as its
- * frames"; WORK.md §Blender in the tab is Blender, "Inspection parity", I4).
- *
- * Blender's overlay ENGINE is never run, ported or recorded: what crosses is
- * the data its draw functions read — per bone a pose matrix, a length, a
- * parent, its hide/select/active flags — and this file is our own drawing of
- * the same shapes with Blender's own vertex tables and Blender's own theme
- * colours. Every metric below cites the file and constant it came from, at the
- * engine's pin (Blender 5.2.0, `fbe6228777e7`).
- *
- * WHAT IS DRAWN, and what is not. `display_type` OCTAHEDRAL and STICK are
- * drawn (`bone_draw_octa` / `bone_draw_line`, `overlay_armature.cc:1415-1500`).
- * BBONE, ENVELOPE and WIRE fall back to the octahedron and say so through a
- * frame warning — Blender's B-Bone needs the per-segment matrices
- * (`draw_bone_update_disp_matrix_bbone`, `:1186`) and its envelope needs the
- * head/tail radii, neither of which the door carries yet. A standing named
- * warning, never a silent degrade.
- *
- * EDIT MODE IS NOT DRAWN EITHER, for a reason worth stating: in edit mode
- * Blender draws the EDIT bones (`ED_armature_ebone_to_mat4`), which are a
- * different set of matrices from `pose.bones`, and drawing the pose there
- * would be a confident picture of the wrong thing. The door reports the mode;
- * an armature in EDIT mode draws its pose with the object-mode colours and the
- * frame carries the warning.
- */
+
 import * as THREE from 'three';
 import { LineMaterial } from 'three/addons/lines/LineMaterial.js';
 import { LineSegments2 } from 'three/addons/lines/LineSegments2.js';
@@ -51,7 +24,7 @@ export const boneSchema = z
     active: z.boolean(),
     lockedWeight: z.boolean(),
     /** `Bone.matrix_local`, the rest matrix in the armature's space. */
-    rest: matrixSchema.optional(),
+    rest: matrixSchema,
     /** The channels' own values: what a channel no action animates keeps. */
     channels: z.object({
       mode: z.string(),
@@ -60,7 +33,7 @@ export const boneSchema = z
       rotation_euler: z.array(scalar).length(3),
       rotation_axis_angle: z.array(scalar).length(4),
       scale: z.array(scalar).length(3),
-    }).strict().optional(),
+    }).strict(),
     /** Parenting flags that are not Blender's default, by name. */
     inherit: z.array(z.string()).optional(),
     /** The bone's constraint stack, in order. */
@@ -114,7 +87,7 @@ export const armatureAnimationSchema = z.object({
   blendType: z.string(),
   extrapolation: z.string(),
   /** The NLA is in tweak mode (`use_tweak_mode`), which the presenter does not play. */
-  tweak: z.boolean().optional(),
+  tweak: z.boolean(),
   tracks: z.array(z.object({ name: z.string(), mute: z.boolean(), solo: z.boolean(), strips: z.array(nlaStripSchema) }).strict()),
   /** Bones whose channels a driver sets. */
   drivers: z.array(z.string()).optional(),
@@ -130,7 +103,7 @@ export const armatureSchema = z
     mode: z.string(),
     bones: z.array(boneSchema),
     /** `animation_data.action`, the action it plays (`session.py` `_armatures`). */
-    action: z.string().nullable().optional(),
+    action: z.string().nullable(),
     animation: armatureAnimationSchema.optional(),
   })
   .strict();
@@ -265,18 +238,7 @@ function wireThickness(bone: Bone): number {
  *  (`overlay_shape.cc:368-375`): a 10 CSS px bar at UI scale 1. */
 const STICK_WIDTH = 10;
 
-/**
- * The CORE of that bar, in the bone's own colour.
- *
- * Blender's stick fragment is a gradient, not two bands:
- * `fac = smoothstep(1.0, 0.2, color_fac)` then `mix(inner, wire, fac)`
- * (`overlay_armature_stick_frag.glsl:13-14`), where `color_fac` runs 1 at the
- * centre line to 0 at either edge. The blend passes 50% at `color_fac` 0.6,
- * i.e. 0.4 of the half-width — so the band that is more bone than wire is
- * 0.4 × 10 = 4 px. `LineMaterial` draws a flat width, so the bar is two
- * lines, 10 px of wire colour with a 4 px core, and that 4 is this
- * measurement rather than a choice.
- */
+/** Bone-colour core spans 0.4 × STICK_WIDTH, matching the midpoint of Blender's stick-fragment gradient. */
 const STICK_CORE_WIDTH = 4;
 
 /**
@@ -300,22 +262,7 @@ const BONE_SOLID_VERTEX = /* glsl */ `
     gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
   }
 `;
-/**
- * THE OUTPUT TRANSFORM HAS TO BE ASKED FOR, and forgetting it is what the walk
- * caught: a `ShaderMaterial` writes `gl_FragColor` RAW. three's own materials
- * end with `#include <colorspace_fragment>`, which is what converts the linear
- * working value to the renderer's `outputColorSpace`; without it the theme's
- * `bone_solid` (#b2b2b2, linear 0.44) reached the framebuffer as 0.44 and the
- * bones photographed at byte 112 against Blender's 178 — visibly dark grey
- * where Blender's are light. Tone mapping is deliberately NOT included: an
- * overlay is drawn after the view transform in Blender and is not a
- * scene-referred value.
- *
- * ONLY THE `_fragment` HALF: three PREPENDS `colorspace_pars_fragment` to every
- * `ShaderMaterial` already, so including it here declared `LinearTransferOETF`,
- * `sRGBTransferEOTF` and `sRGBTransferOETF` twice and the whole program refused
- * to compile ("function already has a body", measured live in `cyclotron console`).
- */
+/** Apply colorspace_fragment to overlay colours without tone mapping. ShaderMaterial already supplies colorspace_pars_fragment. */
 const BONE_SOLID_FRAGMENT = /* glsl */ `
   varying vec3 vColor;
   void main() {

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

@@ -1,6 +1,5 @@
-/** The runtime frame's INCREMENTAL contract — the one thing the worker that
- * builds a frame (`runtime_present`) and the presenter that applies it
- * (`blender-runtime-view.ts`) both have to agree on.
+/** Incremental Blender frames transferred by the worker and applied by
+ * `blender-runtime-view.ts`.
  *
  * A present ships the columns of the meshes whose store revision moved since
  * the last frame that session sent, and a bare REFERENCE for the rest; the
@@ -9,31 +8,18 @@
  * a marker string.
  */
 
-/** A mesh the presenter is expected to already hold, named by the store and
- *  revision it was last sent as. `store`/`revision` are diagnostic — they are
- *  what a stale-geometry report would quote — and `unchanged` is the
- *  discriminator. */
-export interface UnchangedMesh {
-  store: number;
-  revision: number;
-  unchanged: true;
-}
-
 /** The presenter's refusal when a reference names geometry it does not hold.
  *
- * It is a MARKER IN THE MESSAGE rather than an error subclass because the
- * refusal crosses a `Function`-constructed page eval and an SSE channel before
- * the worker sees it, and only the message survives that trip. The worker
- * answers by re-sending the whole frame in full; a page that reloaded under a
- * still-running Python session is the case this exists for. */
+ * The message marker survives the worker response boundary. The worker
+ * answers by re-sending the whole frame in full, restoring geometry after
+ * the presenter has lost its retained frame. */
 export const UNKNOWN_GEOMETRY = 'RUNTIME_FRAME_UNKNOWN_GEOMETRY';
 
 /** The presenter's refusal when a material names a PICTURE it does not hold.
  *
  * The same contract one level up from the meshes: a frame carries an image's
- * bytes once per `(name, revision)` and after that its materials name it
- * (`blender/python/runtime_session.py`, `_stage_images`). The worker cannot
- * answer this one — the bytes are Python's to re-stage — so unlike
- * `UNKNOWN_GEOMETRY` it travels all the way back, and `RuntimeSession.present`
- * drops its record and presents the frame again in full. */
+ * bytes once per `(name, revision)` and after that its materials name it.
+ * The worker cannot supply Python's image bytes, so the refusal reaches
+ * `browser/session.py`'s `Session`, which clears its image-carry record and
+ * retries the present with the image data. */
 export const UNKNOWN_IMAGE = 'RUNTIME_FRAME_UNKNOWN_IMAGE';

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

@@ -8,12 +8,6 @@
  * crosses as transferable buffers, never as nested number arrays. The
  * boundary JSON door (`drawRuntimeGeometry`) remains for a frame that
  * arrives as JSON.
- *
- * A drawn geometry carried a `userData.authoredUv` mark until 2026-09-19.
- * MEASURED when this file became `@volter/editor-blender`'s: its only readers were the
- * kit's own `bmesh.ts` and `unwrap.ts`, and a presented frame's geometry is
- * never handed to the kit — it is the Model document's scene. Data with no
- * reader is not authored, so the mark is gone.
  */
 import * as THREE from 'three';
 import { customCornerNormals, type Normal } from './blender-corner-normals';
@@ -83,10 +77,10 @@ interface DrawView {
   sharp: Iterable<[number, number]>;
   /** A corner's UV, or undefined when the mesh has no map. */
   uv: ((corner: number) => [number, number]) | null;
-  uvLayers?: {name: string; read: (corner: number) => [number, number]}[];
+  uvLayers: {name: string; read: (corner: number) => [number, number]}[];
   /** A corner's value of each generic attribute layer, by vertex, corner and
    *  face; `corner` and `face` are undefined for a loose vertex. */
-  attributeLayers?: {name: string; domain: string;
+  attributeLayers: {name: string; domain: string;
     read: (vertex: number, corner: number | undefined, face: number | undefined) => ArrayLike<number>}[];
 }
 
@@ -115,7 +109,7 @@ function attributeFloat4(type: string, values: ArrayLike<number>, i: number): [n
 function graphAttributeLayers(
   attributes: readonly {name: string; domain: string; type: string; data: ArrayLike<unknown>}[],
   flat: (data: ArrayLike<unknown>, type: string) => ArrayLike<number>,
-): NonNullable<DrawView['attributeLayers']> {
+): DrawView['attributeLayers'] {
   return attributes
     .filter(a => GRAPH_ATTRIBUTE_TYPES.has(a.type) && a.domain !== 'EDGE' && !a.name.startsWith('.')
       && a.name !== 'position' && a.name !== 'custom_normal' && !(a.type === 'FLOAT2' && a.domain === 'CORNER'))
@@ -205,8 +199,8 @@ function drawCore(view: DrawView): Omit<DrawArrays, 'hash'> {
   const positions = new Float32Array(capacity * 3),
     texcoords = new Float32Array(capacity * 2);
   const sourceVertex = new Uint32Array(capacity);
-  const uvLayers = (view.uvLayers ?? []).map(layer => ({...layer, data: new Float32Array(capacity * 2)}));
-  const attributeLayers = (view.attributeLayers ?? []).map(layer => ({...layer, data: new Float32Array(capacity * 4)}));
+  const uvLayers = view.uvLayers.map(layer => ({...layer, data: new Float32Array(capacity * 2)}));
+  const attributeLayers = view.attributeLayers.map(layer => ({...layer, data: new Float32Array(capacity * 4)}));
   const orco = view.orco ? new Float32Array(capacity * 3) : null;
   const indices = new Uint32Array(capacity),
     shared = new Map<string, number>();
@@ -310,15 +304,23 @@ export function geometryFromDrawArrays(
     geometry.addGroup(group.start, group.count, group.materialIndex);
   if (arrays.normals) geometry.setAttribute('normal', new THREE.BufferAttribute(arrays.normals, 3));
   else geometry.computeVertexNormals();
-  // The draw's own vertex map (see `DrawArrays.sourceVertex`). Optional here
-  // because a frame may arrive ALREADY DRAWN from the worker, whose buffers
-  // predate this attribute; a reader that needs it says so by name rather than
-  // colouring by a guessed index.
+  // The draw’s source-vertex map. A reader that needs the map refuses an absent attribute instead of substituting an index.
   if (arrays.sourceVertex)
     geometry.setAttribute('blenderVertex', new THREE.BufferAttribute(arrays.sourceVertex, 1));
   return geometry;
 }
 
+/** Choose a mesh’s render UV, then active UV, then first UV; return -1 when none exist. Only CORNER FLOAT2 layers qualify, so stale names and generic attributes are skipped. */
+export function renderMapIndex(maps: readonly { name: string }[], renderUv: string | null | undefined,
+  activeUv: string | null | undefined): number {
+  for (const name of [renderUv, activeUv]) {
+    if (!name) continue;
+    const index = maps.findIndex((map) => map.name === name);
+    if (index >= 0) return index;
+  }
+  return maps.length ? 0 : -1;
+}
+
 /** Blender already supplied corner normals and triangulation. Read those
  * columns directly: no polygon triangulation, adjacency graph, vector objects
  * or stringified floating-point keys. Two passes size final buffers exactly. */
@@ -326,9 +328,7 @@ function drawNativeColumns(c: MeshColumns, hash: string): DrawArrays {
   const triangles = c.cornerTri!, normal = c.cornerNormal!;
   const nv = c.co.length / 3, nc = c.corner.length, nf = c.faceStart.length - 1;
   const maps = c.attributes.filter(a => a.type === 'FLOAT2' && a.domain === 'CORNER');
-  const mapName = c.renderUv ?? c.activeUv ?? maps[0]?.name;
-  const activeMap = maps.findIndex(a => a.name === mapName);
-  if (mapName && activeMap < 0) throw new Error(`Runtime UV map ${mapName} is missing`);
+  const activeMap = renderMapIndex(maps, c.renderUv, c.activeUv);
   const attributes = graphAttributeLayers(c.attributes, data => data as ArrayLike<number>);
   const width = 3 + maps.length * 2 + attributes.length * 4;
   const scratch = new Float32Array(width), comparison = new Float32Array(width);
@@ -428,9 +428,7 @@ export function drawArraysFromColumns(c: MeshColumns, hash: string): DrawArrays
   if (c.cornerTri && c.cornerNormal) return withIslandRandom(drawNativeColumns(c, hash),c.co.length/3,storedMeshEdges(c.edge));
   const nv = c.co.length / 3;
   const maps = c.attributes.filter((a) => a.type === 'FLOAT2' && a.domain === 'CORNER');
-  const mapName = c.renderUv ?? c.activeUv ?? maps[0]?.name;
-  const map = maps.find((a) => a.name === mapName);
-  if (mapName && !map) throw new Error(`Runtime UV map ${mapName} is missing`);
+  const map = maps[renderMapIndex(maps, c.renderUv, c.activeUv)];
   const uvData = map ? (map.data as Float32Array) : null;
   const ne = c.edge.length / 2;
   const edges: [number, number][] = new Array(ne);
@@ -536,9 +534,7 @@ export function drawRuntimeGeometry(data: MeshData): THREE.BufferGeometry {
         `Runtime attribute ${attribute.name} has ${attribute.data.length} values for ${counts[attribute.domain]} ${attribute.domain} elements`,
       );
   const maps = (data.attributes ?? []).filter((a) => a.type === 'FLOAT2' && a.domain === 'CORNER');
-  const mapName = data.render_uv ?? data.active_uv ?? maps[0]?.name;
-  const map = maps.find((a) => a.name === mapName);
-  if (mapName && !map) throw new Error(`Runtime UV map ${mapName} is missing`);
+  const map = maps[renderMapIndex(maps, data.render_uv, data.active_uv)];
   const uv = map?.data as [number, number][] | undefined;
   const view: DrawView = {
     vertexCount: vertices.length,
@@ -560,8 +556,8 @@ export function drawRuntimeGeometry(data: MeshData): THREE.BufferGeometry {
     attributeLayers: graphAttributeLayers(data.attributes ?? [],
       values => (Array.from(values) as (number | number[])[]).flat()),
   };
-  // Native frames always supply stored edges. Legacy JSON without that
-  // order retains its old unsupported zero input rather than guessing IDs.
+  // Native frames always supply stored edges. A JSON frame without that
+  // order keeps an unsupported zero input rather than guessing IDs.
   const arrays=drawCore(view);
   return geometryFromDrawArrays(view.edges?withIslandRandom(arrays,vertices.length,view.edges):arrays);
 }