Advisory review: the language guide — from buried markdown to a self-verifying page

.github/workflows/pages.yml

@@ -43,18 +43,28 @@ jobs:
           FMPL_BOOTSTRAP_PHASE=1 cargo build -p fmpl-bootstrap
           touch fmpl-core/build.rs
 
-      - name: Build fmpl-wasm (release)
-        run: cargo build -p fmpl-wasm --release --target wasm32-unknown-unknown
+      - name: Build fmpl-wasm (size-tuned wasm-release profile)
+        run: cargo build -p fmpl-wasm --profile wasm-release --target wasm32-unknown-unknown
 
       # Must match the exact wasm-bindgen version pinned in fmpl-wasm/Cargo.toml.
       - name: Install wasm-bindgen CLI
         run: cargo install wasm-bindgen-cli --version 0.2.114 --locked
 
       - name: Generate JS bindings into the site
         run: |
-          wasm-bindgen target/wasm32-unknown-unknown/release/fmpl_wasm.wasm \
+          wasm-bindgen target/wasm32-unknown-unknown/wasm-release/fmpl_wasm.wasm \
             --out-dir docs/repl --target web --no-typescript
 
+      # Pinned binaryen release — apt's is too old to accept the sign-ext
+      # ops Rust emits by default. 129 matches the locally verified build.
+      # Rust also emits bulk-memory ops by default; wasm-opt must be told.
+      - name: Shrink with wasm-opt
+        run: |
+          curl -sL https://github.com/WebAssembly/binaryen/releases/download/version_129/binaryen-version_129-x86_64-linux.tar.gz | tar xz
+          binaryen-version_129/bin/wasm-opt -Oz --enable-bulk-memory --enable-nontrapping-float-to-int \
+            --strip-producers docs/repl/fmpl_wasm_bg.wasm -o docs/repl/fmpl_wasm_bg.wasm
+          ls -l docs/repl/fmpl_wasm_bg.wasm
+
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3
         with:

Cargo.toml

@@ -50,3 +50,14 @@ rkyv = { version = "0.8", features = ["smol_str-0_3"] }
 # Async streaming
 tokio-stream = "0.1"
 async-trait = "0.1"
+
+# Size-tuned profile for the browser wasm build only (pages.yml). Safe with
+# panic="abort": VM errors are Results by design (no catch_unwind in-tree),
+# so unwinding machinery is pure weight here. ~2.1MB -> ~1.1MB raw.
+[profile.wasm-release]
+inherits = "release"
+opt-level = "z"
+lto = "fat"
+codegen-units = 1
+panic = "abort"
+strip = true

README.md

@@ -6,7 +6,9 @@ image is the source of truth; source files are a bootstrapping convenience.
 
 New here? Read the **[engineering tour](https://mparrett.github.io/fmpl/fmpl-tour.html)** —
 architecture, verified capabilities, and the honest gap ledger, in one page —
-or try the **[browser REPL](https://mparrett.github.io/fmpl/repl.html)**
+learn the language from the **[language guide](https://mparrett.github.io/fmpl/fmpl-guide.html)**
+(the web rendering of [`TUTORIAL.md`](TUTORIAL.md)), or try the
+**[browser REPL](https://mparrett.github.io/fmpl/repl.html)**
 (fmpl-core compiled to WebAssembly, no install).
 
 > **Status: experimental.** FMPL is a working prototype under active