docs: rendered-output pitfalls (diamond exits, pixel-exact pins, labels) + DOM verification workflow

[xiaoraoxiaorao]

Context

While generating and reviewing a bilingual (Chinese) government geodata-pipeline flowchart with this skill, several edge/label defects slipped through both validate.py and visual review. Every rule below was verified against the renderer's actual output (viewer URL + headless --dump-dom, reading <path d> segments and label foreignObject anchors), not by eye.

What this adds

references/xml-authoring.md — new section Decision-diamond branches, pixel-exact pins, and labels:

• Rhombus vertex exits must head outward; an elbow leaving the left/right vertex with an inward horizontal run crosses the diamond's own interior (nothing flags it — not the validator, not vision). When both branch targets sit below the decision, one straight edgeStyle=none line per branch from the lower-left / lower-right edge midpoint (exitX=0.25;exitY=0.75 / exitX=0.75;exitY=0.75, both on the rhombus outline) to the target's top center is simpler and crosses nothing.
• entryX/exitX pins must be computed with full precision ((sourceCenterX − target.x) / target.width, e.g. 0.0652); a 1–2 px mismatch renders as an S-shaped double curve (two Q bends) just before the arrowhead. Style values accept more than two decimals.
• endArrow=block;endSize=8 for main flow edges — blockThin tips flush against the border read as "piercing the box" to reviewers.
• Keep only micro-labels (Yes/No) on the line: the white label chip severs its own edge, and near a corner cuts both segments. Offset longer labels into verified empty space; shorten any label wider than the corridor it annotates.

references/troubleshooting.md — new section Verifying the rendered output: dump the viewer DOM and assert per-edge <path> segments and label anchors by script; retry ERR_CONNECTION_CLOSED with a fresh --user-data-dir and gate screenshots on palette-pixel counts (error pages pass naive "has content" checks, and vision models both miss geometry defects and hallucinate new ones). Two new table rows for these failure modes.

SKILL.md — creation-workflow step 5 now points to the DOM-verification fallback when the drawio binary is unavailable or a visual check is inconclusive.

All content is cross-platform (any recent Chromium works for --dump-dom).

[Agents365-ai]

Thanks @xiaoraoxiaorao. I verified the geometry claims against the renderer's own output and pushed three small commits onto your branch.

1. Line endings. The three references arrived as CRLF (GitHub renders every line as trailing whitespace), so the PR diffed as a 459/413 whole-file rewrite while the real change was 46 added lines. Restored LF; the added sections are untouched. The diff is now +56/-0 across 4 files.

2. ## [Unreleased] entry. This repo puts user-facing documentation changes under Unreleased (docs(readme): reorganize for readability did the same) and lets the separate chore(release) commit own the version bump, so I added a bullet there.

3. First decision-diamond row reworded. I could not reproduce an interior crossing from the exact left/right vertex. With exitX=0;exitY=0.5 the orthogonal router dodges instead and wraps the elbow around the top of the diamond: an SVG export of a two-node test gives M 19 59 L 14 59 Q 9 59 9 49 L 9 19 ... L 228.88 59. What does reproduce exactly as you describe is the pin on the shape's left/right side: exitX=0;exitY=0.25 with the target to the right at the same height renders M 20 26.67 L 160 26.7 Q ..., and that horizontal run crosses the rhombus's own interior. The row now names that pin and notes that the vertex case detours instead. The recommended fix is unchanged.

What I verified independently (drawio CLI SVG export, same renderer core as the viewer):

• exitX=0.25;exitY=0.75 and exitX=0.75;exitY=0.75 do land on the rhombus outline and give one straight segment per branch (M 130 60 L 130 189.88, M 190 60 L 322.85 192.85), neither crossing the diamond.
• The entryX precision rule reproduces exactly: entryX=0.49 (1.6 px off) renders L 580 280 Q 580 290 579.2 290 L 578.8 290 Q 578.4 290 578.4 299.94 L 578.4 309.88, i.e. the two Q bends before the tip, while entryX=0.5 is a clean single segment.
• validate.py is indeed silent on all of it: edge_route() returns None without explicit waypoints, so its through-vertex and edge-crossing checks only cover waypointed edges.
• Test suite on the branch: 214 passed, 4 skipped.

One caveat on the DOM recipe: on Chrome 152 here --headless=new --dump-dom never returned (0 bytes after 90 s, including on a plain data: URL), so I could not walk your viewer-DOM recipe end to end and used the CLI's SVG export instead. Which Chromium did you run the snippet on? If it was msedge, the existing "any recent Chromium works" line may be enough; tell me if bare --headless turned out to be the portable spelling, and I will add that note.

[Agents365-ai]

Verified the three added sections against the renderer's own output (details in my comment above), restored LF line endings, and added the Unreleased changelog entry. CI (unittest) is green on a7e2d00. Approving.