docs(webapi): document alpha and validate docs distribution [Codex]

.github/workflows/ci.yml

@@ -52,6 +52,9 @@ jobs:
       - name: Build documentation
         run: npm run build:docs
 
+      - name: Check documentation links
+        run: npm run check:docs-links
+
       - name: Upload documentation
         uses: actions/upload-pages-artifact@v5
         if: github.ref == 'refs/heads/main' && github.event_name == 'push'

.github/workflows/release.yml

@@ -60,6 +60,9 @@ jobs:
       - name: Build documentation
         run: npm run build:docs
 
+      - name: Check documentation links
+        run: npm run check:docs-links
+
       - name: Validate explicit alpha version and unpublished state
         run: npm run check:release
 

CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+This file records user-visible changes. Alpha releases may contain breaking changes, and
+changes may occur between alpha versions. Version numbers and publication-channel instructions
+are maintained by the release workflow; see the [alpha release readiness tracker](https://github.com/rescript-lang/experimental-rescript-webapi/issues/382).
+
+## 1.0.0-alpha.1 (candidate)
+
+Planned first release in the `1.0.0-alpha.N` series. ReScript `13.0.0-alpha.5` is the tested
+compiler baseline. This alpha is not a stable API; review the migration notes below before
+upgrading from earlier prereleases. The release workflow is the source of truth for actual
+versioning and publication.
+
+### Migration notes
+
+- WebSocket sends and worker `Request` fetches now preserve their native receiver (`this`) rather
+  than calling receiver-bound methods unbound.
+- `WebAPI.Request.bytes`, `WebAPI.Response.bytes`, `WebAPI.Blob.bytes`,
+  `WebAPI.Blob.stream`, and `WebAPI.SafeFetch.bytes` expose
+  native `Uint8Array.t` values or chunks instead of `array<int>`. Use the typed-array API
+  directly; the bytes are not copied into a ReScript integer array.
+- `ResizeObserver` callbacks now receive `(entries, observer)` as two arguments rather than a
+  curried callback.
+- Web Audio analyser float buffers, `AudioBuffer` channel and copy APIs, and Biquad/IIR filter
+  frequency-response buffers use `Float32Array.t`; analyser byte buffers use `Uint8Array.t`.
+  `DOMMatrix` and `DOMMatrixReadOnly` Float32 conversions also use `Float32Array.t`. Use native
+  typed-array values rather than ordinary ReScript arrays for these calls.
+- `Element.closest` returns `Null.t<DOMTree.element>` and is no longer polymorphic. Narrow the
+  result with the relevant public classifier when a more specific HTML interface is required.
+- WebCrypto signatures now reflect native results: `sign` and `digest` return `ArrayBuffer.t`,
+  `verify` returns `bool`, and `deriveKey` returns `WebAPI.SubtleCrypto.cryptoKey`. Key and
+  algorithm support types are available through `WebAPI.SubtleCrypto`.
+- Generic `SubtleCrypto.generateKey` and `generateKey2` now return `unknown` because the result
+  depends on the algorithm. Use `generateKeySymmetric` for HMAC keys
+  (`SubtleCrypto.cryptoKey`) or `generateEcdsaKeyPair` for ECDSA pairs
+  (`SubtleCrypto.cryptoKeyPair`). Generic `exportKey` also returns `unknown`; use
+  `exportKeyBinary` for `Raw`, `Pkcs8`, or `Spki` formats (`ArrayBuffer.t`), and
+  `exportKeyJwk` for `Jwk` format (`JSON.t`).
+- `DOMTree.element` no longer exposes a generic `className`. Specific HTML interfaces retain a
+  string `className`; `SVGElement.t.className` is `SVGElement.svgAnimatedString` with
+  `baseVal` and `animVal`.
+- `CustomElementRegistry.define` takes a `DOM.customElementConstructor`; it does not take an
+  element instance.
+- Request destination, referrer-policy, and media `canPlayType` result types now include `Empty`
+  for native empty-string values. `HTMLCanvasElement.toBlob` callbacks receive a
+  `Null.t<WebAPI.Blob.t>` because the browser can return null (including for a zero-sized
+  canvas). An `ifAvailable` Web Locks callback receives a nullable lock when the lock is
+  unavailable. `IDBFactory.deleteDatabase` has an operation-specific `unit` result because the
+  browser's successful result is `undefined`, not a database.
+- `WebAPI.Notification.t` no longer contains a static permission field. Read that value through
+  `WebAPI.Notification.permission`.
+
+For the intended installation, compiler range, runtime/browser checks, and known limitations,
+see the [project status](https://rescript-lang.github.io/experimental-rescript-webapi/project-status/)
+and [API surface guide](https://rescript-lang.github.io/experimental-rescript-webapi/api-surface/).

README.md

@@ -6,30 +6,49 @@ Experimental successor to [rescript-webapi](https://github.com/TheSpyder/rescrip
 
 ## Getting started
 
-Install the package using your favorite package manager:
+ReScript `13.0.0-alpha.5` is the tested compiler baseline. Library alpha releases may contain
+breaking changes. See the [project status](https://rescript-lang.github.io/experimental-rescript-webapi/project-status/)
+for the accepted peer range and its testing limits.
+
+Install the library and compiler in your application:
 
 ```shell
-npm i @rescript/webapi@alpha
+npm install @rescript/webapi@alpha
+npm install --save-dev rescript@13.0.0-alpha.5
 ```
 
-and add `@rescript/webapi` to your `rescript.json`:
+The `@alpha` command targets the published alpha dist-tag. The planned `1.0.0-alpha.1` candidate
+is not published yet; see [project status](https://rescript-lang.github.io/experimental-rescript-webapi/project-status/)
+for the current tag and note that candidate installation is verified from its packed tarball.
+
+Add a source directory and the package dependency to `rescript.json`:
 
 ```json
 {
-  "dependencies": [
-    "@rescript/webapi"
-  ]
+  "name": "webapi-consumer",
+  "sources": [{ "dir": "src" }],
+  "dependencies": ["@rescript/webapi"]
 }
 ```
 
-## Usage
+In `src/Main.res`:
 
 ```rescript
 let location = WebAPI.DOM.window->WebAPI.Window.location
 let href = location.href
 location->WebAPI.Location.reload
 ```
 
+Compile the consumer with:
+
+```shell
+npx rescript build
+```
+
+The namespace is flat under `WebAPI`; internal implementation modules are not public API.
+
 ## Documentation
 
-More information can be found on https://rescript-lang.github.io/experimental-rescript-webapi/
+More information can be found on https://rescript-lang.github.io/experimental-rescript-webapi/.
+See the [alpha release checklist](https://github.com/rescript-lang/experimental-rescript-webapi/issues/382)
+and [migration notes](CHANGELOG.md) for known limitations and breaking changes.

astro.config.mjs

@@ -2,10 +2,9 @@ import { readFileSync } from "node:fs";
 import { defineConfig } from "astro/config";
 import starlight from "@astrojs/starlight";
 import { apiModules } from "./docs/utils";
+import { docsBase, docsSite } from "./docs/siteConfig.js";
 
-const rescriptTM = JSON.parse(
-  readFileSync("./docs/assets/rescript.tmLanguage.json", "utf-8"),
-);
+const rescriptTM = JSON.parse(readFileSync("./docs/assets/rescript.tmLanguage.json", "utf-8"));
 
 const apiSidebarItems = apiModules.map(({ moduleName, link }) => ({
   label: moduleName,
@@ -15,8 +14,8 @@ const apiSidebarItems = apiModules.map(({ moduleName, link }) => ({
 export default defineConfig({
   srcDir: "docs",
   publicDir: "docs/public",
-  site: "https://rescript-lang.github.io",
-  base: "experimental-rescript-webapi",
+  site: docsSite,
+  base: docsBase,
   integrations: [
     starlight({
       title: "Experimental WebAPI",
@@ -31,8 +30,7 @@ export default defineConfig({
         },
       ],
       editLink: {
-        baseUrl:
-          "https://github.com/rescript-lang/experimental-rescript-webapi/edit/main/",
+        baseUrl: "https://github.com/rescript-lang/experimental-rescript-webapi/edit/main/",
       },
       sidebar: [
         {
@@ -44,6 +42,9 @@ export default defineConfig({
         {
           slug: "api-surface",
         },
+        {
+          slug: "font-attribution",
+        },
         {
           label: "Examples",
           link: "examples",
@@ -75,7 +76,7 @@ export default defineConfig({
           },
         },
       ],
-      customCss: ["./docs/styles/fonts.css", "./docs/styles/theme.css"],
+      customCss: ["./docs/styles/theme.css"],
       expressiveCode: {
         shiki: {
           langs: [rescriptTM],

docs/components/signatureItem.astro

@@ -1,5 +1,5 @@
 ---
-import { createAPIModuleLink } from "../utils.js";
+import { apiModules, createAPIModuleLink, publicTypeTargets } from "../utils.js";
 const { item, typesInOwnModule } = Astro.props;
 
 let link;
@@ -9,8 +9,18 @@ if (typesInOwnModule && typesInOwnModule.has(item.path)) {
 
 if (item.path.startsWith("WebAPI.")) {
   const paths = item.path.split(".");
-  if (paths.length === 3) {
-    link = `${import.meta.env.BASE_URL}/${createAPIModuleLink(paths[1])}#${paths[2]}`;
+  const moduleName = paths[1];
+  if (
+    paths.length === 3 &&
+    moduleName &&
+    apiModules.some((apiModule) => apiModule.moduleName === moduleName)
+  ) {
+    link = `${import.meta.env.BASE_URL}/${createAPIModuleLink(moduleName)}#${paths[2]}`;
+  } else if (paths.length === 3 && moduleName && paths[2]) {
+    const publicType = publicTypeTargets.get(`${moduleName}.${paths[2]}`);
+    if (publicType) {
+      link = `${import.meta.env.BASE_URL}/${createAPIModuleLink(publicType.moduleName)}#${publicType.typeName}`;
+    }
   }
 }
 

docs/content/docs/api-surface.mdx

@@ -4,11 +4,19 @@ description: A practical summary of how to use the public @rescript/webapi modul
 slug: "api-surface"
 ---
 
-The package exposes browser APIs under the `WebAPI` namespace. In normal application code,
-add the package to `rescript.json`:
+The package exposes browser APIs under the `WebAPI` namespace. ReScript `13.0.0-alpha.5` is
+the tested compiler baseline, and alpha releases may contain breaking changes. See
+[project status](../project-status/) for the accepted peer range and its testing limits, and
+the [migration notes](https://github.com/rescript-lang/experimental-rescript-webapi/blob/main/CHANGELOG.md)
+for API changes.
+
+Install `@rescript/webapi@alpha` and `rescript@13.0.0-alpha.5`, then add the package dependency.
+Feature bundles are optional when consumers need to restrict compiled modules:
 
 ```json
 {
+  "name": "webapi-consumer",
+  "sources": [{ "dir": "src" }],
   "dependencies": ["@rescript/webapi"]
 }
 ```
@@ -24,6 +32,9 @@ let href = location.href
 location->WebAPI.Location.reload
 ```
 
+For the compiler range, alpha compatibility contract, and breaking changes to byte, observer,
+DOM, and crypto types, read the [alpha migration notes](https://github.com/rescript-lang/experimental-rescript-webapi/blob/main/CHANGELOG.md).
+
 ## Public module shape
 
 The public API is flat under `WebAPI`. Use owner modules directly rather than generated