docs: round-2 accuracy audit (xml pitfall markup fix)

[adamziel]

Summary

Second-round accuracy pass on bin/_docs_components/<slug>.md. After the first pass (#257) fixed six load-bearing inaccuracies in html.md and markdown.md, this round drilled deeper by exercising more of the underlying APIs to make sure the prose still matches reality. One small markup bug in xml.md falls out; everything else holds.

What got fixed

bin/_docs_components/xml.md — two pitfall callouts had unbalanced <strong> tags, an artifact of an earlier "bold the lead sentence" reformat that didn't notice the existing <strong>#1:</strong> prefix. The rendered HTML had one open and two closes per pitfall, so the bold span effectively ran from the #N: colon through the rest of the paragraph (browsers forgive the orphan close, but it doesn't render the way every other pitfall in the catalog does).

- <p>Footgun: <strong>#1:</strong> namespace-aware methods use the namespace
-   name declared in <code>xmlns</code>, not the prefix written in the tag.</strong>
+ <p>Footgun: <strong>Namespace-aware methods use the namespace URI, not the
+   prefix written in the tag.</strong>

Dropped the #N: numbering (it added nothing — each Footgun renders as its own <aside>) and rewrote the bold span to wrap a single lead sentence, matching the style every other pitfall on the site uses.

What got checked and found accurate

For each component I:

• Resolved every use WordPress\… import via class_exists / interface_exists. Every one resolves.
• Resolved every ->method() call in every snippet via reflection. Every one exists on the class returned by the preceding factory/constructor.
• Ran behavioural spot-checks on the load-bearing claims:

Component	Claim	How I checked
ByteStream	pull → peek (non-advancing) → consume (advancing)	Walked abcdefghij through pull(5), peek(3) twice, consume(3), peek(2) — semantics match.
Polyfill	Filter priority ordering (lower runs first), variadic arg passing, action capture	Three filters at priorities 5/10/20 → runs 5 → 10 → 20; do_action('x', 'a', 'b') → 2-arg callback gets both.
Polyfill	esc_html, esc_attr, esc_url, __() outputs	All match prose.
Encoding	wp_is_valid_utf8 accepts 'hello', rejects "\xC3\x28"; wp_scrub_utf8 produces a U+FFFD replacement	All match.
Filesystem	LocalFilesystem::create($root) chroot — ../escape.txt cannot escape	Verified: ../ resolves to root-relative; no file appears outside $root.
Filesystem	SQLiteFilesystem::create(':memory:') round-trips file contents	put_contents('a.txt','data') then get_contents('a.txt') returns 'data'.
ByteStream	DeflateReadStream / InflateReadStream round-trip	550 bytes → 32 compressed → 550 bytes back, byte-for-byte.
BlockParser	Block array has exactly five keys: blockName, attrs, innerBlocks, innerHTML, innerContent	Confirmed via array_keys().
BlockParser	blockName === null for loose HTML between blocks	Confirmed across three loose-HTML positions (before, between, after).
Markdown	MarkdownConsumer::consume() returns BlocksWithMetadata	get_class() confirms the canonical namespace.
Markdown	Round-trip via MarkdownConsumer + MarkdownProducer works for headings/lists	Confirmed; output preserves structure, with only trailing-newline drift.
HttpClient	Request($url, ['method' => 'POST', 'headers' => […]]) constructor accepts options array	Confirmed.
HttpClient	Response::from_http_headers($raw, $request) → Response with status_code	Confirmed.
DataLiberation	ImportEntity('post', […]) constructor signature; WXRWriter::append_entity exists	Confirmed via reflection.
Git	GitRepository::commit(options) exists	Confirmed in the public method list.
XML	XMLProcessor::create_from_string() parses, walks next_tag(); get_tag_namespace() returns the URI not the prefix	Confirmed.
Zip	ZipDecoder::COMPRESSION_NONE = 0, COMPRESSION_DEFLATE = 8	Confirmed via ReflectionClass::getConstant().
CLI	CLI::parse_command_args_and_options() exists, returns [positionals, options]	Confirmed.
Blueprints	HumanFriendlySchemaValidator constructor takes $schema (required), $options (optional)	Confirmed.
HttpServer	ResponseWriteStream is an interface (not a class) — use statements still valid	Confirmed via interface_exists.

Test plan

• Verify docs snippets workflow passes (87/87).
• Pitfall callouts in xml.md render with a single bold lead, matching the rest of the catalog.

🤖 Generated with Claude Code