V0.4 (WASM + Playground)

.github/workflows/CI.yml

@@ -2,7 +2,7 @@ name: Package checks
 
 on:
   pull_request:
-    paths: ['crates/**', 'Cargo.toml', 'Cargo.lock', 'scripts/**', '.github/workflows/CI.yml', '.github/workflows/publish.yml']
+    paths: ['crates/**', '!crates/wasm/**', 'Cargo.toml', 'Cargo.lock', 'scripts/**', '.github/workflows/CI.yml', '.github/workflows/publish.yml']
   workflow_dispatch:
   workflow_call:
 
@@ -26,6 +26,11 @@ jobs:
       - run: cargo test -p superstac-cli -p superstac-engine --features geoparquet --locked
       - run: cargo check -p superstac-python --no-default-features --locked
 
+  wasm:
+    # Pull requests run the standalone WASM workflow, including WASM-only changes.
+    if: github.event_name != 'pull_request'
+    uses: ./.github/workflows/wasm.yml
+
   wheels:
     name: Wheel (${{ matrix.target }})
     runs-on: ${{ matrix.runner }}

.github/workflows/wasm.yml

@@ -0,0 +1,42 @@
+name: WASM checks
+
+on:
+  pull_request:
+    paths:
+      - 'crates/wasm/**'
+      - 'crates/core/**'
+      - 'crates/search/**'
+      - 'Cargo.toml'
+      - 'Cargo.lock'
+      - '.github/workflows/wasm.yml'
+  workflow_dispatch:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  browser:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: '1.88.0'
+          targets: wasm32-unknown-unknown
+      - uses: Swatinem/rust-cache@v2
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: crates/wasm/package-lock.json
+      - run: cargo install wasm-pack --version 0.13.1 --locked --jobs 2
+      - run: npm ci
+        working-directory: crates/wasm
+      - run: npm run build
+        working-directory: crates/wasm
+      - run: npx playwright install --with-deps chromium
+        working-directory: crates/wasm
+      - run: npm run check
+        working-directory: crates/wasm

.gitignore

@@ -75,4 +75,7 @@ ideas/
 .env
 .env.local
 .pnpm-store/
+# Browser binding artifacts
+/crates/wasm/pkg/
+/crates/wasm/node_modules/
 node_modules/

Cargo.toml

@@ -8,6 +8,7 @@ members = [
     "crates/cli",
     "crates/python", 
     "crates/geoparquet",
+    "crates/wasm",
 ]
 
 [workspace.package]

README.md

@@ -97,6 +97,15 @@ Run `superstac --help` for commands and options. The
 [configuration reference](https://spatialnode.com/superstac/docs/reference/configuration)
 explains aliases, timeouts, and retries.
 
+## Browser / WebAssembly
+
+Build the browser binding to search live STAC catalogs from JavaScript or TypeScript.
+See the [WASM guide](crates/wasm/README.md) for build instructions, API usage,
+a browser example, and browser-specific limitations. The docs include a
+[live playground](https://spatialnode.com/superstac/docs/wasm/playground)
+and a [JavaScript guide](https://spatialnode.com/superstac/docs/wasm/overview).
+
+## Configuration
 ## Save metadata for repeated searches
 
 GeoParquet inventories let you reuse metadata for an area and date range. Search

crates/search/Cargo.toml

@@ -17,12 +17,21 @@ authors.workspace = true
 superstac-core = { path = "../core", version = "0.3.0" }
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1"
-tokio = { version = "1", features = ["time"] }
 futures = "0.3"
-stac = "0.16"
-stac-io = "0.2"
-reqwest = { version = "0.13", default-features = false }
+reqwest = { version = "0.13", default-features = false, features = ["json"] }
 tracing = "0.1"
 
+[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
+tokio = { version = "1", features = ["time"] }
+stac-io = "0.2"
+stac = "0.16"
+
+[target.'cfg(target_arch = "wasm32")'.dependencies]
+# 0.17.0 gates filesystem APIs; later releases conflict with native geo dependencies.
+stac = { version = "=0.17.0", default-features = false }
+getrandom = { version = "0.3", features = ["wasm_js"] }
+getrandom02 = { package = "getrandom", version = "0.2", features = ["js"] }
+gloo-timers = { version = "0.3", features = ["futures"] }
+
 [dev-dependencies]
 tokio = { version = "1", features = ["rt", "macros"] }

crates/search/src/backend.rs

@@ -1,5 +1,18 @@
 //! Search contracts shared by remote and file-backed implementations.
-use futures::future::BoxFuture;
+/// Futures run on the browser event loop on WASM; native backends remain Send.
+#[cfg(not(target_arch = "wasm32"))]
+pub type SearchFuture<'a, T> = futures::future::BoxFuture<'a, T>;
+#[cfg(target_arch = "wasm32")]
+pub type SearchFuture<'a, T> = futures::future::LocalBoxFuture<'a, T>;
+
+#[cfg(not(target_arch = "wasm32"))]
+pub trait BackendBounds: Send + Sync {}
+#[cfg(not(target_arch = "wasm32"))]
+impl<T: Send + Sync + ?Sized> BackendBounds for T {}
+#[cfg(target_arch = "wasm32")]
+pub trait BackendBounds {}
+#[cfg(target_arch = "wasm32")]
+impl<T: ?Sized> BackendBounds for T {}
 use superstac_core::{errors::SuperSTACError, models::catalog::Catalog};
 
 use crate::{query::SearchQuery, response::SearchItem};
@@ -21,13 +34,13 @@ pub struct BackendSearchOptions {
 /// Dataset locations can be held by the backend; `Catalog::url` is only an API
 /// endpoint for the STAC backend. This interface does not perform health checks
 /// or ingestion. Boxed futures allow runtime selection via `dyn SearchBackend`.
-pub trait SearchBackend: Send + Sync {
+pub trait SearchBackend: BackendBounds {
     fn search<'a>(
         &'a self,
         catalog: &'a Catalog,
         query: SearchQuery,
         options: BackendSearchOptions,
-    ) -> BoxFuture<'a, Result<Vec<SearchItem>, SuperSTACError>>;
+    ) -> SearchFuture<'a, Result<Vec<SearchItem>, SuperSTACError>>;
 }
 
 impl<T: SearchBackend + ?Sized> SearchBackend for std::sync::Arc<T> {
@@ -36,7 +49,7 @@ impl<T: SearchBackend + ?Sized> SearchBackend for std::sync::Arc<T> {
         catalog: &'a Catalog,
         query: SearchQuery,
         options: BackendSearchOptions,
-    ) -> BoxFuture<'a, Result<Vec<SearchItem>, SuperSTACError>> {
+    ) -> SearchFuture<'a, Result<Vec<SearchItem>, SuperSTACError>> {
         (**self).search(catalog, query, options)
     }
 }