From d25da35e54bae776fbbe91e6a16b8d9ba2caadb4 Mon Sep 17 00:00:00 2001
From: jhugman <jhugman@users.noreply.github.com>
Date: Wed, 16 Oct 2024 13:03:10 +0100
Subject: [PATCH] Documentation III (#125)

Partially fixes #121

This PR completes the baseline documentation (I think).

It adds:

- internals - sketching:
  -  the codegen'd path that the `generate turbo-modules` uses
  - the lifting and lowering path that the generated bindings uses
- callback interfaces and async-callbacks
- contribution guide for documentation.
- miscellaneous typo fixes and refactoring

---------

Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 README.md                                     |  25 +++-
 docs/src/SUMMARY.md                           |  19 ++-
 docs/src/contributing/documentation.md        |  58 ++++++++++
 docs/src/contributing/local-development.md    |   2 +-
 .../guide.md => guides/getting-started.md}    |  14 ++-
 .../pre-installation.md                       |   0
 docs/src/guides/publishing.md                 |  49 ++++++++
 docs/src/idioms/async-callbacks.md            |  48 ++++++++
 docs/src/idioms/callback-interfaces.md        | 108 ++++++++++++++++++
 docs/src/idioms/callbacks.md                  |   1 -
 docs/src/idioms/enums.md                      |   2 +-
 docs/src/idioms/promises.md                   |  66 +++++++----
 docs/src/internals/lifting-and-lowering.md    |  46 ++++++++
 docs/src/internals/rn-codegen.md              |  19 +++
 scripts/run-bootstrap-docs.sh                 |   6 +
 15 files changed, 429 insertions(+), 34 deletions(-)
 create mode 100644 docs/src/contributing/documentation.md
 rename docs/src/{getting-started/guide.md => guides/getting-started.md} (96%)
 rename docs/src/{getting-started => guides}/pre-installation.md (100%)
 create mode 100644 docs/src/guides/publishing.md
 create mode 100644 docs/src/idioms/callback-interfaces.md
 delete mode 100644 docs/src/idioms/callbacks.md
 create mode 100644 docs/src/internals/lifting-and-lowering.md
 create mode 100644 docs/src/internals/rn-codegen.md
 create mode 100755 scripts/run-bootstrap-docs.sh

