feat: add simplicity wasm runner

.github/workflows/ci.yml

@@ -3,33 +3,78 @@ name: ci
 on:
   push:
     branches:
-      - master 
+      - master
       - main
+  # Runnable snippets are executed on every PR, so one that stops compiling is caught
+  # before it reaches the site rather than after.
+  pull_request:
 
 permissions:
   contents: read  # Adjusted from 'write'
   pages: write    # Added
   id-token: write # Added
 
-# Used to avoid concurrency issues
-concurrency:
-  group: github-pages
-  cancel-in-progress: false
-
 jobs:
+  # Executes every `simplicityhl,run` fence under docs/ and checks it behaves as its
+  # `expect=` flag claims. See crates/simplicity-runner/README.md.
+  snippets:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # Ubuntu runners ship a rustup toolchain, so nothing to install for a host build.
+      - uses: actions/cache@v4
+        with:
+          key: cargo-${{ hashFiles('crates/simplicity-runner/Cargo.lock') }}
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            crates/simplicity-runner/target
+          restore-keys: |
+            cargo-
+      - run: cargo test --manifest-path crates/simplicity-runner/Cargo.toml
+
   deploy:
+    # A page whose snippet no longer compiles must not reach the site.
+    needs: snippets
+    if: github.event_name == 'push'
     runs-on: ubuntu-latest
+    # Serialise deploys only; PR runs are free to overlap.
+    concurrency:
+      group: github-pages
+      cancel-in-progress: false
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }} # Retrieved from deploy-pages action
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
+
+      # --- the compiler readers run in their browser --------------------------------
+      # Built here rather than committed, so no 2 MB binary accumulates in git history.
+      # It must land in docs/wasm/pkg/ before mkdocs runs, since mkdocs copies docs/
+      # verbatim into the site.
+      - run: rustup target add wasm32-unknown-unknown
+      - uses: actions/cache@v4
+        with:
+          key: cargo-wasm-${{ hashFiles('crates/simplicity-runner/Cargo.lock') }}
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            crates/simplicity-runner/target
+          restore-keys: |
+            cargo-wasm-
+      - run: curl -sSf https://rustwasm.github.io/wasm-pack/installer/init.sh | sh
+      - run: wasm-pack build crates/simplicity-runner --target web --out-dir ../../docs/wasm/pkg --release
+      # wasm-pack also emits npm packaging and type declarations; only the loader and the
+      # binary are served, and the rest would otherwise be published with the site.
+      - run: rm -f docs/wasm/pkg/{.gitignore,package.json,README.md,*.d.ts}
+
+      # --- the site ------------------------------------------------------------------
       - uses: actions/setup-python@v5
         with:
           python-version: 3.x
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
       - uses: actions/cache@v4
         with:
           key: mkdocs-material-${{ env.cache_id }}
@@ -38,9 +83,12 @@ jobs:
             mkdocs-material-
       - run: pip install -r requirements.txt
       - run: mkdocs build                      # Adjusted from 'mkdocs gh-deploy'
+      # Fail loudly if the compiler is missing rather than deploying a site whose every
+      # Run button 404s.
+      - run: test -s site/wasm/pkg/simplicity_runner_bg.wasm
       - uses: actions/configure-pages@v5       # Added
       - uses: actions/upload-pages-artifact@v3 # Added
         with:
           path: 'site/'
       - uses: actions/deploy-pages@v4          # Added
-        id: deployment
+        id: deployment

.gitignore

@@ -67,3 +67,13 @@ node_modules/
 # Backup files
 *.bak
 *.backup
+.claude/
+# Rust build output for the snippet compiler
+crates/*/target/
+
+# MkDocs hook bytecode
+hooks/__pycache__/
+
+# The SimplicityHL compiler. Built by CI (and locally by `npm run build:wasm`)
+# from crates/simplicity-runner, never committed.
+docs/wasm/pkg/

CONTRIBUTING.md

@@ -49,6 +49,45 @@ Avoid assuming a particular operating system or environment.
 
 If an example needs setup or relies on a tool, include it (or link to it).
 
+### Runnable examples
+
+Add `,run` to a `simplicityhl` fence and the reader can edit and execute it in the
+browser. Works on any page, including inside admonitions and collapsible blocks.
+
+````markdown
+```simplicityhl,run title="A program that succeeds"
+fn main() {
+    assert!(jet::eq_32(2, 2));
+}
+```
+````
+
+Flags, comma- or space-separated, in any order:
+
+| Flag | Effect |
+| --- | --- |
+| `run` | required — without it the fence stays a plain code block |
+| `title="…"` | caption above the editor |
+| `readonly` | show **Run** but forbid editing |
+| `tx` | run against a real Liquid testnet transaction, so introspection jets return true values. Adds a txid field and an input selector |
+| `txid="…"` | the transaction to prepopulate for a `tx` snippet |
+| `input=N` | preselect input `N` in a `tx` snippet's selector |
+| `expect=compile-error` | this snippet is meant not to compile |
+| `expect=run-error` | this snippet is meant to compile and then fail |
+
+Every runnable snippet is executed by `npm run test:snippets`, which fails the build if one
+stops behaving as its `expect` says. CI runs it on every PR. A deliberately broken example
+is fine — that is what `expect=` is for — but say so in the prose too.
+
+To try snippets locally you need the compiler, which is a gitignored build artifact rather
+than a checked-in binary. Once per clone:
+
+```bash
+npm run build:wasm     # needs Rust + wasm-pack; see crates/simplicity-runner/README.md
+```
+
+Without it the page renders fine and only **Run** fails, so prose-only edits need nothing.
+
 ### Audiences
 
 Consider various audiences' perspectives: