Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ading2210/sandstone/llms.txt

Use this file to discover all available pages before exploring further.

The network module manages all outbound connections made by Sandstone. It holds the singleton libcurl HTTP session used to fetch pages and static assets, tracks active WebSocket connections grouped by frame ID, and exposes the set_websocket function you call to point Sandstone at a Wisp server. You access this module as sandstone.network after importing the host bundle.

​
Import

import * as sandstone from "./dist/sandstone.mjs";
// Access network exports via:
const { network } = sandstone;

​
Exports

​
ws_connections
Object
A map of all active WebSocket connections, keyed first by frame ID and then by a per-connection WS ID. Each leaf entry is an object with ws (the underlying libcurl.CurlWebSocket instance), events (a queue of pending events), and callback (an optional resolver for the current long-poll). You typically do not need to read this directly; it is managed automatically as pages open and close WebSockets.
​
session
libcurl.HTTPSession | null
The active libcurl HTTP session, or null before libcurl has finished loading. The session is created with enable_cookies: true when the libcurl_load event fires, so cookies are shared across all requests made through the same session. Use session.fetch directly for advanced request scenarios, or rely on ProxyFrame.navigate_to which calls it internally.
​
set_websocket
(url: string) => void
Set the URL of the Wisp WebSocket server that libcurl.js uses to tunnel all proxied traffic. You must call this before the first navigation. Wraps libcurl.set_websocket(url) directly.
​
clean_ws_connections
(frame_id: string) => void
Close and remove all WebSocket connections associated with the given frame ID. This is called automatically by ProxyFrame.navigate_to each time you navigate to a new page, so stale connections from the previous page are cleaned up. You can also call it manually if you need to forcibly tear down connections for a specific frame.

​
The libcurl re-export

sandstone.libcurl re-exports the libcurl.js instance directly, giving you access to the full libcurl.js API for advanced use cases such as making raw fetch requests, creating CurlWebSocket instances, or calling set_websocket directly: 
// Both of these are equivalent
sandstone.network.set_websocket("wss://wisp.mercurywork.shop/");
sandstone.libcurl.set_websocket("wss://wisp.mercurywork.shop/");

​
Example

import * as sandstone from "./dist/sandstone.mjs";

// Point Sandstone at a Wisp server before navigating
sandstone.network.set_websocket("wss://wisp.mercurywork.shop/");

// Access the HTTP session directly after libcurl loads
sandstone.libcurl.events.addEventListener("libcurl_load", () => {
  const { session } = sandstone.network;
  console.log("HTTP session ready:", session);
});
sandstone.network.session is null until the libcurl_load event fires. If you need to make requests before the first ProxyFrame.navigate_to call (which waits for libcurl internally), listen for libcurl_load on sandstone.libcurl.events before accessing session.

Build docs developers (and LLMs) love

Get started for freeTalk to us