.d.ts: decorate wasm-bindgen output with emscripten factory shape

Replaces the parked emcc --emit-tsd + textual-merge plumbing with a
direct decoration approach. wasm-pack appends a small EmscriptenRuntime
interface, a `MainModule = EmscriptenRuntime & BindgenModule`
intersection, and a default-exported factory declaration to the
wasm-bindgen-generated .d.ts.

The decoration makes `import M from "./<name>.mjs"` type-check cleanly
without depending on emcc's TSD generator (which currently asserts on
wasm-bindgen-style multi-value returns) or any upstream emcc PR. For a
pure-Rust wasm-pack package the TS surface is fully knowable to us:
wasm-bindgen owns the exports, emcc's runtime is a small curated set,
and there's no user C/C++ to type. Users who need additional emscripten
runtime members typed can extend the .d.ts after the build.

Drops emcc_post_link's emit_tsd parameter, the merge_emscripten_and_bindgen_dts
helper, and the parked code path in step_emcc_post_link. Adds an
integration test that asserts the decoration's shape.

Author: guybedford

docs/src/emscripten-target.md

@@ -132,11 +132,14 @@ A few things differ from the default wasm-pack target:
 - **`wasm-pack test` is not supported.** The `wasm-bindgen-test` runner
   isn't currently wired up for emscripten; tests must run via
   `cargo test` directly.
-- **TypeScript declarations come from wasm-bindgen only.** emcc's
-  `--emit-tsd` mode currently asserts on wasm-bindgen-style multi-value
-  returns (any Rust function returning `String`, `Vec`, etc.). The `.d.ts`
-  in `pkg/` describes the wasm-bindgen surface but does not type
-  emscripten runtime methods.
+- **TypeScript declarations are wasm-bindgen-driven and wasm-pack-decorated.**
+  The `.d.ts` in `pkg/` is wasm-bindgen's output (covering every
+  `#[wasm_bindgen]` export and class) decorated with a `MainModule`
+  intersection type and a default-export factory declaration so
+  `import M from "./<name>.mjs"` type-checks cleanly. A small curated
+  `EmscriptenRuntime` interface surfaces the heap views and
+  `_initialize`. If you need more of emscripten's runtime typed (for C/C++
+  interop, FS, etc.) extend the `.d.ts` in `pkg/` after the build.
 - **Optimization is capped at `-O2`.** emcc's `-O3` enables wasm-opt's
   `--minify-imports-and-exports` pass, which renames wasm exports to
   single letters — but wasm-bindgen's generated JS glue references the

src/command/build.rs

@@ -709,31 +709,32 @@ impl Build {
             emcc_opt_level_for(&self.profile)
         };
 
-        // TODO: re-enable emcc's `--emit-tsd` once
-        // https://github.com/emscripten-core/emscripten (TSD multi-value PR)
-        // lands. emcc currently asserts in its TSD generator on any wasm
-        // function with multiple return values, and wasm-bindgen emits
-        // those for every Rust-side String / Vec / Result / struct
-        // return. The merge code path (`merge_emscripten_and_bindgen_dts`)
-        // is kept ready below — flip `emscripten_dts` from `None` to
-        // `Some(...)` once emcc cooperates and the merge will produce a
-        // union `.d.ts` describing both EmscriptenModule and BindgenModule.
-        let emscripten_dts: Option<PathBuf> = None;
-        let _ = (
-            &bindgen_dts,
-            merge_emscripten_and_bindgen_dts as fn(&Path, &Path) -> Result<()>,
-        );
-
+        // We deliberately don't ask emcc for `--emit-tsd`. For a pure-Rust
+        // wasm-pack package the TS surface is fully knowable to us:
+        // wasm-bindgen owns the user-facing exports (already typed in its
+        // own .d.ts), and emcc's runtime surface is a small curated set
+        // wasm-pack chooses to expose. emcc's TSD would only add value if
+        // we linked arbitrary C/C++ exports, which the wasm-pack flow
+        // doesn't support today. Avoiding it also sidesteps the emcc
+        // assertion on wasm-bindgen-style multi-value-return exports.
         emcc_post_link(
             &in_wasm,
             &in_library,
             &out_js,
-            emscripten_dts.as_deref(),
             &post_link_settings,
             opt_level,
         )?;
         info!("emcc --post-link produced {out_js:?}.");
 
