Add material diagnostics and realistic surface workflows

Author: SamG-Coder

schemas/tools-v1.schema.json

@@ -650,7 +650,9 @@
             "type": { "const": "projectUvs" },
             "layer": { "$ref": "#/$defs/geometryLayerName" },
             "cornerIndices": { "$ref": "#/$defs/geometryCornerSelection" },
-            "axis": { "enum": ["xy", "xz", "yz"] },
+            "projection": { "enum": ["planar", "cylindrical", "spherical"] },
+            "axis": { "enum": ["xy", "xz", "yz", "x", "y", "z"] },
+            "center": { "$ref": "#/$defs/geometryVec3" },
             "scale": {
               "oneOf": [
                 { "type": "number", "minimum": -1000000, "maximum": 1000000 },
@@ -1263,6 +1265,7 @@
         "protocolVersion": { "$ref": "#/$defs/protocolVersion" }, "sessionId": { "$ref": "#/$defs/sessionId" }, "projectId": { "$ref": "#/$defs/id" },
         "baseRevision": { "$ref": "#/$defs/revision" }, "idempotencyKey": { "$ref": "#/$defs/idempotencyKey" }, "label": { "$ref": "#/$defs/label" },
         "dryRun": { "type": "boolean" },
+        "previewEvidence": { "type": "object", "additionalProperties": false, "properties": { "width": { "type": "integer", "minimum": 16, "maximum": 1920 }, "height": { "type": "integer", "minimum": 16, "maximum": 1080 } } },
         "operations": { "type": "array", "minItems": 1, "maxItems": 128, "items": { "$ref": "#/$defs/operation" } }
       }
     },
@@ -1281,7 +1284,7 @@
         "frame": { "type": "object", "additionalProperties": false, "anyOf": [{ "required": ["targetIds"] }, { "required": ["bounds"] }], "properties": { "targetIds": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/$defs/id" } }, "bounds": { "$ref": "#/$defs/bounds3" } } },
         "timelineFrame": { "type": "integer", "minimum": -1000000, "maximum": 1000000 },
         "width": { "type": "integer", "minimum": 16, "maximum": 1920 }, "height": { "type": "integer", "minimum": 16, "maximum": 1080 },
-        "passes": { "type": "array", "minItems": 1, "maxItems": 2, "items": { "enum": ["beauty", "objectId"] } },
+        "passes": { "type": "array", "minItems": 1, "maxItems": 7, "items": { "enum": ["beauty", "raster", "objectId", "albedo", "roughness", "normal", "uv"] } },
         "renderer": { "const": "webgpu" }
       }
     },
