workinf_Blender_Wasm/docs/web/depsgraph-evaluation-contract.md

Blender Depsgraph Evaluation Contract

evaluateDepsgraph is an explicit WebEngine Worker command intended to evaluate the currently opened .blend with Blender 5.2's native loader and dependency graph. It does not reinterpret the SceneIR modifier metadata in TypeScript.

Current status: the native module executes Blender 5.2 full loading, view-layer synchronization, graph build, tagged update and frame evaluation in the headless WASM runtime for the declared fixtures. The wasm32 DNA bridge recursively aligns 64-bit members, and the Web ID registry includes embedded NodeTree, Camera, Light, Lattice and Grease Pencil data. The command returns the native BlenderDepsgraph/EVALUATED report; loader, graph or schema failures remain structured errors and never become Three.js approximations.

The native evaluation sequence is:

1. Initialize Blender's headless data runtime once per WASM module.
2. Load the saved buffer with BLO_read_from_memory.
3. Synchronize view layers, build the viewport Depsgraph and apply tagged and frame evaluation.
4. Return modifier identity/status for every evaluated object and final mesh vertex positions and triangle indices for every mesh object, keyed by stable SceneIR object/Mesh IDs. Each mesh also returns its original modifier stack in order. Entries carry Blender's persistent UID, registered type name, viewport/render/edit/cage flags, target object IDs, the previous-stack and cross-object dependency edges, and an explicit status: EVALUATED, DISABLED or BLOCKED. Blocked entries carry a stable errorCode, human-readable error and actionable suggestion; they are never silently treated as successful evaluation.

The result is validated by parseDepsgraphEvaluation. Every mesh must have a 16-value world matrix, exactly vertexCount * 3 position values and exactly triangleCount * 3 in-range integer indices. A load, initialization or graph failure returns the existing structured WebEngine error; it must never fall back to a Three.js approximation.

The rigged fixture is checked against a golden written by desktop Blender 5.2. The golden disables the fixture's Preview Decimate modifier solely to isolate shape-key plus armature deformation. The current Web deformation evaluator already compares final positions under the declared maximum and RMS error budget. Native WASM Depsgraph evaluation must pass the same comparison and repeated memory-safety runs before this contract is considered complete.

The offline regression npm --prefix web run test:depsgraph checks this report schema for all declared fixtures and verifies the rigged stack order Armature -> Decimate, its stack edge, the Armature target object edge and Blender's structured "requires more than 3 input faces" Decimate block. Drivers and constraints remain separate matrix entries. Geometry Nodes now has two explicitly bounded native closures described below; it is not a claim of general node-graph evaluation.

The category fixture suite adds Generate, Deform, Physics, Geometry Nodes and Grease Pencil desktop goldens. Twenty-four category types execute native Web implementations and compare topology/positions, including serialized Mesh/Surface Deform bind caches and frame-6 Build/Wave output. Subdivision uses the locally linked OpenSubdiv 3.7.0 CPU evaluator; exact Boolean uses local GMP 6.3.0; Curve evaluates through Blender's native modifier after registering the Curves ID type. Their category goldens now pass in wasm32.

Geometry Nodes is intentionally narrower than Blender's full lazy-function runtime. The evaluator accepts a three-node graph containing either Transform Geometry in Components mode with literal defaults, or Set Position with an unlinked constant selection/offset. Both use Blender mesh APIs and match desktop goldens. Other graph shapes produce BLENDER_MODIFIER_ERROR; simulation/bake state produces GEOMETRY_NODES_SIMULATION_UNAVAILABLE and preserves input geometry.

Other unsupported implementations retain their original DNA type code through a disabled placeholder and report UNSUPPORTED_MODIFIER_TYPE; they are not rewritten to None. Unsupported resource closures are validated before their implementation can mutate geometry or enter an unavailable runtime path.