fix: audit Web API binding contracts

[jderochervlk]

Summary

• audit Web API binding returns and properties for spec-defined absence, using Null.t for JavaScript null and option for undefined-only values
• propagate absence through promise result types and add @throws(JsExn) to synchronous bindings that can throw
• model HTMLElement.hidden reads with an explicit state type and separate semantic/raw setters
• update compile-time contract tests for the corrected APIs

No audited binding required Nullable.t; the reviewed APIs distinguish null from undefined-only values.

Migration

Direct hidden record-field access is replaced by the typed HTMLElement functions:

// Before
element.hidden = true

// After
element->HTMLElement.setHidden(HTMLElement.Hidden)

Use HTMLElement.hidden for typed reads and HTMLElement.setHiddenRaw only when the native Web IDL setter's coercion behavior is required.

Verification

• npm test
• npm run format:check
• npm run check:features
• git diff --check

---

_{Stack created with GitHub Stacks CLI • Give Feedback}

[jderochervlk]

@codex

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-08-29T14:43:22.198827Z	a11e7cf	Manual request

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a11e7cfb79

ℹ️ 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".