Source maps applied to wasm binaries

FutureFeatures.md

@@ -148,16 +148,6 @@ instance. However, operators with 32-bit indices and operators with 64-bit
 indices will be given separate names to leave open the possibility of
 supporting both in the same instance in the future.
 
-### Source maps integration
-
-* Add a new source maps [module section type](MVP.md#module-structure).
-* Either embed the source maps directly or just a URL from which source maps can
-  be downloaded.
-* Text source maps become intractably large for even moderate-sized compiled
-  codes, so probably need to define new binary format for source maps.
-* Gestate ideas and start discussions at the
-  [Source Map RFC repository](https://github.com/source-map/source-map-rfc/issues)
-
 ### Coroutines
 
 Coroutines will [eventually be part of C++][] and is already popular in other

Web.md

@@ -299,6 +299,86 @@ Transcoding failure is detected by `decodeURIComponent`, which may throw
 `URIError`. If it does, the WebAssembly module will not validate. This validation
 rule is only mandatory for Web embedding.
 
+## Source Maps for WebAssembly files on the web
+
+### Background
+[Source maps](https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k)
+are a debug-information format used on the web, generated by toolchains that target
+JavaScript, either from other languages (e.g. TypeScript, Emscripten) or from
+JavaScript itself (e.g. Closure, minifiers). A browser that supports source maps
+can display the original source in its developer tools instead of the compiled
+JavaScript that the VM actually executes. It can support setting breakpoints
+specified as source lines, single-stepping through source lines, and showing
+source lines in stack traces; however it cannot support getting or setting
+variables from the original source code because the format is not "full" debug
+info: it only maps locations from the compiled code back to locations in the
+source files (where a generated-code location consists of a line and column
+number, and a source location consists of file, line, and column). Generated
+files use a specially-formatted comment to specify a URL for a source map that
+describes the file.
+
+Source maps can be made to serve the same purpose for WebAssembly binary files,
+allowing parity with asm.js. By re-using an existing standard, browsers can
+take advantage of their existing source map support without having to make
+significant changes to their developer tools.
+
+
+### Alternatives
+
+An alternative method is to specify location mapping information in some way
+other than source maps. For example, it could be encoded directly into the WebAssembly
+binary the way function and local names are written in the "name" section. This
+is more convenient if the VM itself uses the information (for example to
+generate a stack trace). However existing developer tools implementations are
+designed around the source map model of passing a URL from the VM to the dev
+tools code, which fetches and interprets the information. Therefore it is
+expected that it will be much simpler to use "real" source maps than to design
+another format.
+
+Source maps also have known limitations (e.g. source variables cannot be
+described). A complete debug info format will eventually be needed; however the
+intention of this specification is to allow for easy integration with existing
+developer tools implementations in browsers.
+
+
+### Spec
+
+With few exceptions, most aspects of the source map
+[spec](https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/)
+may be applied directly to WebAssembly.
+Because WebAssembly is a binary format (and thus does not have lines and columns, or
+comments per se), some simple reinterpretation of concepts is needed.
+
+#### Locations
+
+Source maps specify how to map a (zero-based) line and column position in
+generated code to a file, line, and column location in the source. For
+WebAssembly binary locations, the line number is always 1, and the column number
+is interpreted as a byte offset into the WebAssembly binary content (this results
+in a more efficient encoding than using the line number instead).
+Source locations are interpreted as in the source map spec.
+
+#### Linking generated code to source maps
+
+When the generated code is JavaScript, it includes a specially-formatted line
+at the end, which is the URL of the associated source map. For WebAssembly, a custom
+section named `"sourceMappingURL"` contains the URL.
+The URL is represented and encoded as defined in the WHATWG
+[URL spec](https://url.spec.whatwg.org).
+If the URL is not absolute, then:
+* If the wasm module is associated with an HTTP response (e.g. the
+compileStreaming or instantiateStreaming
+[APIs](#additional-web-embedding-api) are used), then it is resolved relative to
+the URL of the response.
+* Otherwise it is relative to the page's origin.
+
+For wasm modules with an associated HTTP response (e.g. those using
+the compileStreaming or instantiateStreaming
+[APIs](#additional-web-embedding-api)) the source map URL may also be specified
+using the `SourceMap:` HTTP header as with JavaScript source maps.
+
+
+
 ## Security
 
 WebAssembly's [security](Security.md) model should depend on the