diff --git a/README.md b/README.md
index a54c9a0b..6eb2acd8 100644
--- a/README.md
+++ b/README.md
@@ -15,11 +15,34 @@ If you're ready to start, then start with [a step-by-step tutorial to make a Rus
 If you're new to uniFFI, then [**the UniFFI user guide**](https://mozilla.github.io/uniffi-rs/latest/)
 or [**the UniFFI examples**](https://github.com/mozilla/uniffi-rs/tree/main/examples#example-uniffi-components) are interesting places to start.
 
+## Why `uniffi-bindgen-react-native`?
+
+- Spend more time writing Typescript and Rust
+- Full compatibility with `uniffi-rs`
+- Your Rust SDK is portable across multiple languages.
+
+### Why not, say WASM, via `wasm-bindgen`?
+
+WASM is an amazing virtual machine however:
+
+- your Rust crate must make alternative arrangements if it needs things that the virtual machine does not offer:
+    - threads and
+    - file access.
+- you need to maintain a separate FFI (this is a temporary issue, solvable by something like uniFFI).
+
+## Who is using `uniffi-bindgen-react-native`?
+
+- [@unomed/react-native-matrix-sdk](https://www.npmjs.com/package/@unomed/react-native-matrix-sdk)
+
+## Prior art and related projects
+
+- [cawfree/react-native-webassembly](https://github.com/cawfree/react-native-webassembly)
+
 ## Contributing
 
 If this tool sounds interesting to you, please help us develop it! You can:
 
-* View the [contributor guidelines](./docs/contributing.md).
+* View the [contributor guidelines](https://jhugman.github.io/uniffi-bindgen-react-native/).
 * File or work on [issues](https://github.com/jhugman/uniffi-bindgen-react-native/issues) here in GitHub.
 <!--
 * Join discussions in the [#uniffi:mozilla.org](https://matrix.to/#/#uniffi:mozilla.org) room on Matrix.
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index e166b03c..7bf8e675 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -4,8 +4,9 @@
 
 # Getting started
 
-- [Before you start](getting-started/pre-installation.md)
-- [Step by step: Make your first library project](getting-started/guide.md)
+- [Before you start](guides/pre-installation.md)
+- [Step by step: Make your first library project](guides/getting-started.md)
+- [Publishing your library project](guides/publishing.md)
 
 # Mapping Rust on to Typescript
 
@@ -15,15 +16,16 @@
 - [Records: Objects without methods](idioms/records.md)
 - [Enums and Tagged Unions](idioms/enums.md)
 - [Errors](idioms/errors.md)
-- [Callback interfaces]()
+- [Callback interfaces](idioms/callback-interfaces.md)
 - [Promises/Futures](idioms/promises.md)
-- [Async Callback interfaces]()
+- [Async Callback interfaces](idioms/async-callbacks.md)
 
 # Contributing
 
 - [Local development](contributing/local-development.md)
-- [Adding or changing generated turbo-module templates](contributing/changing-turbo-module-templates.md)
-- [Changing generated Typescript or C++ templates](contributing/changing-bindings-templates.md)
+- [Turbo-module Templates: Adding or changing](contributing/changing-turbo-module-templates.md)
+- [Documentation: Contributing or reviewing](contributing/documentation.md)
+- [Typescript or C++ templates: Changing](contributing/changing-bindings-templates.md)
 - [Cutting a Release](./contributing/cutting-a-release.md)
 
 # Reference
@@ -34,3 +36,8 @@
 - [Generating a Turbo Module](reference/turbo-module-files.md)
 - [Reserved words](reference/reserved-words.md)
 - [Potential collisions](reference/potential-collisions.md)
+
+# Internals
+
+- [Lifting and lowering](./internals/lifting-and-lowering.md)
+- [NativeModule.ts and Codegen](./internals/rn-codegen.md)
diff --git a/docs/src/contributing/documentation.md b/docs/src/contributing/documentation.md
new file mode 100644
index 00000000..0225a19b
--- /dev/null
+++ b/docs/src/contributing/documentation.md
@@ -0,0 +1,58 @@
+# Contributing or reviewing documentation
+
+A project is only as good as its docs!
+
+The documentation is in [markdown](https://rust-lang.github.io/mdBook/format/markdown.html), and lives in the `docs/src` directory.
+
+You can edit the files directly with a text editor.
+
+## Before you start
+
+The following assumes you have checked out the `uniffi-bindgen-react-native` project and that Rust is installed.
+
+## Install `mdbook`
+
+The docs are produced by [`mdbook`, a static-site generator](https://rust-lang.github.io/mdBook/index.html) written for documenting Rust projects.
+
+`uniffi-bindgen-react-native` uses this with a few plugins. You can install it by opening the terminal and using `cd` to navigate to the project directory, then running the following command:
+
+```sh
+./scripts/run-bootstrap-docs.sh
+```
+
+## Run `mdbook serve`
+
+`mdbook` can now be run from the `docs` directory.
+
+From within the project directory, run the following:
+
+```sh
+cd docs
+mdbook serve
+```
+
+This will produce output like:
+
+```sh
+2024-10-14 12:59:35 [INFO] (mdbook::book): Book building has started
+2024-10-14 12:59:35 [INFO] (mdbook::book): Running the html backend
+2024-10-14 12:59:35 [INFO] (mdbook::book): Running the linkcheck backend
+2024-10-14 12:59:35 [INFO] (mdbook::renderer): Invoking the "linkcheck" renderer
+2024-10-14 12:59:36 [INFO] (mdbook::cmd::serve): Serving on: http://localhost:3000
+2024-10-14 12:59:36 [INFO] (warp::server): Server::run; addr=[::1]:3000
+2024-10-14 12:59:36 [INFO] (warp::server): listening on http://[::1]:3000
+```
+
+## Make some changes
+
+You can edit pages with your text editor.
+
+New pages should be added to the `SUMMARY.md` file so that a) `mdbook` knows about them and b) they ends up in the table of contents.
+
+You can now navigate your browser to [localhost:3000](http://localhost:3000/) to see the changes you've made.
+
+## Pushing these changes back into the project
+
+A normal Pull Request flow is used to push these changes back into the project.
+
+---
diff --git a/docs/src/contributing/local-development.md b/docs/src/contributing/local-development.md
index 9334ac26..418d0903 100644
--- a/docs/src/contributing/local-development.md
+++ b/docs/src/contributing/local-development.md
@@ -2,7 +2,7 @@
 
 ## Pre-installation
 
-This guide is in addition to the [Pre-installation](../getting-started/pre-installation.md) guide.
+This guide is in addition to the [Pre-installation](../guides/pre-installation.md) guide.
 
 ```sh
 git clone https://github.com/jhugman/uniffi-bindgen-react-native
diff --git a/docs/src/getting-started/guide.md b/docs/src/guides/getting-started.md
similarity index 96%
rename from docs/src/getting-started/guide.md
rename to docs/src/guides/getting-started.md
index d4eeaca2..0cfdd8a9 100644
--- a/docs/src/getting-started/guide.md
+++ b/docs/src/guides/getting-started.md
@@ -86,7 +86,6 @@ Opening `package.json` add the following:
 +    "ubrn:android":  "ubrn build android --config ubrn.config.yaml --and-generate",
 +    "ubrn:checkout": "ubrn checkout      --config ubrn.config.yaml",
 +    "ubrn:clean": "rm -Rf cpp/ android/src/main/java ios/ src/Native* src/generated/ src/index.ts*",
-+    "postinstall": "yarn ubrn:checkout && yarn ubrn:android && yarn ubrn:ios",
     "example": "yarn workspace react-native-my-rust-lib-example",
     "test": "jest",
     "typecheck": "tsc",
@@ -136,7 +135,6 @@ Until then, you need to add the dependency to the app's Podfile, in this case `e
 +  # We need to specify this here in the app because we can't add a local dependency within
 +  # the react-native-matrix-rust-sdk
 +  pod 'uniffi-bindgen-react-native', :path => '../../node_modules/uniffi-bindgen-react-native'
-
 ```
 
 ## Step 3: Create the `ubrn.config.yaml` file
@@ -166,6 +164,14 @@ yarn ubrn:checkout
 
 This will checkout the `uniffi-starter` repo into the `rust_modules` directory within your project.
 
+You may want to add to `.gitignore` at this point:
+
+```diff
++# From uniffi-bindgen-react-native
++rust_modules/
++*.a
+```
+
 ## Step 4: Build the Rust
 
 Building for iOS will:
@@ -199,6 +205,10 @@ You can change the targets that get built by adding a comma separated list to th
 yarn ubrn:android --targets aarch64-linux-android,armv7-linux-androideabi
 ```
 
+```admonish warning title="Troubleshooting"
+This won't happen with the `uniffi-starter` library, however a common error is to not enable a `staticlib` crate type in the project's `Cargo.toml`. Instructions on how to do this are given [here](../reference/commandline.md#admonition-note).
+```
+
 ## Step 5: Write an example app exercising the Rust API
 
 Here, we're editing the app file at `example/src/App.tsx`.
diff --git a/docs/src/getting-started/pre-installation.md b/docs/src/guides/pre-installation.md
similarity index 100%
rename from docs/src/getting-started/pre-installation.md
rename to docs/src/guides/pre-installation.md
diff --git a/docs/src/guides/publishing.md b/docs/src/guides/publishing.md
new file mode 100644
index 00000000..52a5de74
--- /dev/null
+++ b/docs/src/guides/publishing.md
@@ -0,0 +1,49 @@
+# Publishing your library project
+
+```admonish warning title="Help wanted"
+I haven't had any experience of publishing libraries for React Native.
+
+I would love some [help with this document](../contributing/documentation.md).
+```
+
+## Binary builds
+
+In order to distribute pre-built packages you will need to add to `.gitignore` the built `.a`:
+
+```diff
+# From uniffi-bindgen-react-native
+rust_modules/
++*.a
+```
+
+but add them back in to the `files` section of `package.json`[^issue121].
+
+[^issue121]: [This advice](https://github.com/jhugman/uniffi-bindgen-react-native/issues/121) is from @Johennes
+
+## Source packages
+
+If asking your users to compile Rust source is acceptable, then adding a `postinstall` script to `package.json` may be enough.
+
+If you've kept the scripts from the [Getting Started guide](./getting-started.md#step-2-add-uniffi-bindgen-react-native-to-the-project), then adding:
+
+```diff
+scripts: {
+  "scripts": {
+    "ubrn:ios":      "ubrn build ios     --config ubrn.config.yaml --and-generate && (cd example/ios && pod install)",
+    "ubrn:android":  "ubrn build android --config ubrn.config.yaml --and-generate",
+    "ubrn:checkout": "ubrn checkout      --config ubrn.config.yaml",
++   "postinstall":   "yarn ubrn:checkout && yarn ubrn:android && yarn ubrn:ios",
+```
+
+## Add `uniffi-bindgen-react-native` to your README.md
+
+If you publish your source code anywhere, it would be lovely if you could add something to your README.md. For example:
+
+```diff
+Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)
++ and [uniffi-bindgen-react-native](https://github.com/jhugman/uniffi-bindgen-react-native)
+```
+
+## Add your project to the `uniffi-bindgen-react-native` README.md
+
+Once your project is published and would like some cross-promotion, perhaps you'd like to raise a PR to add it to the [`uniffi-bindgen-react-native` README](https://github.com/jhugman/uniffi-bindgen-react-native/blob/main/README.md#who-is-using-uniffi-bindgen-react-native).
diff --git a/docs/src/idioms/async-callbacks.md b/docs/src/idioms/async-callbacks.md
index 4c99d9e9..f67cceea 100644
--- a/docs/src/idioms/async-callbacks.md
+++ b/docs/src/idioms/async-callbacks.md
@@ -1 +1,49 @@
 # Async Callback interfaces
+
+[Callback interfaces and foreign traits](./callback-interfaces.md) can expose methods which are asynchronous. A toy example here:
+
+```rust
+#[uniffi::export(with_foreign)]
+#[async_trait::async_trait]
+trait MyFetcher {
+    async get(url: String) -> String;
+}
+
+fetch_with_fetcher(url: String, fetcher: Arc<dyn MyFetcher>) -> String {
+    fetcher.fetch(url).await
+}
+```
+
+Used from Typescript:
+
+```typescript
+class TsFetcher implements MyFetcher {
+    async get(url: string): Promise<string> {
+        return await fetch(url).text()
+    }
+}
+
+fetchWithFetcher("https://example.com", new TsFetcher());
+```
+
+You can see this in action in the [`futures` fixture](https://github.com/jhugman/uniffi-bindgen-react-native/tree/main/fixtures/futures).
+
+## Task cancellation
+
+When the Rust Future is completed, it is dropped, and Typescript is informed. If the Future is dropped before it has completed, it has been cancelled. `uniffi-bindgen-react-native` can use this information to call the async callback to cancel, using [the standard `AbortController` and `AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) machinery.
+
+`uniffi-bindgen-react-native` generates an optional argument for each async callback method, which is an options bag containing an `AbortSignal`.
+
+It is up to the implementer of each method whether they want to use it or not.
+
+Using exactly the same `MyFetcher` trait from above, this example passes the signal straight to [the `fetch` API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#canceling_a_request).
+
+```typescript
+class TsFetcher implements MyFetcher {
+    async get(url: string, asyncOptions?: { signal: AbortSignal }): Promise<string> {
+        return await fetch(url, asyncOptions).text()
+    }
+}
+
+fetchWithFetcher("https://example.com", new TsFetcher());
+```
diff --git a/docs/src/idioms/callback-interfaces.md b/docs/src/idioms/callback-interfaces.md
new file mode 100644
index 00000000..b99a4fcf
--- /dev/null
+++ b/docs/src/idioms/callback-interfaces.md
@@ -0,0 +1,108 @@
+# Callback interfaces
+
+Callbacks and function literals are not directly supported by `uniffi-rs`.
+
+However, [callback __interfaces__](https://mozilla.github.io/uniffi-rs/latest/proc_macro/index.html#the-uniffiexportcallback_interface-attribute) are, that is: instances of Typescript classes can be passed to Rust. The Typescript methods of those objects may then be called from Rust.
+
+```rust
+#[uniffi::export(callback_interface)]
+pub trait MyLogger {
+    fn is_enabled() -> bool;
+    fn error(message: string);
+    fn log(message: string);
+}
+
+#[uniffi::export]
+fn greet_with_logger(who: String, logger: Box<dyn MyLogger>) {
+    if logger.is_enabled() {
+        logger.log(format!("Hello, {who}!"));
+    }
+}
+```
+
+In Typescript, this can be used:
+
+```typescript
+class ConsoleLogger implements MyLogger {
+    isEnabled(): boolean {
+        return true;
+    }
+    error(message: string) {
+        console.error(messgae);
+    }
+    log(message: string) {
+        console.log(messgae);
+    }
+}
+
+greetWithLogger(new ConsoleLogger(), "World");
+```
+
+So-called [Foreign Traits](https://mozilla.github.io/uniffi-rs/latest/foreign_traits.html) can also be used. These are traits that can be implemented by either Rust or a foreign language: from the Typescript point of view, these are exactly the same as callback interfaces. They differ on the Rust side, using `Rc<>` instead of `Box<>`.
+
+
+```rust
+#[uniffi::export(with_foreign)]
+pub trait MyLogger {
+    fn error(message: string);
+    fn log(message: string);
+}
+
+#[uniffi::export]
+fn greet_with_logger(who: String, logger: Arc<dyn MyLogger>) {
+    logger.log(format!("Hello, {who}!"));
+}
+```
+
+These trait objects can be implemented by Rust or Typescript, and can be passed back and forth between the two sides of the FFI.
+
+## Errors
+
+Errors are propagated from Typescript to Rust:
+
+```rust
+#[derive(uniffi::Error)]
+enum MyError {
+    LoggingDisabled,
+}
+
+#[uniffi::export(callback_interface)]
+pub trait MyLogger {
+    fn is_enabled() -> bool;
+    fn log(message: string) -> Result<(), MyError>;
+}
+
+#[uniffi::export]
+fn greet_with_logger(who: String, logger: Box<dyn MyLogger>) -> Result<(), MyError> {
+    logger.log(format!("Hello, {who}!"));
+}
+```
+
+If an error is thrown in Typescript, it ends up in Rust:
+
+```typescript
+class ConsoleLogger implements MyLogger {
+    isEnabled(): boolean {
+        return false;
+    }
+    log(message: string) {
+        if (!this.isEnabled()) {
+            throw new MyError.LoggingDisabled();
+        }
+        console.log(message);
+    }
+}
+
+try {
+    greetWithLogger(new ConsoleLogger(), "World");
+} catch (e: any) {
+    if (MyError.instanceOf(e)) {
+        switch (e.tag) {
+            case MyError_Tags.LoggingDisabled: {
+                // handle the logging disabled error.
+                break;
+            }
+        }
+    }
+}
+```
diff --git a/docs/src/idioms/callbacks.md b/docs/src/idioms/callbacks.md
deleted file mode 100644
index ea64432d..00000000
--- a/docs/src/idioms/callbacks.md
+++ /dev/null
@@ -1 +0,0 @@
-# Callback interfaces
diff --git a/docs/src/idioms/enums.md b/docs/src/idioms/enums.md
index 0a1ee39a..42b86db7 100644
--- a/docs/src/idioms/enums.md
+++ b/docs/src/idioms/enums.md
@@ -144,7 +144,7 @@ const cat = MyAnimal.Cat.new();
 
 ## Enums with explicit discriminants
 
-Both [Rust](https://doc.rust-lang.org/reference/items/enumerations.html#discriminants) and Typescript allow you to specify discriminants to enum variants. As [in other bindings for uniffi-rs](https://mozilla.github.io/uniffi-rs/latest/proc_macro/index.html#variant-discriminants), this is suppoorted by `uniffi-bindgen-react-native`. For example,
+Both [Rust](https://doc.rust-lang.org/reference/items/enumerations.html#discriminants) and Typescript allow you to specify discriminants to enum variants. As [in other bindings for uniffi-rs](https://mozilla.github.io/uniffi-rs/latest/proc_macro/index.html#variant-discriminants), this is supported by `uniffi-bindgen-react-native`. For example,
 
 ```rust
 #[derive(uniffi::Enum)]
diff --git a/docs/src/idioms/promises.md b/docs/src/idioms/promises.md
index c40f1e4e..5e1dd01f 100644
--- a/docs/src/idioms/promises.md
+++ b/docs/src/idioms/promises.md
@@ -24,36 +24,58 @@ It can be called from Typescript:
 const message = await sayAfter(1000n, "World");
 ```
 
-## Calling async typescript
+You can see this in action in the [`futures-example` fixture](https://github.com/jhugman/uniffi-bindgen-react-native/tree/main/fixtures/futures-example/src), and the more complete [`futures` fixture](https://github.com/jhugman/uniffi-bindgen-react-native/tree/main/fixtures/futures).
+
+## Passing Promises across the FFI
+
+There is no support for passing a `Promise` or `Future` as an argument or error, in either direction.
+
+## Task cancellation
+
+Internally, `uniffi-rs` generates [a cancel function](https://docs.rs/uniffi/latest/uniffi/ffi/fn.rust_future_cancel.html) for each Future. On calling it, the `Future` is dropped.
+
+This is accessible for every function that returns a `Promise` by passing an _optional_ `{ signal: AbortSignal }` option bag as the final argument.
+
+Using the same Rust as above:
 
-The following code calls an async function implemented by Typescript.
 ```rust
-#[uniffi::export(with_foreign)]
-#[async_trait::async_trait]
-pub trait Greeter {
-    async fn create_greeting(&self, delay_ms: i32, who: String) -> String;
-}
+use std::time::Duration;
+use async_std::future::{timeout, pending};
 
-async fn greet_with(
-            greeter: &Greeter,
-            delay_ms: i32,
-            who: String
-) -> String {
-    greeter.create_greeting(delay_ms, who).await
+/// Async function that says something after a certain time.
+#[uniffi::export]
+pub async fn say_after(ms: u64, who: String) -> String {
+    let never = pending::<()>();
+    timeout(Duration::from_millis(ms), never).await.unwrap_err();
+    format!("Hello, {who}!")
 }
 ```
 
-The typescript:
+It can be used from Typescript, either without an `AbortSignal` as above, or with one passed as the final argument:
 
 ```typescript
-class TsGreeter implements Greeter {
-    async createGreeting(delayMs: number, who: string) {
-        await new Promise((resolve) => setTimeout(resolve, delayMs));
-        return `Hello, ${who} from Typescript!`;
-    }
+const abortController = new AbortController();
+setTimeout(() => abortController.abort(), 1000);
+try {
+    // Wait 1 hour for Hello, World!
+    const message = await sayAfter(60 * 60 * 1000, "World", { signal: abortController.signal });
+    console.log(message);
+} catch (e: any) {
+    e instanceof Error; // true
+    e.name === "AbortError"; // true
 }
-
-const message = greetWith(new TsGreeter(), 1000, "World");
 ```
 
-There is no support for passing a `Promise` or `Future` as an argument or error, in either direction.
+This example calls into the `say_after` function, and the Rust would wait for 1 hour before returning. However, the `abortController` has its `abort` method called after 1 second.
+
+```admonish warning
+[Task cancellation for one language is… complicated](https://without.boats/blog/asynchronous-clean-up/). For FFIs, it is a small but important source of impedence mismatches between languages.
+
+The [`uniffi-rs` docs](https://mozilla.github.io/uniffi-rs/latest/futures.html#cancelling-async-code) suggest that:
+
+> You should build your cancellation in a separate, library specific channel; for example, exposing a `cancel()` method that sets a flag that the library checks periodically.
+
+While `uniffi-rs` is recommending this, `uniffi-bindgen-react-native`— as a foreign-language binding to the uniffi-rs code— does so too.
+
+However, while `uniffi-rs` exposes `rust_future_cancel` function, `uniffi-bindgen-react-native`— as a foreign-language binding to the uniffi-rs code— does so too.
+```
diff --git a/docs/src/internals/lifting-and-lowering.md b/docs/src/internals/lifting-and-lowering.md
new file mode 100644
index 00000000..8aad3347
--- /dev/null
+++ b/docs/src/internals/lifting-and-lowering.md
@@ -0,0 +1,46 @@
+# Lifting, lowering and serialization
+
+This page is based upon the corresponding [`uniffi-rs` page](https://mozilla.github.io/uniffi-rs/latest/internals/lifting_and_lowering.html).
+
+> UniFFI is able to transfer rich data types back-and-forth between the Rust code and the Typescript code via a process we refer to as "lowering" and "lifting".
+>
+> Recall that UniFFI interoperates between different languages by defining a C-style FFI layer which operates in terms of primitive data types and plain functions. To transfer data from one side of this layer to the other, the sending side "lowers" the data from a language-specific data type into one of the primitive types supported by the FFI-layer functions, and the receiving side "lifts" that primitive type into its own language-specific data type.
+>
+> Lifting and lowering simple types such as integers is done by directly casting the value to and from an appropriate type. For complex types such as optionals and records we currently implement lifting and lowering by serializing into a byte buffer, but this is an implementation detail that may change in future.
+
+## Three layers
+In many languages, there are mechanisms to talk to the C-style FFI layer directly. Javascript has no such facilities.
+
+Instead, we perform serialization to an `ArrayBuffer` in Typescript, then pass it to C++ and then on to Rust.
+
+This can be sketched as:
+1. In Typescript, in `{namespace}.ts`: Lowering and serializing from higher level Typescript types to `ArrayBuffer`s, `number`s and `bigint`.
+1. Javascript calls into C++, through `{namespace}-ffi.ts`
+1. In C++, in `{namespace}.cpp`: lower the JSI `number`, `bigint` and `ArrayBuffer` further, into C equivalents, e.g. `uint32_t` and `uint8_t*`
+1. Pass these C equivalents to Rust through a C style ABI.
+1. Rust lifts the low level types, then calls into handwritten Rust.
+
+In more detail, for most types:
+
+1. do the [serialization (and deserialization)](https://mozilla.github.io/uniffi-rs/latest/internals/lifting_and_lowering.html#serialization-format) step in Typescript into an `ArrayBuffer` using `DataView` and `Uint8TypedArray`.
+    - This is done with a series of `FfiConverter`s. These are generated for complex types, but many can be seen in [`ffi-converters.ts`](https://github.com/jhugman/uniffi-bindgen-react-native/blob/main/typescript/src/ffi-converters.ts).
+1. call into generated C++ with the `ArrayBuffer`.
+    - This is represented by a `jsi::ArrayBuffer`.
+    - The JS/C++ interface is defined on the Typescript side by the `{namespace}-ffi.ts` file; it is implemented by the `{namespace}.cpp` file.
+1. [extract the `int32_t*` from the `jsi::ArrayBuffer`](https://github.com/jhugman/uniffi-bindgen-react-native/blob/main/cpp/includes/ForeignBytes.h) and [copy into a `RustBuffer`](https://github.com/jhugman/uniffi-bindgen-react-native/blob/main/crates/ubrn_bindgen/src/bindings/react_native/gen_cpp/templates/RustBufferHelper.cpp), a [C-style struct shared by both Rust and C++](https://github.com/jhugman/uniffi-bindgen-react-native/blob/main/cpp/includes/RustBuffer.h).
+1. call into Rust with the RustBuffer.
+
+### Primitives
+For more primitive types, the lifting and lowering is also done in two stages: for example, if Rust is expecting an `i32`, the Javascript `number` is passed into C++. The C++ then extracts the `int32_t` from the `jsi::Value::Number`.
+
+### Strings
+For Strings, we would want to use a [`TextEncoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder). Unfortunately these aren't currently available for hermes; see hermes issues for [`TextEncoder`](https://github.com/facebook/hermes/issues/948) and [`TextDecoder`](https://github.com/facebook/hermes/issues/1403).
+
+In this case, we use C++ again. When a string needs serializing to an `ArrayBuffer`, [the `FfiConverterString`](https://github.com/jhugman/uniffi-bindgen-react-native/blob/main/crates/ubrn_bindgen/src/bindings/react_native/gen_typescript/templates/StringHelper.ts):
+1. calls passes the string from Typescript [to C++](https://github.com/jhugman/uniffi-bindgen-react-native/blob/main/crates/ubrn_bindgen/src/bindings/react_native/gen_cpp/templates/StringHelper.cpp), these are represented as `jsi::Value::String`.
+1. In C++ [`UniffiString.h`](https://github.com/jhugman/uniffi-bindgen-react-native/blob/main/cpp/includes/UniffiString.h):
+    1. get a C++ String using the `utf8()` method of `jsi::String`
+    1. the copy the bytes into a `jsi::ArrayBuffer`.
+1. Return the ArrayBuffer to Javascript so it can be:
+    1. added to the serialization of a complex type OR
+    1. passed to Rust as an `ArrayBuffer`, as above.
diff --git a/docs/src/internals/rn-codegen.md b/docs/src/internals/rn-codegen.md
new file mode 100644
index 00000000..c5e8cf20
--- /dev/null
+++ b/docs/src/internals/rn-codegen.md
@@ -0,0 +1,19 @@
+# NativeModule.ts and Codegen
+
+React Native provides its own Codegen to route calls to C++ TurboModules, via Objective-C and Java/JNI.
+
+`uniffi-bindgen-react-native` uses this to "install" the C++ in to the `jsi::Runtime`.
+
+The install flow is sketched as follows:
+
+1. when the first time the package is imported, the `installRustCrate` typescript method is called. This is in [the input file for Codegen, the `Native{namespace}.ts` file](https://github.com/jhugman/uniffi-bindgen-react-native/blob/main/crates/ubrn_cli/src/codegen/templates/NativeCodegenTemplate.ts).
+1. this invokes the corresponding machinery generated by `Codegen`, in Objective C and Java.
+1. once in Objective C and Java, we find the `jsi::Runtime` and the `facebook::react::CallInvoker` from the
+    - [Objective C](https://github.com/jhugman/uniffi-bindgen-react-native/blob/main/crates/ubrn_cli/src/codegen/templates/ModuleTemplate.mm#L20-L25) and
+    - [Java](https://github.com/jhugman/uniffi-bindgen-react-native/blob/main/crates/ubrn_cli/src/codegen/templates/ModuleTemplate.java#L37-L40).
+1. this then passes the `Runtime` and `CallInvoker` to the [C++ Turbo-Module](https://github.com/jhugman/uniffi-bindgen-react-native/blob/main/crates/ubrn_cli/src/codegen/templates/TurboModuleTemplate.cpp) proper.
+1. This then calls into the generated `cpp/bindings/{namespace}.cpp` which implements the `src/bindings/{namespace}-ffi.ts`.
+
+Every other call from JS goes directly to this C++, rather than via Objective-C and Java.
+
+This pattern of using the `Codegen` just for the installation flow for the bindings allowed for testing outside React Native, and could then be relatively [simply templated](../reference/commandline.md#generate-turbo-module).
diff --git a/scripts/run-bootstrap-docs.sh b/scripts/run-bootstrap-docs.sh
new file mode 100755
index 00000000..bc0641e2
--- /dev/null
+++ b/scripts/run-bootstrap-docs.sh
@@ -0,0 +1,6 @@
+#!/bin/sh
+
+cargo install mdbook
+cargo install mdbook-admonish
+cargo install mdbook-linkcheck
+cargo install mdbook-open-on-gh