@@ -1300,8 +1303,15 @@
     },
     "job": {
       "type": "object", "additionalProperties": false,
+      "required": ["action", "projectId", "graphId", "textureId", "output", "resolution", "baseRevision", "idempotencyKey", "label"],
       "properties": {
-        "protocolVersion": { "$ref": "#/$defs/protocolVersion" }, "sessionId": { "$ref": "#/$defs/sessionId" }
+        "protocolVersion": { "$ref": "#/$defs/protocolVersion" }, "sessionId": { "$ref": "#/$defs/sessionId" },
+        "action": { "const": "textureBake" },
+        "projectId": { "$ref": "#/$defs/id" }, "graphId": { "$ref": "#/$defs/id" }, "textureId": { "$ref": "#/$defs/id" },
+        "output": { "enum": ["albedo", "roughness", "normal"] },
+        "resolution": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "integer", "minimum": 1, "maximum": 512 } },
+        "name": { "type": "string", "minLength": 1, "maxLength": 160 },
+        "baseRevision": { "$ref": "#/$defs/revision" }, "idempotencyKey": { "$ref": "#/$defs/idempotencyKey" }, "label": { "$ref": "#/$defs/label" }
       }
     },
     "project": {

src/blender/catalog.mjs

@@ -155,20 +155,20 @@ const entries = [
     canonicalRepresentation: 'Entity.transform contains local position, Euler rotation in radians, and non-zero scale vectors.',
     mcpWorkflow: ['three_studio_apply: entity.patch|entity.transformMany', 'three_studio_apply: entity.reparent|entity.group|entity.ungroup'],
     runtimeNotes: 'The compiler applies local TRS through the canonical parent hierarchy. Grouping rejects non-representable shear instead of silently drifting world placement.',
-    supportedSubset: ['local translation', 'Euler rotation', 'scale', 'uniform guarded delta transforms', 'parent transforms', 'world-preserving group and ungroup', 'exact numeric layout'],
-    unsupportedSubset: ['quaternions', 'per-object heterogeneous bulk transforms', 'parent inverse document field', 'apply/freeze transforms', 'transform orientations', 'snapping and proportional editing', 'TRS representation of shear'],
+    supportedSubset: ['local translation', 'Euler rotation', 'scale', 'uniform guarded delta transforms', 'parent transforms', 'world-preserving group and ungroup', 'exact numeric layout', 'bounded proportional vertex movement with five falloffs'],
+    unsupportedSubset: ['quaternions', 'per-object heterogeneous bulk transforms', 'parent inverse document field', 'apply/freeze transforms', 'transform orientations', 'snapping', 'TRS representation of shear'],
     officialUrls: ['https://docs.blender.org/manual/en/latest/scene_layout/object/editing/transform/introduction.html'],
   }),
   capability({
     id: 'blender/mesh-editing',
     domain: 'meshEditing',
     label: 'Mesh Editing',
     status: 'partial',
-    canonicalRepresentation: 'Geometry resource recipes or explicit indexed meshes with positions, normals, UVs, colors, and indices.',
-    mcpWorkflow: ['three_studio_apply: resource.create|resource.patch', 'three_studio_apply: entity.create with components.mesh'],
-    runtimeNotes: 'Primitive recipes and complete explicit buffers are supported; there is no stateful Edit Mode or topology-operator layer.',
-    supportedSubset: ['box', 'plane', 'sphere', 'capsule', 'circle', 'cone', 'cylinder', 'torus', 'torus knot', 'lathe', 'tube along a Catmull-Rom path', '2D shape with holes', 'extrude with bevel', 'explicit indexed mesh', 'computed normals'],
-    unsupportedSubset: ['vertex/edge/face selection', 'topology extrusion operator', 'inset', 'loop cut', 'bevel operator', 'merge/dissolve', 'shape keys', 'sculpt topology'],
+    canonicalRepresentation: 'Geometry resources include procedural recipes, indexed triangles, and editable polygon-corner meshes with topology hashes, layers, material slots, sharp edges, and creases.',
+    mcpWorkflow: ['three_studio_inspect: meshElements for exact topology and topologyHash', 'three_studio_apply: geometry.edit with guarded bounded commands', 'three_studio_apply: entity.create with components.mesh'],
+    runtimeNotes: 'Geometry edits are exact canonical mutations rather than UI selection state; topology and corner attributes propagate together and compile to indexed WebGPU geometry.',
+    supportedSubset: ['procedural primitives and curves', 'indexed and editable polygon meshes', 'exact vertex/edge/face selections', 'move/scale/rotate/smooth/proportional move', 'subdivide/inset/extrude/bevel/delete/merge', 'normals', 'UV and color layers', 'face materials', 'sharp edges and creases'],
+    unsupportedSubset: ['loop cut', 'dissolve', 'shape keys', 'interactive selection mode', 'sculpt topology'],
     officialUrls: ['https://docs.blender.org/manual/en/latest/modeling/meshes/editing/introduction.html'],
   }),
   capability({
@@ -179,8 +179,8 @@ const entries = [
     canonicalRepresentation: 'Entity.components.modifiers is an ordered, stable-ID stack. Canonical live types are validated strictly; unsupported Blender settings use an explicit bakeBoundary with a validated Blender operatorType and opaque bounded parameters.',
     mcpWorkflow: ['three_studio_inspect: modifierDigest for the exact stackHash', 'three_studio_apply: guarded modifier.create|patch|move|delete or modifier.stack.edit', 'three_studio_validate', 'Bake explicit bakeBoundary entries externally before expecting downstream live evaluation.'],
     runtimeNotes: 'Array, mirror, and pattern lower to bounded instance transforms. Nine deterministic indexed-mesh modifiers evaluate as derived geometry without mutating the shared base resource. A bakeBoundary stops live downstream evaluation instead of silently approximating it. Blender 5.2\'s complete 83-type RNA inventory remains queryable; authored render-enable flags are preserved but do not claim render/evidence parity.',
-    supportedSubset: ['ordered stack up to 64 entries', 'stable modifier IDs and exact stack hashes', 'one guarded atomic stack-edit batch', 'array count/offset up to bounded limits', 'single-axis mirror', 'bounded linear/grid/radial/scatter patterns', 'triangulate', 'weld', 'smooth', 'weighted normal subset', 'edge split by angle', 'solidify subset', 'simple/Loop triangle subdivision', 'deterministic decimate subset', 'inline deterministic displacement', 'complete Blender 5.2 Object Modifier Type Items inventory'],
-    unsupportedSubset: ['full Blender semantic parity for live geometry subsets', 'render/evidence parity for enabledRender', 'downstream live evaluation after bakeBoundary', 'surface masks or collision-aware scatter', 'apply-to-base operation', 'edit cage', 'modifier object/vertex-group references', 'Grease Pencil stroke/layer object model', 'physics solvers'],
+    supportedSubset: ['ordered stack up to 64 entries', 'stable modifier IDs and exact stack hashes', 'one guarded atomic stack-edit batch', 'array count/offset up to bounded limits', 'single-axis mirror', 'bounded linear/grid/radial/scatter patterns', 'area-weighted surface scatter with normal/gravity alignment and minimum spacing', 'triangulate', 'weld', 'smooth', 'weighted normal subset', 'edge split by angle', 'solidify subset', 'simple/Loop triangle subdivision', 'deterministic decimate subset', 'inline deterministic displacement', 'complete Blender 5.2 Object Modifier Type Items inventory'],
+    unsupportedSubset: ['full Blender semantic parity for live geometry subsets', 'render/evidence parity for enabledRender', 'downstream live evaluation after bakeBoundary', 'collision-aware scatter beyond minimum spacing', 'apply-to-base operation', 'edit cage', 'general modifier object/vertex-group references', 'Grease Pencil stroke/layer object model', 'physics solvers'],
     officialUrls: [
       'https://docs.blender.org/manual/en/5.2/modeling/modifiers/introduction.html',
       'https://docs.blender.org/api/5.2/bpy_types_enum_items/object_modifier_type_items.html',
@@ -205,9 +205,9 @@ const entries = [
     status: 'partial',
     canonicalRepresentation: 'Material resources use basic, standard, physical, or toon recipes with linear color and bounded scalar parameters.',
     mcpWorkflow: ['three_studio_apply: resource.create materials', 'three_studio_apply: entity.create|entity.patch materialIds'],
-    runtimeNotes: 'The WebGPU compiler supports one material per mesh and compiles the supported typed graph subset to Three.js TSL NodeMaterials.',
-    supportedSubset: ['base color', 'roughness', 'metalness', 'emissive', 'opacity', 'clearcoat', 'transmission', 'toon/basic/standard/physical families', 'Blender-shaped live shader graphs'],
-    unsupportedSubset: ['multiple material slots', 'volume materials', 'true geometric material displacement', 'image texture binding'],
+    runtimeNotes: 'The WebGPU compiler supports exact face material slots, canonical raster maps, and typed TSL graphs, including a documented view-rim subsurface approximation.',
+    supportedSubset: ['base color', 'roughness', 'metalness', 'emissive', 'opacity', 'clearcoat', 'transmission', 'multiple face material slots', 'canonical image texture binding', 'subsurface tint/scale approximation', 'toon/basic/standard/physical families', 'Blender-shaped live shader graphs'],
+    unsupportedSubset: ['volume materials', 'true random-walk subsurface scattering', 'true geometric material displacement'],
     officialUrls: ['https://docs.blender.org/manual/en/latest/render/materials/introduction.html'],
   }),
   capability({
@@ -229,9 +229,9 @@ const entries = [
     status: 'partial',
     canonicalRepresentation: 'Texture and asset resources plus versioned typed texture graphs with explicit color-space declarations.',
     mcpWorkflow: ['three_studio_inspect: graphCatalog domain texture', 'three_studio_apply: resource.create textures|assets|graphs', 'three_studio_validate'],
-    runtimeNotes: 'Procedural texture graphs compile to live TSL where supported and can be deterministically CPU-evaluated into typed albedo, roughness, normal, and height maps.',
-    supportedSubset: ['sRGB/non-color declarations', 'UV and generated coordinates', 'checker/gradient/noise/Voronoi/Wave/ramp/math evaluation', 'bounded deterministic CPU bake', 'live procedural TSL'],
-    unsupportedSubset: ['image decoding and GPU binding through MCP', 'UDIM', 'texture painting', 'file-producing bake jobs'],
+    runtimeNotes: 'Procedural texture graphs compile live and the textureBake job can commit an albedo, roughness, or normal output as a canonical dataTexture without external files.',
+    supportedSubset: ['sRGB/non-color declarations', 'UV and generated coordinates', 'checker/gradient/noise/Voronoi/Wave/ramp/math evaluation', 'bounded deterministic CPU bake job', 'canonical raster GPU binding', 'live procedural TSL'],
+    unsupportedSubset: ['external image-file decoding through MCP', 'UDIM', 'texture painting', 'height-map job output'],
     officialUrls: ['https://docs.blender.org/manual/en/latest/render/shader_nodes/textures/index.html'],
   }),
   capability({
@@ -337,9 +337,9 @@ const entries = [
     status: 'planned',
     canonicalRepresentation: 'Future versioned compositor graph resources consuming explicit render passes and producing bounded image outputs.',
     mcpWorkflow: ['three_studio_render: future diagnostic/render passes', 'three_studio_job: future offline compositor job'],
-    runtimeNotes: 'Only direct WebGPU beauty evidence is available; no post-render graph is evaluated.',
-    supportedSubset: [],
-    unsupportedSubset: ['compositor nodes', 'render-layer inputs', 'AOVs', 'cryptomatte', 'file outputs', 'viewport compositor'],
+    runtimeNotes: 'No post-render graph is evaluated, but bounded raster, albedo, roughness, normal, UV, and object-ID diagnostic inputs are available.',
+    supportedSubset: ['diagnostic render inputs for future compositing'],
+    unsupportedSubset: ['compositor nodes', 'cryptomatte', 'file-output nodes', 'viewport compositor'],
     officialUrls: ['https://docs.blender.org/manual/en/latest/compositing/introduction.html'],
   }),
   capability({
@@ -348,10 +348,10 @@ const entries = [
     label: 'Rendering',
     status: 'partial',
     canonicalRepresentation: 'External Three.js WebGPU renderer plus revision-bound evidence metadata and project render settings.',
-    mcpWorkflow: ['three_studio_status', 'three_studio_render: beauty with authored camera or exact framing', 'three_studio_inspect: latestEvidence'],
-    runtimeNotes: 'The persistent native viewport uses WebGPU with shadows. Evidence capture is explicit and offscreen; RTX, animation, and diagnostic passes are capability-gated.',
-    supportedSubset: ['WebGPU beauty pass', 'native live viewport', 'shadows', 'offscreen PNG evidence', 'perspective and orthographic capture', 'exact revision metadata'],
-    unsupportedSubset: ['Cycles', 'Eevee parity', 'RTX path tracing', 'AOV/render passes', 'render animation', 'distributed render', 'denoising'],
+    mcpWorkflow: ['three_studio_status', 'three_studio_render: beauty+raster or material diagnostic passes with authored camera/exact framing', 'three_studio_inspect: latestEvidence|rtxDigest'],
+    runtimeNotes: 'The persistent native viewport uses WebGPU. Explicit evidence can pair raster and active RTX beauty and can isolate material channels without contaminating the ordinary render loop.',
+    supportedSubset: ['WebGPU beauty and raster passes', 'native live viewport', 'shadows', 'offscreen PNG evidence', 'albedo/roughness/normal/UV/object-ID diagnostics', 'perspective and orthographic capture', 'exact revision metadata', 'RTX preflight and raster fallback'],
+    unsupportedSubset: ['Cycles', 'Eevee parity', 'RTX path tracing', 'render animation sequences', 'distributed render', 'denoising'],
     officialUrls: ['https://docs.blender.org/manual/en/latest/render/introduction.html'],
   }),
   capability({
@@ -482,11 +482,11 @@ const entries = [
     domain: 'uvEditing',
     label: 'UV Editing',
     status: 'partial',
-    canonicalRepresentation: 'Explicit geometry resources may carry one UV attribute array aligned to vertex positions.',
-    mcpWorkflow: ['three_studio_apply: resource.create|resource.patch indexedMesh with uvs'],
-    runtimeNotes: 'UV coordinates persist and compile, but texture maps do not yet bind and there is no unwrapping operator.',
-    supportedSubset: ['single UV attribute import', 'UV buffer validation by vertex count'],
-    unsupportedSubset: ['unwrap', 'seams', 'multiple UV maps', 'UV islands', 'packing', 'live UV editing'],
+    canonicalRepresentation: 'Editable polygon meshes own named per-corner UV layers with an explicit active viewport layer; indexed meshes retain one compact UV channel.',
+    mcpWorkflow: ['three_studio_inspect: meshElements for exact corners and active layer', 'three_studio_apply: geometry.edit create/set/transform/project UV commands'],
+    runtimeNotes: 'UV edits preserve seams through topology operations. Planar, cylindrical, and spherical projection are live; the active layer binds raster maps and UV graph inputs.',
+    supportedSubset: ['multiple named UV layers', 'exact per-corner UV edits and seams', 'active UV layer', 'transform UVs', 'planar/cylindrical/spherical projection', 'raster and graph sampling'],
+    unsupportedSubset: ['angle-based unwrap', 'island packing', 'automatic seam marking', 'UDIM'],
     officialUrls: ['https://docs.blender.org/manual/en/latest/modeling/meshes/uv/unwrapping/introduction.html'],
   }),
   capability({