Rename overloaded constructor bindings from numbered make* names to semantic from* names

Inizia da docs/superpowers/plans/2026-04-18-constructor-make-rename-plan.md e dall’ordine di rollout, cominciando da src/FileAPI.res e src/FileAPI/ReadableStream.res. Passa in rassegna i file sorgente dei constructor indicati e aggiungi i moduli di compile-coverage corrispondenti sotto tests/, inclusi gli snapshot JavaScript sottoposti a commit. Il lavoro è completo quando npm run build, npm run test, npm run build:docs e npm run format:check vengono eseguiti correttamente senza differenze negli artefatti generati.

Summary

Rename overloaded constructor bindings from numbered make* names to semantic from* names, while keeping singleton and true default constructors named make. This pass should also update constructor source comments so generated API docs describe each overload's input shape, add compile-coverage tests for every renamed constructor, and update contributor docs with the constructor naming and documentation rules.

Plan source: docs/superpowers/plans/2026-04-18-constructor-make-rename-plan.md

Context from PR #234

PR #234 (Rename a few bindings with a proper descriptive naming) is the prior rename pass for this area. It was authored against the pre-*API module layout, so treat paths like src/DOM/* and src/WebSockets/* in that PR as earlier equivalents of the current src/DOMAPI/* and src/WebSocketsAPI/* files.

Use PR #234 as source material only for the overlapping constructor families in this issue:

• FontFace: make2 -> fromDataView, make3 -> fromArrayBuffer, but the string constructor stayed make
• VideoFrame: make2 through make10 were renamed, but the HTML image constructor stayed make and several names were shorter than the source-type names this issue wants (fromSvgImage, fromVideoElement, fromCanvasElement)
• MediaStream: make2 -> fromStream, make3 -> fromTracks
• Path2D: make2 -> fromString, but the default constructor and copy constructor were not split
• DOMMatrix / DOMMatrixReadOnly: make2 -> fromFloatArray, but the string overload stayed merged into make
• OfflineAudioContext: make2 -> makeWithParams
• WebSocket: make2 -> makeWithProtocols
• ReadableStream: make2 and make3 were removed instead of being remodeled as typed constructors

This issue intentionally supersedes the constructor naming choices from PR #234 where they do not match the make / from* rules:

• rename non-default constructors still called make
• prefer source-type names such as fromMediaStream, fromURL, fromURLWithProtocols, fromHTMLVideoElement, fromString, and fromArray
• split optional-argument constructors into a true make() plus typed from* overloads
• keep the non-constructor overload renames from PR #234 out of scope here

Rules to enforce

• Keep singleton constructors named make.
• Keep true default constructors named make, even inside overloaded families.
• Rename typed constructor overloads in overloaded families to from* names based on the source input type.
• Do not change existing makeWith* constructors in this pass.
• If an optional labeled argument currently hides the default constructor, split it into a real make plus typed from* overloads.

Scope

Rename pure overload families

• src/CSSFontLoadingAPI/FontFace.res
  • fromString
  • fromDataView
  • fromArrayBuffer
• src/DOMAPI/VideoFrame.res
  • fromHTMLImageElement
  • fromSVGImageElement
  • fromHTMLVideoElement
  • fromHTMLCanvasElement
  • fromImageBitmap
  • fromOffscreenCanvas
  • fromVideoFrame
  • fromArrayBuffer
  • fromSharedArrayBuffer
  • fromDataView
• src/WebSocketsAPI/WebSocket.res
  • fromURL
  • fromURLWithProtocols
• src/WebAudioAPI/OfflineAudioContext.res
  • fromOptions
  • fromChannelCountLengthAndSampleRate

Update mixed default-plus-typed families

• src/MediaCaptureAndStreamsAPI/MediaStream.res
  • keep make() as the default constructor
  • rename typed overloads to fromMediaStream and fromTracks
• src/FileAPI.res
  • add type underlyingSource<'t> = any near the existing stream support types
• src/FileAPI/ReadableStream.res
  • make make generic: unit => readableStream<'t>
  • rename typed overloads to fromUnderlyingSource and fromUnderlyingSourceWithStrategy

Split constructor bindings that currently hide the default constructor

• src/CanvasAPI/Path2D.res
  • split into make(), fromPath2D(~path), fromString(~path)
• src/DOMAPI/DOMMatrix.res
  • split into make(), fromString(~init), fromArray(~init)
• src/DOMAPI/DOMMatrixReadOnly.res
  • split into make(), fromString(~init), fromArray(~init)

Documentation

• Rewrite every touched constructor comment to use the final function name in the signature line and example.
• Add a Source shape: block for every touched constructor comment.
• Include MDN links for the input type.
• Include ReScript stdlib links when the source input is a stdlib type such as string, array<'a>, ArrayBuffer.t, or DataView.t.
• Include local source links when the shape is a project-local record or alias.
• Preserve the existing constructor-level MDN link in each comment.
• Update docs/content/docs/contributing/api-modelling.mdx with a constructor-overload subsection covering make vs from* naming and overload splitting.
• Update docs/content/docs/contributing/documentation.mdx so the documented comment structure explicitly includes source-shape links and shows a constructor overload example.
• Do not hand-edit docs/pages/apidocs/**; those pages are template-driven from source comments.

Tests and generated artifacts

• Add compile-coverage test modules for:
  • tests/CSSFontLoadingAPI/FontFace__test.res
  • tests/DOMAPI/VideoFrame__test.res
  • tests/WebSocketsAPI/WebSocket__test.res
  • tests/WebAudioAPI/OfflineAudioContext__test.res
  • tests/MediaCaptureAndStreamsAPI/MediaStream__test.res
  • tests/FileAPI/ReadableStream__test.res
  • tests/CanvasAPI/Path2D__test.res
  • tests/DOMAPI/DOMMatrix__test.res
  • tests/DOMAPI/DOMMatrixReadOnly__test.res
• Commit the generated tests/**/*.js snapshots for those new coverage modules.
• Do not hand-edit lib/**; it should be regenerated through the normal build.

Verification

• npm run build
• npm run test
• npm run build:docs
• npm run format:check

Expected results:

• build succeeds with the renamed constructors and overload splits
• tests succeed with the new committed .js snapshots and no leftover snapshot diffs
• docs build succeeds with the updated source comments and contributor docs
• format check succeeds after formatting

Out of scope

• adopting Vitest in this pass
• adopting happy-dom in this pass
• replacing the current compile-and-snapshot test flow
• runtime browser-behavior assertions
• updating contributor testing docs for a future runtime harness before that harness exists

Rollout order

• Update ReadableStream support types in src/FileAPI.res first.
• Rename the pure overload families.
• Update the mixed default-plus-typed families.
• Split the optional-argument constructor bindings into true default make plus typed from* overloads.
• Rewrite all touched constructor comments.
• Add compile-coverage tests and generated JS snapshots.
• Update contributor docs.
• Leave a clear note that runtime verification will be handled later via Vitest and happy-dom.
• Run build, test, docs, and format verification.