Update ext/wasm/api/README.md for recent changes.

FossilOrigin-Name: 03b70686939e5f9ad984220a31674c23a1beb19f040c6327f24e23f0378555da

ext/wasm/api/README.md

@@ -2,7 +2,7 @@
 
 This is the README for the files `sqlite3-*.js` and
 `sqlite3-wasm.c`. This collection of files is used to build a
-single-file distribution of the sqlite3 WASM API. It is broken into
+single-file distribution of the sqlite3 JS/WASM API. It is broken into
 multiple JS files because:
 
 1. To facilitate including or excluding certain components for
@@ -12,16 +12,19 @@ multiple JS files because:
 2. To facilitate modularizing the pieces for use in different WASM
    build environments. e.g. the files `post-js-*.js` are for use with
    Emscripten's `--post-js` feature, and nowhere else.
+   As-yet-hypothetical comparable toolchains would necessarily have
+   similar facilities.
 
 3. Certain components must be in their own standalone files in order
    to be loaded as JS Workers.
 
 The structure described here is the current state of things, as of
 this writing, but is not set in stone forever and may change at any
-time.
+time. This doc targets maintainers of this code and those wanting to
+dive in to the details, not end user.
 
 The overall idea is that the following files get concatenated
-together, in the listed order, the resulting file is loaded by a
+together, in the listed order, and the resulting file is loaded by a
 browser client:
 
 - **`sqlite3-api-prologue.js`**\  
@@ -50,10 +53,10 @@ browser client:
 - **`sqlite3-api-glue.js`**\  
   Invokes functionality exposed by the previous two files to flesh out
   low-level parts of `sqlite3-api-prologue.js`. Most of these pieces
-  involve populating the `sqlite3.capi.wasm` object. This file also
-  deletes most global-scope symbols the above files create,
-  effectively moving them into the scope being used for initializing
-  the API.
+  involve populating the `sqlite3.capi.wasm` object and creating
+  `sqlite3.capi.sqlite3_...()` bindings. This file also deletes most
+  global-scope symbols the above files create, effectively moving them
+  into the scope being used for initializing the API.
 - **`<build>/sqlite3-api-build-version.js`**\  
   Gets created by the build process and populates the
   `sqlite3.version` object. This part is not critical, but records the