+        // Decorate wasm-bindgen's bare .d.ts with the emscripten-shaped
+        // factory: an `EmscriptenRuntime` interface for the runtime members
+        // we surface, a `MainModule` intersection type, and a default-export
+        // factory declaration. After this `import M from "./<name>.mjs"`
+        // type-checks against the produced module.
+        if !self.disable_dts && bindgen_dts.exists() {
+            decorate_bindgen_dts_for_emscripten(&bindgen_dts)?;
+        }
+
         // Clean up intermediate artifacts that shouldn't ship in pkg/.
         // `_bg.wasm` (pre-post-link) is superseded by the post-linked
         // `<name>.wasm`; `library_bindgen.js` was a build-time-only DSL file.
@@ -1106,18 +1107,10 @@ fn emcc_opt_level_for(profile: &BuildProfile) -> &'static str {
 
 /// Invoke `emcc --post-link` to merge the wasm-bindgen output with
 /// emscripten's standard JS runtime, producing the final JS module.
-///
-/// If `emit_tsd` is supplied, emcc also tries to emit an EmscriptenModule
-/// `.d.ts` to that path. Currently emcc's TSD generator asserts on
-/// wasm-bindgen-style multi-value returns, so the file may not be
-/// produced — we leave it as best-effort and rely on
-/// `merge_emscripten_and_bindgen_dts` to fall back gracefully when the
-/// file is missing.
 fn emcc_post_link(
     in_wasm: &Path,
     in_library: &Path,
     out_js: &Path,
-    emit_tsd: Option<&Path>,
     settings: &EmccPostLinkSettings,
     opt_level: &str,
 ) -> Result<()> {
@@ -1134,9 +1127,6 @@ fn emcc_post_link(
     if settings.source_phase_imports {
         cmd.arg("-sSOURCE_PHASE_IMPORTS=1");
     }
-    if let Some(tsd) = emit_tsd {
-        cmd.arg("--emit-tsd").arg(tsd);
-    }
     cmd.arg("-o").arg(out_js);
 
     let status = cmd.status().context("running emcc --post-link")?;
@@ -1146,43 +1136,62 @@ fn emcc_post_link(
     Ok(())
 }
 
-/// Fuse emscripten's `EmscriptenModule` typings with wasm-bindgen's
-/// `BindgenModule` typings into a single `.d.ts` written at `bindgen_dts`
-/// (overwriting it in place).
+/// Append the emscripten factory shape to wasm-bindgen's `.d.ts`.
 ///
-/// emcc's `--emit-tsd` output ends with:
-///   ```ts
-///   export type MainModule = EmscriptenModule;
-///   ```
-/// We strip that line, append wasm-bindgen's typings, and replace it with
-/// an intersection:
-///   ```ts
-///   export type MainModule = EmscriptenModule & BindgenModule;
-///   ```
-/// so consumers see a single typed factory covering both surfaces.
-fn merge_emscripten_and_bindgen_dts(emscripten_dts: &Path, bindgen_dts: &Path) -> Result<()> {
-    let em_src = std::fs::read_to_string(emscripten_dts)
-        .with_context(|| format!("reading emscripten .d.ts at {emscripten_dts:?}"))?;
-    let bg_src = std::fs::read_to_string(bindgen_dts)
-        .with_context(|| format!("reading bindgen .d.ts at {bindgen_dts:?}"))?;
+/// wasm-bindgen's emscripten-mode output emits an unexported
+/// `interface BindgenModule { ... }` and a sibling class export per
+/// `#[wasm_bindgen] pub struct`, but doesn't declare the default-exported
+/// module factory that emscripten's `-sMODULARIZE -sEXPORT_ES6` emits in
+/// the JS. Without this decoration, `import M from "./<name>.mjs"`
+/// type-checks against `any`.
+///
+/// We append:
+///
+/// ```ts
+/// export interface EmscriptenRuntime {
+///   // small curated set of emscripten-runtime members
+/// }
+/// export type MainModule = EmscriptenRuntime & BindgenModule;
+/// declare function ModuleFactory(opts?: object): Promise<MainModule>;
+/// export default ModuleFactory;
+/// ```
+///
+/// The runtime members we surface are the ones realistic consumers reach
+/// for (heap views, `_initialize`, optional `ccall`/`cwrap`). emcc's full
+/// runtime is much larger; we deliberately don't enumerate everything
+/// since that would commit us to tracking emcc's evolution.
+fn decorate_bindgen_dts_for_emscripten(bindgen_dts: &Path) -> Result<()> {
+    const DECORATION: &str = r#"
+
+// --- wasm-pack: emscripten factory shape ---
+// Curated subset of emscripten's MODULARIZE/EXPORT_ES6 runtime surface.
+// Add or remove members as your use case dictates.
+export interface EmscriptenRuntime {
+    HEAP8: Int8Array;
+    HEAPU8: Uint8Array;
+    HEAP16: Int16Array;
+    HEAPU16: Uint16Array;
+    HEAP32: Int32Array;
+    HEAPU32: Uint32Array;
+    HEAPF32: Float32Array;
+    HEAPF64: Float64Array;
+    _initialize?: () => void;
+}
 
-    let mut merged = String::new();
-    for line in em_src.lines() {
-        if line.trim_start().starts_with("export type MainModule") {
-            continue;
-        }
-        merged.push_str(line);
-        merged.push('\n');
-    }
-    merged.push_str("\n// --- wasm-bindgen-generated types ---\n");
-    merged.push_str(&bg_src);
-    if !merged.ends_with('\n') {
-        merged.push('\n');
-    }
-    merged.push_str("\nexport type MainModule = EmscriptenModule & BindgenModule;\n");
+export type MainModule = EmscriptenRuntime & BindgenModule;
+
+declare function ModuleFactory(opts?: object): Promise<MainModule>;
+export default ModuleFactory;
+"#;
 
-    std::fs::write(bindgen_dts, merged)
-        .with_context(|| format!("writing merged .d.ts to {bindgen_dts:?}"))?;
+    let mut existing = std::fs::read_to_string(bindgen_dts)
+        .with_context(|| format!("reading bindgen .d.ts at {bindgen_dts:?}"))?;
+    if !existing.ends_with('\n') {
+        existing.push('\n');
+    }
+    existing.push_str(DECORATION);
+    std::fs::write(bindgen_dts, existing)
+        .with_context(|| format!("writing decorated .d.ts to {bindgen_dts:?}"))?;
     Ok(())
 }
 

tests/all/emscripten.rs

@@ -275,6 +275,43 @@ fn emscripten_package_json_points_at_mjs() {
     );
 }
 
+#[test]
+fn emscripten_dts_is_decorated_with_factory_shape() {
+    skip_without_emcc!();
+    let fixture = utils::fixture::emscripten_hello_world();
+    let mut cmd = fixture.wasm_pack();
+    if let Some(bin) = local_wasm_bindgen_bin() {
+        cmd.env("WASM_BINDGEN_BIN", bin);
+    } else {
+        fixture.install_local_wasm_bindgen();
+    }
+    cmd.arg("build")
+        .arg("--target")
+        .arg("web")
+        .assert()
+        .success();
+
+    let dts = std::fs::read_to_string(fixture.path.join("pkg/em_hello_world.d.ts")).unwrap();
+    // wasm-bindgen's own surface should be present untouched.
+    assert!(
+        dts.contains("interface BindgenModule"),
+        "bindgen-emitted BindgenModule interface should be preserved"
+    );
+    // wasm-pack appends the factory shape on top.
+    for needle in [
+        "export interface EmscriptenRuntime",
+        "HEAPU8: Uint8Array",
+        "export type MainModule = EmscriptenRuntime & BindgenModule",
+        "declare function ModuleFactory(opts?: object): Promise<MainModule>",
+        "export default ModuleFactory",
+    ] {
+        assert!(
+            dts.contains(needle),
+            "expected decorated .d.ts to contain {needle:?}; got:\n{dts}"
+        );
+    }
+}
+
 #[test]
 fn emscripten_test_command_is_rejected() {
     // No emcc gating — this path doesn't actually invoke emcc, just