feat(runtime): align React event prop bindings

[integrate-your-mind]

Summary

• map React-facing onDoubleClick to native dblclick
• support the current allowlisted React DOM Capture props with native capture-phase listeners
• preserve custom event names outside that allowlist
• add normal, failure, odd, replacement, removal, and compatibility regressions
• document a source-backed compatibility matrix without making a drop-in React claim

Current disposition

FIX_NOW / ready for review, not merge eligible.

• Remote head: 1188761f0a4b05a9f0f1825c82f4bec74ee4268d
• Base: codex/pr13-site-integration-proof@dc2ab5e0103ad06aab9e07ac8bc8cf563bab3644
• Comparison: CLEAN / mergeable as a Git diff only
• GitHub status checks: zero
• Eligible approvals: zero
• Review thread: one outdated, unresolved P2 on custom events ending in Capture

The remote head fixes that P2 at the parser boundary: custom onFileCapture remains native filecapture, while onFileCaptureCapture explicitly requests capture-phase filecapture. The regression asserts both wrong-event silence and correct-event delivery across initial binding, replacement, and removal. The outdated thread remains open until executable exact-head proof exists; no review thread is being silently resolved from source inspection alone.

Scope and dependency

This PR is stacked on the older codex/pr13-site-integration-proof branch. Its comparison is limited to:

• README.md
• docs/react-compatibility.md
• packages/runtime/src/dom-base.ts
• packages/runtime/test/dom.test.mjs

PR #13's actual current head is a7a5f7f50dafd2a0a3eaab301ab570d787deac2d; this dependent PR must be reconciled and re-proven only after PR #13 reaches a terminal disposition. No rebase, retarget, or source mutation is included in this metadata refresh.

It does not modify release scripts, server-action security, Cloudflare, observability, uploads, or publication behavior.

Reproduced original defects

Before the compatibility slice:

• onDoubleClick registered doubleclick, so native dblclick produced no call.
• onClickCapture registered clickcapture, so it did not participate in capture ordering.

The formerly actionable P2 showed that parsing every trailing Capture as a phase modifier would reinterpret the native custom event filecapture; the remote fix is intentionally covered by discriminating wrong/right-event regressions.

Evidence and exact-head gaps

Independent exact-head source review of 1188761: ACCEPT, with no P0-P2 finding.

Static checks at the exact remote head:

• git diff --check: pass
• node --check packages/runtime/test/dom.test.mjs: pass
• redacted Gitleaks scan of origin/codex/react-compatibility..HEAD: no leaks

Current missing proof:

• the mandatory guard denied the focused exact-head runtime-test launch before child execution with exit 75; no test result is inferred
• no exact-head lint, typecheck, build, full tests, coverage, browser QA, package/runtime proof, or Buildkite run exists
• GitHub reports zero checks and no distinct eligible approval

No stale, denied, local-only, or earlier-SHA run is being relabeled as current CI evidence.

Compatibility boundary

Ferrite remains not drop-in React compatible. This slice aligns selected event prop names and phase selection only. Event objects remain native, listeners remain per-element, and Ferrite does not implement React synthetic delegation or onChange normalization.

React capture names intentionally take precedence. onClickCapture means capture-phase click; it cannot mean a bubbling custom event named clickcapture. Unknown names such as onFileCapture retain native custom-event behavior. onFileCaptureCapture explicitly opts that custom event into capture phase. onMouseEnterCapture and onPointerEnterCapture are not claimed as React two-phase capture props and retain custom-event mapping.

Risk and rollback

Risk is limited to DOM listener registration, replacement, and removal. Rollback is a normal revert of the focused event commits; there is no migration, persistent data, configuration, deployment, or release state. The PR must not merge until its dependency is reconciled, the outdated P2 is proven closed by executable evidence, and all exact-head technical and repository review requirements are satisfied.

[integrate-your-mind]

Independent advisory review at exact head e1bdf16189482ac7a86488fbac783932665fbea5: GO on the four-path PR comparison. The reviewer found no hidden overlap from the advanced-base merge and no blocker in event aliasing, capture/bubble coexistence, replacement/removal, pointer-capture exceptions, malformed-name rejection, failure atomicity, backward compatibility, or documentation boundaries. This is technical review evidence, not the distinct GitHub approval required by branch protection. Guarded exact-head verify, coverage, and CI remain pending.

[integrate-your-mind]

Delivery boundary at exact remote head e1bdf16189482ac7a86488fbac783932665fbea5:

• local, upstream, and GitHub branch SHAs match; PR is CLEAN/MERGEABLE as a Git comparison
• all four changed-file blobs are byte-identical to the previously linted, built, covered, and browser-tested b3cf6b3 head
• exact-head independent advisory review is GO
• exact-head Buildkite-equivalent verify was denied before execution by the mandatory launch guard: heavy job denied for ferrite-react-compat-verify-e1bdf16: warning pressure with swap usage
• the existing private Ferrite Buildkite pipeline branch configuration does not include codex/react-compatibility, and no project=ferrite / queue=ferrite-local agent is connected; GitHub reports zero checks
• branch protection requires one approval, but the repository currently exposes only the author/codeowner collaborator identity, so self-approval cannot satisfy it

The PR remains draft and not merge-ready. No check, approval, merge, deployment, or release is being inferred.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e1bdf16189

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[integrate-your-mind]

Reviewed exact head 1188761f0a4b05a9f0f1825c82f4bec74ee4268d.

The earlier onFileCapture regression is fixed by limiting Capture suffix stripping to the React allowlist and the explicit repeated-suffix form. The listener keying also handles bubble/capture coexistence, phase changes, replacement, and removal correctly. I found no new P0–P2 source defect in the four changed paths.

This is not an approval or merge signal: the exact head has no GitHub workflow run, so runtime, typecheck, build, and full-test proof remain open.

[integrate-your-mind]

Pin this evidence to immutable revisions. Both “current official React documentation” and “repository head” move after this file lands, and the React source link below targets main, so the date alone does not let a reader reproduce which contracts were checked. Please name a React tag/commit and this Ferrite SHA, or remove the review-at-head claim.