Reactivity (PulsePoint)

Caspian is built on top of PulsePoint, a lightweight reactive DOM engine. While PulsePoint provides the core primitives, Caspian extends it with framework-specific utilities for routing, server communication, and URL management.

Core PulsePoint Directives

These primitives are part of the core library and handle DOM updates, state, and references.

pp-component pp-spread pp-ref pp-for pp.state pp.effect pp.ref pp-ignore
Read the PulsePoint Documentation

Caspian Extensions

Caspian injects global helpers to streamline full-stack development.

pp.rpc(functionName, data?)

The bridge to your Python backend. It handles serialization, CSRF protection, and error states automatically.

  • Smart Serialization: Automatically switches between JSON and FormData if you pass File objects.
  • Auto-Redirect: If the server responds with a redirect header, the client navigates automatically.
  • Security: Injects X-CSRF-Token headers on every request. 
async function saveProfile(e) {
  // 1. Basic Call
  const user = await pp.rpc("update_user", { name: "Jeff" });

  // 2. With File Upload (Auto FormData)
  const file = fileInput.files[0];
  await pp.rpc("upload_avatar", { avatar: file });

  // 3. Abort Previous (Debounce style)
  await pp.rpc("search", { query }, true);
}

searchParams

A global reactive wrapper around URLSearchParams. It is available directly as searchParams (no prefix). Updating these params will update the URL without a page reload and trigger any active listeners. 

// Get a value
const tab = searchParams.get("tab") || "overview";

// Set a value (Updates URL history)
searchParams.set("page", "2");

// Replace all params
searchParams.replace({ 
  sort: "asc", 
  filter: null // null removes the key
});

Navigation

Caspian intercepts standard <a> tags for client-side navigation automatically. For programmatic navigation, use the pp.redirect helper.

pp.redirect(url)

This is a smart navigation handler that automatically determines the best way to load the new URL:

  • Internal Links: Uses efficient client-side routing (no full reload), preserving state and enabling View Transitions.
  • External Links: Automatically falls back to a standard window.location.href hard reload. 
function goHome() {
  // Client-side transition (fast)
  pp.redirect("/dashboard");
}

function goGoogle() {
  // Hard reload (standard)
  pp.redirect("https://google.com");
}