Repository navigation
Track v1.0.0 alpha release readiness #382
Description
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
- Start Accept supported ReScript 13 prereleases and verify tarball installation #384 (installation) and Establish reliable runtime regression tests for the alpha #383 (regression infrastructure).
- Implement the binding fixes in parallel by family, each with its own regression tests; docs/license/dependency work can also proceed independently.
- 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
alphadist-tag agree;latestis 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.
Activity
jderochervlk commentedon Nov 5, 2026
Implementation is being coordinated in three batched PRs:
agent/alpha-tooling-releaseagent/alpha-binding-contractsagent/alpha-docs-distributionEach batch has a separate implementation agent. After opening its PR, that agent will obtain an independent agent review, address actionable findings, and post issue-by-issue acceptance evidence. A passing compile alone is not sufficient, and unresolved criteria will remain explicit.
The tooling batch owns shared package/workflow/test infrastructure and will publish an early test-harness contract. The other batches can implement independently, then stack on the foundation where necessary. Stacked PRs must receive CI; docs-link validation will be wired with the documentation fixes rather than creating a circular foundation dependency.
ReScript 13 alpha remains an accepted baseline. This work does not authorize merging to main, publishing a package, or closing the milestone. PR links and final review/acceptance results will be added as the batches complete.
jderochervlk commentedon Nov 5, 2026
First batch PR is open: #397 — tooling/runtime/release foundation, currently draft, based on
main. An independent review agent is reviewing it; the implementation agent is responsible for addressing findings and revalidating the final head.The bindings and documentation batches are integrating the shared foundation on their own feature branches and will open stacked PRs. The foundation's CI now supports PRs targeting non-main base branches.
A release permission issue is being corrected during review: PR validation/dry-run must not receive npm-capable OIDC permissions. Real publication is being isolated to a guarded main-branch manual-dispatch job using the already-validated artifact. This change still requires final-head review.
The npm account-level trusted-publisher check remains unconfirmed; the precise maintainer-only checklist is recorded in #385. No issues are being manually closed and no PRs/packages are being merged or published by this coordination.
jderochervlk commentedon Nov 7, 2026
All three batch PRs are now open as drafts:
main.agent/alpha-tooling-release(build(webapi): fix alpha installs and release checks [Codex] #397).agent/alpha-binding-contracts(fix(webapi): correct browser API types and calls [Codex] #399) so migration notes/examples can be verified against the actual corrected public API.The intended final review/landing order is tooling -> bindings -> docs. Each author remains responsible for resolving independent review findings and documenting issue acceptance on the final combined head. Draft status is intentional; CI success is not being treated as completion of all review/acceptance work.
The reported CustomElementRegistry documentation-build failure was isolated: the direct compiler-doc command and sequential full docs rebuild pass, as do the binding PR's CI/Release checks. The earlier attempt overlapped operations sharing generated build state; no public-module exclusion or documentation parser workaround is planned on that evidence.
No automatic landing/publication is authorized. The external npm Trusted Publisher confirmation in #385 remains a maintainer gate.
jderochervlk commentedon Nov 8, 2026
Implementation and independent-review follow-through are complete for the code stack. Live GitHub checks confirm all three PRs are ready for review, with CI
buildand Releasevalidatesuccessful; real publication and deployment were skipped.ebe4fcac0e9ca68eb4b62f7209be8cf2e173fa95(identical source tree to the independently reviewed foundation)0b4642539c9a41d9e2aa53c3278a9e6850d7a744fd007c8d4a6d6ef9d1b6d4ebac4c7e26cc73ac11Independent review findings were addressed by the implementation authors; their issue-by-issue acceptance reports and final-head supplements are on the PRs. These are agent review comments, not formal maintainer approvals.
Closing-reference ownership is being finalized without changing code: #397 covers #384/#396; #399 covers #386/#389; #398 completes the cross-stack docs/testing acceptance for #383/#387/#388/#390/#391/#392 plus #393/#394/#395. Those issues remain open until authorized landing; no manual closures are being performed.
Remaining external release gate: #385 still requires maintainer confirmation of npm Trusted Publishing and eventual provenance verification. Its repository machinery and runbook are implemented, but no real package was published. See the existing precise npm-settings checklist in #385.
The PRs are stacked. Land/review in the order above and ensure each child is retargeted appropriately after its parent lands; no merge, package publication, tag, settings change, or milestone closure has been authorized or performed by this coordination.
jderochervlk commentedon Nov 8, 2026
All three PRs have reached main: #399 was included through #397, followed by #398. Thirteen of the fourteen required sub-issues are complete. #386 and #389 are now closed after verifying their landed code and regression coverage; the other completed issues closed with the PRs.
Main is 844c32af. Main CI and the documentation deployment passed. Its full Git tree is identical to the previously validated docs head
7d92df25024356458fd8c2e940c3dab970b01995; release validation and the exact-package dry-run passed on that tree. The checklist now reflects this evidence.Keeping this tracker and the milestone open. #385 still needs npm Trusted Publishing confirmation. An authorized release must also create the matching tag/release, publish
1.0.0-alpha.1toalpha, and verify the published package, provenance and unchangedlatesttag. The registry still pointsalphaat0.1.0-alpha-b1d58f9. No package, tag or release was created during this issue cleanup.jderochervlk commentedon Nov 8, 2026
The requested follow-up privacy policy and implementation plan are now tracked in #403. It covers private backing types and public re-exports for native objects, a supported mutation path, and construction-rejection tests, while preserving caller-created options and initializer records. PR #402 is being updated to explicit record re-exports without changing existing privacy. #403 remains a separate follow-up, not an automatic addition to this alpha milestone.