Flatten unmonorepo public module surface

Author: jderochervlk

docs/content/docs/contributing/api-modelling.mdx

@@ -130,8 +130,7 @@ mutable fillStyle: fillStyle
 When we wish to read and write the `fillStyle` property, we can use a helper module to lift the type to an actual ReScript variant:
 
 export const fillStyleModule = `
-open WebAPI.Canvas
-open WebAPI.DOM
+open WebAPI
 
 external fromString: string => fillStyle = "%identity"
 external fromCanvasGradient: canvasGradient => fillStyle = "%identity"

docs/content/docs/philosophy.mdx

@@ -16,11 +16,10 @@ The bindings are generated from the [MDN Web API documentation](https://develope
 
 In other words, if you are searching for a specific JavaScript binding, begin your journey at the [MDN Web API documentation](https://developer.mozilla.org/en-US/docs/Web/API) and determine which module contains your sample. Ensure that the module is available in the bindings by checking the specific API. Please [open an issue](https://github.com/rescript-lang/experimental-rescript-webapi/issues/new/choose) if you require an API that is not yet present.
 
-The bindings are exposed under the `WebAPI` namespace, with feature entry modules such as `WebAPI.DOM` available when you want to scope imports more narrowly.
+The bindings are exposed under the `WebAPI` namespace with the same flat module structure as the original package.
 
 ```ReScript
-open WebAPI.Global
-// or WebAPI.DOM
+open WebAPI.DomGlobal
 
 let myElement: WebAPI.Element.t = document->WebAPI.Document.createElement("div")
 ```
@@ -44,8 +43,7 @@ JavaScript supports function overloads, where a function can have multiple signa
 In some cases, type conversion will be required. Subtypes can safely be cast to their base type using conversion helpers within their module.
 
 ```ReScript
-open WebAPI.Global
-// or WebAPI.DOM
+open WebAPI.DomGlobal
 
 let element: WebAPI.Element.t = document->WebAPI.Document.createElement("div")
 let node: WebAPI.Node.t = element->WebAPI.Element.asNode

docs/llm.js

@@ -2,7 +2,7 @@ import * as path from "node:path";
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
 import fs from "node:fs/promises";
-import { featureSpecs, publicNameForLeafModule } from "../scripts/unmonorepo/feature-spec.mjs";
+import { featureSpecs } from "../scripts/unmonorepo/feature-spec.mjs";
 
 const execAsync = promisify(exec);
 
@@ -107,11 +107,7 @@ function moduleNameForFile(relativePath) {
 
   const leafName = path.basename(fileName, ".res");
 
-  if (leafName === spec.publicModule) {
-    return `WebAPI.${spec.publicModule}`;
-  }
-
-  return `WebAPI.${spec.publicModule}.${publicNameForLeafModule(leafName, spec.internalPrefix)}`;
+  return `WebAPI.${leafName}`;
 }
 
 const pattern = "../src/*/**/*.res";

docs/superpowers/specs/2026-04-22-unmonorepo-webapi-design.md

@@ -7,16 +7,16 @@
 
 The repository was split into npm workspaces so each Web API area could build and publish independently from `packages/*`. The ReScript compiler now supports feature-gated source directories and feature-gated dependencies, so the package split is no longer required to support partial builds.
 
-The new target is a single published npm package, `@rescript/webapi`, with a unified internal build and an external API that still preserves feature-level boundaries such as `WebAPI.DOM`, `WebAPI.Fetch`, and `WebAPI.Base`.
+The new target is a single published npm package, `@rescript/webapi`, with a unified internal build and feature-gated source groups such as `WebAPI.DOM`, `WebAPI.Fetch`, and `WebAPI.Base`.
 
 ## Goals
 
 - Remove the monorepo/workspace package split.
 - Move all feature sources from `packages/<Pkg>/src` to `src/<Pkg>`.
 - Delete every subpackage `package.json` and `rescript.json`.
 - Make the root `rescript.json` the single source of truth for sources, features, and ReScript dependencies.
-- Preserve the logical public API boundaries as `WebAPI.<Feature>`.
-- Keep internal helper modules private through the new `public` source setting.
+- Preserve the original flat public API module shape.
+- Keep feature boundaries in the build configuration rather than generated wrapper modules.
 - Publish one npm package: `@rescript/webapi`.
 - Let internal builds and downstream consumers compile only the features they need.
 
