So, you asked for a post-mortem. It's a bit tricky since I'm not using any prefab macros, building things from scratch, and I do not yet have a full grasp of how troff's low-level plumbing for such things works.
There are "environments" for saving parameters like font, line length, etc. You can "divert" output to recall later and also measure its size, so I use that on the floating content. Then you set "traps" at the appropriate (vertical) positions that shrink the text area to flow stuff around and finally move into the empty space and place the diverted text.
Something isn't working the way I expect which causes the spacing around the heading to fail. No idea what's going on, yet. Anyway, once I figure it out, I can roll the technique into macros and future inserts should be easy.