#72 docs: ghostty_surface_host_frame's present needs an explicit CATransaction lock span with no draw in it (#71 follow-up)

Summary

• Follow-up to #71 (the Claude review, should-fix 3). The header rule for ghostty_surface_host_frame(present: true) said "in one [CATransaction lock] span (or one Core Animation layout or display pass of the commit)". It is not known whether Core Animation holds the lock in a layout or display pass. Also, a display pass of a surface with nothing shown draws on main: drawFrame(true) waits for a free frame, and the GPU completion thread frees that frame only after it took the lock.
• The rule now allows only an explicit lock span. In that span: no commit, no flush, and no draw (ghostty_surface_draw, or a first-frame display pass).
• The example call site is now a main run-loop observer just before Core Animation's commit (what cmux's TerminalFramePresenter does), not a layer that Core Animation displays.
• The comment in the commit-order test now says that the test counts commits only. The off-main present calls no flush.
• Comments only. No code changes, no test changes and no workflow changes. cmux does not need to move its pin for this change (it pins 7d43bb68b, the #71 merge).

Testing

• Comment-only diff: git diff 7d43bb68b...db8627d95 -- src/ changes only // lines.
• PR CI of this branch.

Observed / Not run

• Observed: the diff above.
• Not run: no test run is necessary for a comment change.

Changelog

none

---

^{Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.}

---

Summary by cubic

Follow-up to #71's review: tightens the locking rule for ghostty_surface_host_frame(present: true). The rule previously accepted either an explicit [CATransaction lock] span or a Core Animation layout or display pass; only the explicit lock span is valid now, since it's unknown whether Core Animation holds the lock in those passes and a display pass of a surface with nothing shown draws on main and can deadlock. The docs now also forbid drawing in the span, the example call site is a main run-loop observer just before Core Animation's commit (what cmux's TerminalFramePresenter does) instead of a displayed layer, and the commit-order test's comment now says it counts commits only. Comments only: no code, test, or workflow changes, so cmux does not need to move its pin.