Here I try to collect known issues, incompatibilities and workarounds when it comes the the usage of <references> transcluded by templates with VE. Especially in the context of the {{reflist}} templates that are used in several projects.

Context:

There are several Wiki projects that use a version of the {{reflist}} template to insert the references section into an article. Mostly out of convenience to apply common styling. The usual template looks something like that inside (simplified):

Template:

<templatestyles src="Reflist/styles.css" />
<div class="reflist">
  {{#tag:references|{{{refs|}}}|group={{{group|}}}}}
</div>

Usage:

Apart from applying custom styling the template is also used to define named references for the article:

Reference here: <ref name="list-defined" />

=== References there: ===
{{reflist|refs=<ref name="list-defined">Reference content</ref>}}

This can get even more complex, when templates are used in the refs inside of the {{reflist}} template:

Book reference here: <ref name="list-defined-book" />

=== References there: ===
{{reflist|refs=<ref name="list-defined-book">{{Cite_book|title=Foo|author=Bar}}</ref>}}

Issues:

Parsoid is not necessarily able to provide enough context when nested references inside of another template are used so that VE can work with these. Especially in the later example there have been problems in the past when users tried to copy footnotes in VE from one article to another, leaving the new articles with weird fragments of references that could not be parsed correctly. See

T209493: VE is transforming citation templates into formatted text with "cite class" tags (when copying a reference defined within template-generated reflist)

Apart from that VE still tries to support the {{reflist}} use case to provide some convenience for editor nonetheless. It does that by inserting a readonly version of a MWReferencesListNode when it detects it as result of a transclusion. To make sure that the MWReferencesListNode is not written back to Wikitext as <references> tag VE needs to track whenever a that node came from a transclusion or not. See

T52769: Adding or updating a reference in VisualEditor does not update fake references blocks inside templates
T188898: VisualEditor converts reference list template to plain reference list on cs.wiki
T310407: {{reflist}} no longer detected as a reference list and therefore updating as references are added

User should also not be able to edit references that are created from a template, or in that cases from the references tag transcluded by a template. VE cannot know how changes would need to be written back to the template without specific knowledge of it's concrete setup and configuration. So the references coming from a {{reflist}} need to be at least readonly.

Workarounds in code:

Parsoid tries to detect whenever a <references> tag is coming from a transclusion and then does not add the body.html of nested references to the tag's mwData. It also never marks a these tags as autoGenerated.

See
https://gerrit.wikimedia.org/g/mediawiki/extensions/Cite/+/635589c4cf012ce46bbfd65cf1026f9580414373/src/Parsoid/References.php#618

VE hard codes the common variants of how mw:Extension/references can appear in the DOM including exceptions for the case that a TemplateStyles node comes before the actual node including the tag.

See ( and the following lines )
https://gerrit.wikimedia.org/g/mediawiki/extensions/Cite/+/635589c4cf012ce46bbfd65cf1026f9580414373/modules/ve-cite/ve.dm.MWReferencesListNode.js#99

VE also does not compute the body.html of a transcluded references node to avoid processing theses refs in a way where they can lead to problems in other parts.

See ( and following )
https://gerrit.wikimedia.org/g/mediawiki/extensions/Cite/+/635589c4cf012ce46bbfd65cf1026f9580414373/modules/ve-cite/ve.dm.MWReferencesListNode.js#128