feat(native): expose native integration snapshots

[monotykamary]

Summary

Expose two observational primitives for trusted native integrations:

• getNativeWindowHandle() returns a tagged, lossless native-byte-order handle, with the display connection where required.
• getElementPaintState(id) returns last-painted logical bounds, rectangular clipping, and scale without forcing a render.

Add generated native declarations, React types/test forwarding, focused regressions, a small diagnostic example, README contracts, and a changeset.

Scope and API rationale

No CEF, WebView, terminal, native-child host, callbacks, new style behavior, or Zed submodule change. Existing GPUI HasWindowHandle / HasDisplayHandle and paint-time bounds are sufficient; this does not depend on remorses/zed#8.

The boundary follows Electron's native-handle Buffer, raw-window-handle's borrowed lifetime/thread constraints, and Qt's explicit foreign-window ownership. Bytes do not retain a window. These snapshots are not leases, safe FFI callbacks, or native-child lifecycle guarantees. Applications own synchronization, parenting, focus, stacking, and cleanup.

Geometry is recorded during paint, not speculative virtual-list prepaint. It is scoped to the renderer owning the latest paint records, may be stale until another paint, and does not imply visibility or hit-test acceptance. Rounded clipping and occlusion are not represented. README documents null/error cases and platform handle widths.

Upstream research confirmed merged zed-industries/zed#24327, zed-industries/zed#50768, and zed-industries/zed#62775; no new GPUI API is required.

Validation

On macOS Apple Silicon, against the freshly rebuilt release addon:

• Native library: 232 passed, including six backend encoding tests.
• React: 413 passed, including nine snapshot regressions; package build passed.
• Examples: 47 passed; starter: 6 passed.
• Real background AppKit probe verified handle encoding, scale, clipped bounds, renderer ownership, and removal after paint. The close action exited normally; post-close JS assertions are not claimed.
• Diagnostic bundle and public API checks passed; git diff --check passed.

Windows/Linux encoding is unit-tested, but their desktop runtimes were not exercised locally. cargo fmt --check reports three unchanged baseline regions in accessibility.rs, custom_elements/img.rs, and custom_elements/input.rs; this PR does not reformat unrelated code.

Grok 4.6 reviewed the design and code. Findings about offscreen handle semantics and generated comments were fixed; an unrelated visibility change was removed. Final review: APPROVE.

Agent provenance

Harness: Pi coding agent with Fabric
Agent: Main, with isolated dynamic-image-pr / embedding-pr implementation agents
Model: openai-codex/gpt-6-astra
Design and code review: xai/grok-4.6

User prompts driving these primitive PRs (verbatim)

1. Perfect. Recall what PRs we wanted to do once the zed PR we made was merged.

2. Does GPUIx need them baked in? Or leave it up to the user? Our colleague wants to make sure we expose primitives and create small scoped PRs.

3. Help me add (1) and (2) while considering carefully best practices of related primitives out in the wild (feel free to search the web and check). Make sure grok 4.6 reviews your work and code; it needs to be tight and small in scope and PR, follow code conventions and most importantly good code style. Create those PRs for me.

4. gh watch the CI and resolve the issues.

5. I've converted them to a draft. Open them back up once all fixed. Proceed.

CI follow-up

Commit 199da00 fixes Windows subprocess file-URL conversion and derives clipping expectations from the actual native viewport. Targeted local tests: 78 passed; package build passed. Grok 4.6 approved the test-only changes. All platform builds, macOS/Windows test jobs, and the publish job passed in CI run 34314125640. Marked ready only after the exact updated head was green.