@@ -62,14 +62,12 @@ Each former package source directory is listed as its own source entry. Example
     {
       "dir": "src/DOM",
       "subdirs": true,
-      "feature": "WebAPI.DOM",
-      "public": ["DOM"]
+      "feature": "WebAPI.DOM"
     },
     {
       "dir": "src/Fetch",
       "subdirs": true,
-      "feature": "WebAPI.Fetch",
-      "public": ["Fetch"]
+      "feature": "WebAPI.Fetch"
     },
     {
       "dir": "tests",
@@ -84,8 +82,7 @@ Rules:
 
 - Every former package gets one root source entry.
 - The `feature` value matches the public module name, for example `"WebAPI.DOM"` and `"WebAPI.Fetch"`.
-- The `public` list exposes only the feature entry module for that source directory.
-- Helper modules such as `DomTypes` and `DomGlobal` stay internal because they are not listed in `public`.
+- Source directories expose their modules directly, matching the original plain package structure.
 - `tests` remains a dev-only source.
 
 ### Dependencies
@@ -112,23 +109,22 @@ Migration rule:
 
 ## Public API Shape
 
-The public API remains feature-oriented:
+The build remains feature-oriented:
 
 - `WebAPI.Base`
 - `WebAPI.DOM`
 - `WebAPI.Fetch`
 - `WebAPI.WebCrypto`
 - and the rest of the former package surfaces
 
-The unified build must not expose raw internal file modules as first-class public API. Consumers should interact with a curated surface through the feature entry modules only.
+The unified build keeps the original flat module surface instead of adding generated feature entry modules. For example, consumers should use modules such as:
 
-Each feature directory therefore needs one public entry module whose filename matches the feature name:
+- `WebAPI.Document`
+- `WebAPI.Element`
+- `WebAPI.Headers`
+- `WebAPI.URL`
 
-- `src/DOM/DOM.res`
-- `src/Fetch/Fetch.res`
-- `src/Base/Base.res`
-
-Those entry modules are the only modules exported from their source directory through `public`.
+Shared DOM base types should be owned by `DOM`, so common references stay short, for example `DOM.element` instead of `BaseDOM.element` or `Base.DOM.element`.
 
 ## Internal Module Naming
 
@@ -144,6 +140,7 @@ In a unified package these names would collide, so the migration must rename gen
 
 Examples:
 
+- `src/Base/DOM.res` -> `src/Base/DOM.res`
 - `src/DOM/Types.res` -> `src/DOM/DomTypes.res`
 - `src/DOM/Global.res` -> `src/DOM/DomGlobal.res`
 - `src/Fetch/Global.res` -> `src/Fetch/FetchGlobal.res`
@@ -153,7 +150,7 @@ Examples:
 Naming rule:
 
 - Prefix internal modules with the feature’s public module stem.
-- Keep the public entry module itself unprefixed when it is the exported surface module, for example `DOM.res` and `Fetch.res`.
+- Keep legacy same-name public modules unprefixed when the feature owns that name, for example `src/URL/URL.res`, `src/Event/Event.res`, and `src/File/File.res`.
 
 This keeps the public API stable while making the unified internal module graph collision-free.
 
@@ -196,8 +193,7 @@ The build becomes unified at the repository level:
 1. ReScript reads the root `rescript.json`.
 2. Each feature source directory is included in the build graph.
 3. Feature gating determines which source directories and gated dependencies participate in a given build.
-4. Only the explicitly public feature entry modules are exposed to consumers.
-5. Internal helper modules remain compile-time implementation details.
+4. The original flat public modules are exposed directly to consumers.
 
 This provides one coherent package without losing the ability to compile narrower slices of the API surface.
 
@@ -240,4 +236,4 @@ The most important regression risks are:
 - Use `WebAPI.*` spelling, not `WebApi.*`.
 - Map feature names to public module names such as `"WebAPI.DOM"`.
 - Rename generic internal modules to feature-qualified names.
-- Use source-level `public` settings so only the feature entry module is exposed.
+- Keep feature-gated source directories, but do not generate feature entry modules.

docs/utils.js

@@ -3,7 +3,7 @@ import { exec } from "node:child_process";
 import { promisify } from "node:util";
 import { readdirSync, existsSync, readFileSync } from "fs";
 import { micromark } from "micromark";
-import { featureSpecs, publicNameForLeafModule } from "../scripts/unmonorepo/feature-spec.mjs";
+import { featureSpecs } from "../scripts/unmonorepo/feature-spec.mjs";
 
 const execAsync = promisify(exec);
 
@@ -32,15 +32,14 @@ function mapTypeModules(parentModuleLink, file, spec) {
   }
 
   const typesFileName = `${spec.internalPrefix}Types.res`;
-  const entryFileName = `${spec.publicModule}.res`;
   const files = readdirSync(folder);
   return files
-    .filter((f) => f.endsWith(".res") && f !== typesFileName && f !== entryFileName)
+    .filter((f) => f.endsWith(".res") && f !== typesFileName)
     .map((file) => {
       const filePath = path.join(folder, file);
 
       const leafName = file.replace("$", "").replace(".res", "");
-      const moduleName = publicNameForLeafModule(leafName, spec.internalPrefix);
+      const moduleName = leafName;
       const apiRouteParameter = toKebabCase(moduleName);
       const link = createTypeModuleLink(parentModuleLink, moduleName);
       const typeName = moduleName[0].toLocaleLowerCase() + moduleName.slice(1);