Track v1.0.0 alpha release readiness #382

Goal

Ship the first hardened @rescript/webapi release in the 1.0.0-alpha.N series (initial candidate 1.0.0-alpha.1, Git tag v1.0.0-alpha.1) under npm's alpha dist-tag.

ReScript 13 is currently alpha, and this library may remain alpha alongside it. A stable ReScript compiler is not an alpha release prerequisite. The supported compiler prereleases must nevertheless be accepted by package metadata, documented, and tested through normal installation.

This tracker comes from the repository readiness review of commit ebe9cca6. It tracks actionable work, not authorization to publish or merge changes.

Alpha scope

• Normal installation and compilation of the actual npm artifact with the supported compiler alpha.
• Explicit, repeatable numbered-alpha release/version/channel handling.
• Fix the confirmed binding defects with targeted regressions; do not confuse successful compilation with platform correctness.
• Reliable Node/consumer tests plus a focused real-browser regression path for the affected browser APIs.
• Accurate alpha documentation, working local reference links, asset notices, and resolved identified tooling advisories.

Required sub-issues

Installation and release

• Accept supported ReScript 13 prereleases and verify tarball installation #384 — Accept supported ReScript 13 prereleases and verify tarball installation
• Publish explicit numbered v1.0.0 alpha versions safely #385 — Publish explicit numbered v1.0.0 alpha versions safely

Binding correctness

• Fix receiver dispatch for WebSocket sends and worker Request fetches #386 — Fix receiver dispatch for WebSocket sends and worker Request fetches
• Correct ResizeObserver callback arity #387 — Correct ResizeObserver callback arity
• Preserve Uint8Array types in Fetch, Blob, and SafeFetch byte APIs #388 — Preserve Uint8Array types in Fetch, Blob, and SafeFetch byte APIs
• Use native typed arrays in Web Audio and DOMMatrix bindings #389 — Use native typed arrays in Web Audio and DOMMatrix bindings
• Correct WebCrypto result types and verify key workflows #390 — Correct WebCrypto result types and verify key workflows
• Correct DOM constructor, narrowing, and SVG className contracts #391 — Correct DOM constructor, narrowing, and SVG className contracts
• Represent native empty, nullable, and operation-specific results accurately #392 — Represent native empty, nullable, and operation-specific results accurately

Validation

• Establish reliable runtime regression tests for the alpha #383 — Establish reliable runtime regression tests for the alpha

Documentation and distribution

• Document the ReScript 13 alpha contract and safe contributor workflow #393 — Document the ReScript 13 alpha contract and safe contributor workflow
• Resolve generated API links to public pages and check built documentation #394 — Resolve generated API links to public pages and check built documentation
• Include provenance and license notices for bundled documentation fonts #395 — Include provenance and license notices for bundled documentation fonts
• Update vulnerable documentation-tooling transitive dependencies #396 — Update vulnerable documentation-tooling transitive dependencies

Suggested execution order

1. Start Accept supported ReScript 13 prereleases and verify tarball installation #384 (installation) and Establish reliable runtime regression tests for the alpha #383 (regression infrastructure).
2. Implement the binding fixes in parallel by family, each with its own regression tests; docs/license/dependency work can also proceed independently.
3. Finish Publish explicit numbered v1.0.0 alpha versions safely #385 with the resulting validation gates, then verify the final candidate artifact and release checklist below.

Release acceptance

• Required sub-issues are resolved; any scope reduction is an explicit maintainer decision recorded here and in known limitations, not an implicit omission.
• A clean checkout passes the documented CI/release commands on the selected toolchain.
• A fresh consumer installs the actual tarball without peer-resolution bypasses and compiles/runs representative supported workflows.
• The candidate package contains the intended sources/interfaces/config/license and no development-only payload.
• Version, tag, package metadata, docs, changelog, and npm alpha dist-tag agree; latest is not advanced by an alpha release.
• Known limitations, tested compiler/browser/runtime scope, and alpha breaking changes are documented.
• An authorized maintainer approves actual publication and verifies the published artifact/dist-tag afterwards.

Not required for this alpha

• A stable ReScript 13 release, beta/stable API freeze, or guaranteed compatibility with all future compiler alphas.
• A complete Firefox/WebKit/browser-version matrix or exhaustive certification of every Web API.
• A blanket private-record conversion: the 80 related TODOs need a separate design decision; current compiler mutation emits warning 111.
• Generator rewrite/reproducible regeneration of all handwritten bindings, new API families, extension-module expansion, or speculative performance refactors.

Existing backlog to reconcile, not automatically duplicate

• Simplify package module/type structure #237 package/module structure
• Rename overloaded constructor bindings from numbered make* names to semantic from* names #236 constructor naming
• Improve generated overloads #27 generated overloads
• API overview #23 API overview
• How to model Errors #4 error modeling
• Consider adding useful extension module #5 optional extension module

These historical issues need current dispositions; they are not all automatically prerequisites for alpha.

Review evidence and limits

Existing npm ci, npm run format:check, npm run build, npm run check:features, npm test, and npm run build:docs passed on Node 24.16.0/npm 11.15.0/ReScript 13.0.0-alpha.5. Feature validation covered 28 bundles and three consumer compile fixtures. The tarball contained 343 files (~136 KB compressed).

Despite those passes, normal tarball installation failed, targeted compiled-consumer/native probes exposed binding defects, and the built docs contained 45 missing local routes. There are 42 ReScript fixtures but only seven runtime imports, with assertions in two modules. Isolated browser probes used Chromium 156; they are not a complete compiled-binding browser suite. The workflow's Node 26 environment and nested generator suite were not run locally during the review.