fix(webapi): correct binding nullability and exception contracts [Codex]

[jderochervlk]

Problem

Several Web API bindings did not accurately represent browser behavior. Nullable and optional values were modeled inconsistently, synchronous operations that can throw were missing exception annotations, and HTMLElement.hidden exposed a mutable field without representing the until-found state or the native setter's coercion behavior.

These mismatches made some valid browser states difficult to express and allowed callers to assume values were present when the platform can return null or undefined.

Solution

Align the affected bindings with their Web IDL contracts. The updated types distinguish null-only values from values that may be either null or undefined, expose synchronous exceptions through @throws(JsExn), and model HTMLElement.hidden with semantic states plus an explicit raw setter for native coercion cases.

Changes

• Corrected return, property, parameter, and record-field types across animation, canvas, DOM, fetch, storage, media, messaging, workers, and related APIs.
• Added @throws(JsExn) to synchronous bindings that can raise JavaScript or DOM exceptions.
• Added HTMLElement.hiddenState, typed hidden and setHidden bindings, and setHiddenRaw for the complete native setter contract. The typed accessors are also available through the concrete HTML element modules.
• Added and updated compile-time fixtures for nullable inputs, null-returning APIs, required fields, worker names, and the HTMLElement.hidden contract.

Migration

// Before
element.hidden = true

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

Use HTMLElement.hidden for typed reads. HTMLElement.setHiddenRaw remains available when the full native setter behavior is required.

---

_{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-09-03T13:26:07.202219Z	bbe9c53	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".

[jderochervlk]

@codex

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bbe9c53735

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