fix(logic): correct two structural logic bugs in MetadataFigure.run()

[lkdmc]

Summary

Two bugs that cause incorrect document tree structure or broken output in non-HTML builders.

1. self.content assigned a plain list instead of StringList (__init__.py:547)

When :number: is used without a caption, the code injected an HTML <span> placeholder by assigning a plain Python list to self.content. The parent Figure.run() expects a StringList; passing a plain list can cause subtle failures during caption parsing.

Additionally, the raw HTML <span class="invisible-caption-text">&nbsp;</span> was used regardless of the active builder. LaTeX, PDF, and other non-HTML builders render it as literal markup text, producing garbage in the output.

Fix:

• Wrap the placeholder in StringList([...]).
• Detect the builder name via env.app.builder.name; HTML-family builders (html, dirhtml, singlehtml, readthedocs) receive the HTML span; all other builders receive an RST escaped-space (\\ ) which produces no visible output.

---

2. {cite:empty} reference node appended to the document root (__init__.py:592)

self.state.document += para inserts the citation-registration paragraph directly at the top level of the Sphinx document tree. This bypasses the normal document-tree structure and can result in an extra paragraph appearing in unexpected locations or breaking document traversal.

Fix: collect the node in _extra_prefix_nodes and prepend it to the returned node list at the end of run(). Sphinx then inserts it at the correct position in the tree relative to the figure.

Test plan

• Use :number: on a figure without a caption; build with the LaTeX builder and confirm no raw HTML appears in the .tex output.
• Use :bib: with an existing key; confirm the build completes and the citation reference does not appear as an extra visible paragraph anywhere in the HTML output.
• Existing HTML builds should continue to show the invisible-caption span correctly for numbered uncaptioned figures.

https://claude.ai/code/session_01ApsmWPWsKBesMV1rq2VenA