@@ -117,21 +120,18 @@ browser client:
 
 **Files with the extension `.c-pp.js`** are intended [to be processed
 with `c-pp`](#c-pp), noting that such preprocessing may be applied
-after all of the relevant files are concatenated. That extension is
-used primarily to keep the code maintainers cognisant of the fact that
-those files contain constructs which may not run as-is in any given
-JavaScript environment.
+after all of the relevant files are concatenated. The `.c-pp.js`
+extension is used primarily to keep the code maintainers cognisant of
+the fact that those files contain constructs which may not run as-is
+in any given JavaScript environment.
 
 The build process glues those files together, resulting in
-`sqlite3-api.js`, which is everything except for the
-`pre/post-js-*.js` files, and `sqlite3.js`, which is the
-Emscripten-generated amalgamated output and includes the
-`pre/post-js-*.js` parts, as well as the Emscripten-provided module
-loading pieces.
+`sqlite3-api.js`, which is everything except for the Emscripten-specific
+files detailed below (into which `sqlite3-api.js` gets injected).
 
 The non-JS outlier file is `sqlite3-wasm.c`: it is a proxy for
-`sqlite3.c` which `#include`'s that file and adds a couple more
-WASM-specific helper functions, at least one of which requires access
+`sqlite3.c` which `#include`'s that file and adds a handful of
+WASM-specific helper functions, at least two of which requires access
 to private/static `sqlite3.c` internals. `sqlite3.wasm` is compiled
 from this file rather than `sqlite3.c`.
 
@@ -144,21 +144,26 @@ build-generated `sqlite3.js` along with `sqlite3-api.js`.
   purposes and holds no code relevant to the production deliverables.
 - **`pre-js.c-pp.js`**\  
   Emscripten-specific header for Emscripten's `--pre-js` flag. This
-  file is intended as a place to override certain Emscripten behavior
-  before it starts up, but corner-case Emscripten bugs keep that from
-  being a reality.
+  file overrides certain Emscripten behavior before Emscripten does
+  most of its work.
 - **`post-js-header.js`**\  
-  Emscripten-specific header for the `--post-js` input. It opens up
-  a lexical scope by starting a post-run handler for Emscripten.
+  Emscripten-specific header for the `--post-js` input. It opens up,
+  but does not close, a function.
+- (**`sqlite3-api.js`** gets sandwiched between these &uarr; two
+  &darr; files.)
 - **`post-js-footer.js`**\  
   Emscripten-specific footer for the `--post-js` input. This closes
-  off the lexical scope opened by `post-js-header.js`.
+  off the function opened by `post-js-header.js`.
 - **`extern-post-js.c-pp.js`**\  
   Emscripten-specific header for Emscripten's `--extern-post-js`
-  flag. This file overwrites the Emscripten-installed
-  `sqlite3InitModule()` function with one which, after the module is
-  loaded, also initializes the asynchronous parts of the sqlite3
-  module. For example, the [OPFS][] VFS support.
+  flag. This file is run in the global scope. It overwrites the
+  Emscripten-installed `sqlite3InitModule()` function with one which
+  first runs the original implementation, then runs the function
+  installed by `post-js-header/footer.js` to initialize the library,
+  then initializes the asynchronous parts of the sqlite3 module (for
+  example, the [OPFS][] VFS support). Its final step is to return a
+  Promise of the sqlite3 namespace object to the caller of
+  `sqlite3InitModule()` (the library user).
 
 <a id='c-pp'></a>
 Preprocessing of Source Files

manifest

@@ -1,5 +1,5 @@
-C Cleanups\sand\sdocs\sin\sthe\sinternal\sparts\sof\sthe\sJS\slib\sbootstrapping.\sMore\stinkering\swith\sthe\scustom\s(but\sstill\sdisabled)\swasm\sfile\sloader.
-D 2025-09-22T17:29:52.547
+C Update\sext/wasm/api/README.md\sfor\srecent\schanges.
+D 2025-09-22T18:05:10.957
 F .fossil-settings/binary-glob 61195414528fb3ea9693577e1980230d78a1f8b0a54c78cf1b9b24d0a409ed6a x
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
@@ -590,7 +590,7 @@ F ext/wasm/api/EXPORTED_FUNCTIONS.sqlite3-core e5cf4fa7610a09d51017d75faf50be381
 F ext/wasm/api/EXPORTED_FUNCTIONS.sqlite3-extras cb4fa8842c875b6ee99381523792975c5ebb7371bd27fbd1bd863a43c7f3505a
 F ext/wasm/api/EXPORTED_FUNCTIONS.sqlite3-see fb29e62082a658f0d81102488414d422c393c4b20cc2f685b216bc566237957b
 F ext/wasm/api/EXPORTED_RUNTIME_METHODS.sqlite3-api 1ec3c73e7d66e95529c3c64ac3de2470b0e9e7fbf7a5b41261c367cf4f1b7287
-F ext/wasm/api/README.md 7f029c5fe83b3493931d2fb915e2febd3536267d538a56408a6fef284ea38d29
+F ext/wasm/api/README.md 5fc27524cae0851ba577859dc464e432f2de8a633c30927d29e81b6904e699d5
 F ext/wasm/api/extern-post-js.c-pp.js 36181698fa0a8dba6292d0659c8945941f7794d632883bd335c4a7c7d2981555
 F ext/wasm/api/extern-pre-js.js cc61c09c7a24a07dbecb4c352453c3985170cec12b4e7e7e7a4d11d43c5c8f41
 F ext/wasm/api/post-js-footer.js e617e5f81a907362de152576323155f02d24642e625fc05fb801b86b6a269444
@@ -2175,8 +2175,8 @@ F tool/version-info.c 3b36468a90faf1bbd59c65fd0eb66522d9f941eedd364fabccd7227350
 F tool/warnings-clang.sh bbf6a1e685e534c92ec2bfba5b1745f34fb6f0bc2a362850723a9ee87c1b31a7
 F tool/warnings.sh 1ad0169b022b280bcaaf94a7fa231591be96b514230ab5c98fbf15cd7df842dd
 F tool/win/sqlite.vsix deb315d026cc8400325c5863eef847784a219a2f
-P 3e7ede2e6dc9ac8e746dafe0ecb5379044631e753e951f9ab97ec84addbd830a
-R 470af61e633781a34c9404de25c82545
+P 35651d9ab5529da915500fc50ca3833a004d0b7a19d98e8fbf39234d94697aec
+R 452146c528c5b88da8bcc9faecddbf7e
 U stephan
-Z 415b84aa6c95cbcde807602afc8a1e9e
+Z 3d212d42a59ec4f93d36bc8b774364d4
 # Remove this line to create a well-formed Fossil manifest.

manifest.uuid

@@ -1 +1 @@
-35651d9ab5529da915500fc50ca3833a004d0b7a19d98e8fbf39234d94697aec
+03b70686939e5f9ad984220a31674c23a1beb19f040c6327f24e23f0378555da