DocsBuilding pages
PulsePoint runtime
The browser half of Rahti: it mounts the boundaries the server named, runs their compiled scripts, tracks hook state, applies bindings, and handles SPA navigation and RPC calls. It ships prebuilt — there is no JavaScript build step.
A file, not a build step
The runtime is a prebuilt asset. An application ships public/js/pp-reactive-v2.min.js and mounts it from public/js/main.js. cargo rahti new writes the same bundle into every project it creates, and cargo rahti upgrade replaces it when the framework ships a new build.
The browser compiles nothing. html! compiles every binding, handler, pp-for collection and component script when the application is built, and the server serves the result as a registry at /_rahti/client.js. public/js/main.js imports it after the runtime and before the first mount, and a static export writes it beside the pages. PulsePoint runs registered code only, so the content security policy needs no 'unsafe-eval'.
The authoring model
PulsePoint scripts are plain JavaScript written inside the reactive root they belong to. The root and the script are one component scope.
html! {
<section>
<p>{count}</p>
<button onclick={setCount(value => value + 1)}>"Increment"</button>
<script>r##"
const [count, setCount] = pp.state(0);
"##</script>
</section>
}Hooks must run in a stable order during every render, as in React. Do not call them conditionally, or after the component is disposed.
Component boundaries
The runtime reads the served document back and mounts one scope per boundary. A boundary arrives in one of three shapes, all written by html! and never by hand:
- An element carrying
pp-component— the ordinary case: a page's root, a component's root, a single-rooted child fragment. The element anchors the scope. - A template — around a root layout's
<slot />, and around server-deferred content generally. The runtime materialises it into live DOM before mounting. - A comment pair — around a run of siblings from a
<>…</>fragment. At mount the runtime raises the pair into a live, layout-invisible boundary element.
Two things are deliberately not boundaries. A block whose root is a component tag contributes no markup of its own, so it adds no scope. And several instances of one component are separate scopes even though they share a name — the runtime derives a unique identity per instance, which is why two copies of the same counter count independently.
The binding surface
| Syntax | Purpose |
|---|---|
| {expression} in text | Escaped reactive text or value. |
| {expression} in a quoted attribute | A reactive attribute or property. |
| any native on* attribute | An event handler expression. |
| pp-for="item in items" | A loop on a <template>. |
| pp-for="(item, index) in items" | The same, with an index. |
| key="{expression}" | Repeated-row identity. |
| pp-ref={ref} | Binds a native element to a ref. |
| pp-style="{cssText}" | Dynamic inline style. |
| pp-spread="{object}" | Spreads dynamic attributes. |
| <token.provider value="{value}"> | A context provider. |
| pp-spa="false" on an anchor | Opts out of SPA interception. |
| pp-reset-scroll="true" | Resets a scroll container on navigation. |
| pp-scroll-key="name" | A stable scroll-restoration identity. |
| pp-loading-content="true" | The region a loading.rs replaces. |
| pp-loading-transition | Fade timing for that swap, as JSON. |
Value rendering
A binding does not print its value with String(...). PulsePoint serializes it the way React serializes a JSX child. Read this before binding a value that is not a plain string or number — most surprises reported as "my binding is blank" are one of these rules working as designed.
In text position
| Value | Rendered |
|---|---|
| "text", 42, 12n | The value, HTML-escaped. |
| true / false | Nothing. Both booleans, not only false. |
| null / undefined | Nothing. |
| "" | Nothing — it is the empty string, not a blank. |
| 0 | 0. Falsy, but printed. |
| an array | Each item by these same rules, concatenated with no separator. |
| an object, function or symbol | Nothing, plus a [PP-WARN] console line. React throws here; PulsePoint omits and warns. |
The boolean row is the one that costs time. A value seeded from Rust as false, or a None seeded as null, arrives in the browser correctly and then renders as an empty span.
// admin === false renders nothing at all — both booleans vanish.
<p>"Admin: "<span>{admin}</span></p>
// Spell the display out in the expression instead.
<p>"Admin: "<span>{admin ? "yes" : "no"}</span></p>
<p>"Role: "<span>{role ? role : "none"}</span></p>
// The React `&&` idiom leaks a zero: `0` prints, only booleans and nullish
// values vanish.
<p>{items.length > 0 ? "Some" : "None"}</p>In attribute position
| Attribute kind | Value | Result |
|---|---|---|
| HTML boolean (disabled, hidden, checked…) | true | Attribute present. |
false, nullish, or a falsy primitive | Attribute absent. | |
| a truthy primitive | Present, carrying that value. | |
| anything else (class, title, aria-*, data-*) | true / false | The literal strings "true" / "false". |
null / undefined | Attribute present, with an empty value. | |
0, NaN | "0", "NaN". |
Two of those rows differ from React. A boolean on a non-boolean attribute is serialized rather than dropped, because aria-pressed and data- flags are string-valued in the DOM. And a nullish value leaves the attribute present and empty — harmless on class or title, not harmless on a URL, where src="" re-requests the current document.
// A nullish value leaves a non-boolean attribute present and empty, and
// src="" re-requests the current document. Guard URL attributes.
<img src="{avatar ? avatar : placeholder}" />An attribute the browser parses or fetches the moment it is set — src, srcset, sizes, imagesrcset, imagesizes, poster — is written with a binding like any other, and the browser only ever sees its evaluated value. Until the owning block renders, the runtime keeps the unevaluated text off the real attribute, so no request goes out for the expression and no srcset parse warning reaches the console. That holds in a page, in children written between a component's tags, and in the rows a pp-for inserts, scripted component rows included.
// The browser only ever sees the evaluated URL: no request goes out for the
// `{…}` text, even in rows a pp-for inserts.
<template pp-for="photo in photos">
<img key={photo.id} src={photo.url} alt={photo.alt} />
</template>The attribute that holds the expression in the meantime is runtime-managed and gone once the block renders; never write it or select on it.
A pp-for collection that is not iterable renders no rows and logs a warning; null and undefined render no rows silently. Binding an object rather than an array is a blank list, not an error.
Events
Use native lowercase event names, including long names such as onlostpointercapture. A handler runs when its event fires, never while the element renders.
onclick={save()}
oninput={setName(target.value)}
// Inside an event expression the runtime exposes `event`, `e`, `$event`,
// `target`, `currentTarget` and `el`. Use native lowercase names — `onclick`,
// never `onClick`.Handlers on a component root
A native handler written on a component's root runs in that component instance's script scope. Each instance resolves its own handler, even when several instances of the same component appear on a page. A caller's handler forwarded through bindings runs in the caller's scope.
use rahti::{Html, component, html};
#[component]
pub fn SubmitForm() -> Html {
html! {
<form onsubmit={handleSubmit(event)}>
<button type="submit">"Save"</button>
<script>r##"
function handleSubmit(e) {
e.preventDefault();
}
"##</script>
</form>
}
}One element has one event owner. A root cannot combine its own native handlers with a caller's: an on…=@{…} value beside an owned handler is a compile error, and an attribute spread that brings a native event handler onto such a root triggers a debug assertion and is dropped in release builds. Put the caller's handler on an inner element, or call it from the component's own handler.
Rahti writes pp-event-owner automatically; do not author it. Run cargo rahti upgrade with the current CLI to update both the Rust dependencies and the shipped PulsePoint bundle.
Bindings on a component root
Handlers are the only client expressions a component writes on its own root. The runtime evaluates every other root attribute where the tag was written, so a {…} the component writes there could never read its own state or pp.props. In a #[component] that is a compile error; bind an element inside the root instead. Server @{…} values, pp-* attributes and JSON data on the root compile as usual, and page and layout roots are not checked.
The other side of the same rule is what makes component tags work like React props. A {…} the caller writes on a component tag is handed to the component as source, the component writes it on its root through bindings, and it reads the state of the page that wrote the tag — attributes and handlers alike. That holds between another component's tags too: children carrying such a prop ship owner-scoped, so the inner component's root reads the page rather than the component it sits in.
// A `{…}` a component writes on its own root is evaluated in the caller's
// scope, so it could never read the component's state: in a #[component]
// it is a compile error. Bind an element inside the root instead.
<section hidden={!open}> // compile error
<section><div hidden={!open}>"…"</div> // fine
// A caller's `{…}` prop is the caller's expression. The component writes it
// on its root through `bindings`, and it reads the page that wrote the tag —
// here and between another component's tags alike.
<Button disabled={count === 0} onclick={setCount(count + 1)}>"Add"</Button>
<Card><Input value={query} oninput={setQuery(target.value)} /></Card>A component with no script compiles in its caller's scope — that is how a script-less component takes expressions from the page. When its own markup below the root binds a client value, html! adds an empty <script></script> before the root closes, so <p>{pp.props.label}</p> reads that component's props. A spread below the root keeps the caller's scope, because the spread may carry the caller's bindings.
Prop names are checked
Nothing ties the name a caller passes to the name a component reads at runtime: a misspelled one is an attribute nobody reads on one side and undefined on the other. html! refuses the two cases it can be certain of.
// MigrationDialog's file reads pp.props.open and pp.props.current.
html! {
<MigrationDialog open={shown} curent={id} />
}
// error: rahti[RAHTI_PROP_NOT_READ]: `<MigrationDialog>` is passed `curent={…}`,
// and `MigrationDialog` never reads `pp.props.curent`.
// It reads `current`, `open`.The name is compared in camelCase, so online-now and onlineNow both match pp.props.onlineNow. These are never refused:
| Never refused | Why |
|---|---|
An HTML attribute, a handler, and anything starting data-, aria- or pp- | The root element uses it for itself. To set an attribute of your own on a component's root, name it data-…. |
| A prop of a component that reads no prop itself | It is a wrapper, and what it is passed is for its root. |
| A prop of a component that may read one unseen | One that uses pp.props whole, forwards its bindings to another component, or hands them to a function. |
| A prop of a component from another crate | The build reads this application's own files. |
#[component]
pub fn Greeting(user_name: &str) -> Html {
html! {
<div user-name=@{user_name}>
<b>{pp.props.userNmae}</b>
</div>
}
}
// error: rahti[RAHTI_PROP_NEVER_GIVEN]: this component reads `pp.props.userNmae`,
// a prop it is never given.
// Its root element gives it `userName`.A component whose root element takes no spread has exactly the props that root is written with. Once the root carries bindings or an Attrs spread, a caller can pass any prop, and nothing read there is refused.
Names are checked
A misspelled state, setter, function or loop variable used to compile and fail on the page, as undefined in a binding or a ReferenceError in a handler. html! knows where every name a block reads can come from, and refuses one that comes from nowhere, on the name itself.
html! {
<section>
<p hidden={domians.length > 0}>"No domains yet."</p>
<button onclick={laod()}>"Reload"</button>
<script>r##"
const [domains, setDomains] = pp.state([]);
async function load() {
setDomians(await pp.rpc("list_domains", {}));
}
"##</script>
</section>
}
// error: rahti[RAHTI_UNKNOWN_NAME]: this binding reads `domians`, a name
// nothing gives it. Did you mean `domains`?
//
// `laod` and `setDomians` are refused the same way, one at a time.| Code | Names it can read |
|---|---|
A <script> | What it declares, pp, and the window. |
A binding, a pp-for collection | What the block's script declares at its top level, the rows and indexes of the pp-fors it is written in, pp, and the window. |
| A handler | The same, and its event: event, e, $event, target, currentTarget, el. |
The window is the language's and the browser's own names, such as document, fetch and setTimeout, and any name that starts with a capital letter: Math, IntersectionObserver, or a class a vendored library publishes. typeof name asks whether a name exists without reading it.
| Not checked | Why |
|---|---|
Bindings and handlers of a block with no <script> | It renders in the scope of the block around it. |
| Fragment-rooted children written between component tags | They read the component they are passed to. |
What is read off a name, such as domain.nmae | That is a field, not a name. See the state and response checks on the RPC page. |
Forms
value={state} and checked={state} are controlled bindings; default values are uncontrolled. Do not switch a control between the two after mount. PulsePoint preserves selection and focus, and handles input, textarea, select, checkbox, radio and form-reset behaviour.
// Controlled: the binding owns the value.
<input value={name} oninput={setName(target.value)} />
<input type="checkbox" checked={agreed} onchange={setAgreed(target.checked)} />
// A file input is imperative — reach it with a ref.
<input type="file" pp-ref={file} />
<script>r##"
const file = pp.ref(null);
"##</script>A controlled value works the same when the control is a component's own root: <Select value={fruit}> keeps the page's fruit selected through every re-render, whether its options are plain <option>s or components of their own.
A controlled type="number" input compares its text with the bound value by number, as React does: while the state is 1, the user's own 1.0 or 01 stays as typed instead of being rewritten mid-keystroke. Parse in the handler — target.valueAsNumber — and keep the state numeric.
On a large page PulsePoint may defer the render an input event causes to the next frame. A discrete event — submit, click, keydown and the like — commits any such pending render before its handler runs, so a handler always reads the state every earlier edit produced, as in React: typing then pressing Enter, or an autofill followed by a submit in the same frame, never submits stale state. Events that carry their control's own new value (input, change, blur, focusout, and a checkbox or radio click) are not preceded by that commit, because re-rendering first would write the old controlled value back before the handler reads it.
Lists
For browser-owned collections, loop over a template. The collection must be iterable, and stable keys preserve row identity and local state. For a server-owned list rendered once in Rust, use Html::concat instead.
<ul>
<template pp-for="(item, index) in items">
<li key="{item.id}">{index}: {item.label}</li>
</template>
</ul>Keys must be unique among siblings, not across the page. Two loops in one component may share key values — two lists keyed by index, or a tab bar and a sub-tab list that both have a data row — and each still updates its own rows in place. Since Rahti 0.0.66 that holds for fast row patching too; on earlier releases the collision logged a "patching was abandoned" warning and slowed the whole component down. A duplicate key inside one list still warns and weakens diffing.
A component rendered inside a pp-for keeps its own loops. When a row component with a <script> writes its own <template pp-for>, that loop is compiled in the component's scope, not the surrounding row's, at any depth of nesting.
#[component]
pub fn Code() -> Html {
html! {
<p>
<template pp-for="(letter, index) in letters">
<span key="{index}">{letter}</span>
</template>
<script>r##"const letters = ["K", "7", "Q"];"##</script>
</p>
}
}
// In a page:
<template pp-for="row in rows">
<article key="{row.id}"><Code /></article>
</template>letters resolves in Code for every row the page's loop renders, even though the page never defines it.
Hooks
| Hook | What it gives you |
|---|---|
| pp.state(initial) | [value, setter]. The initial value may be lazy; the setter takes a replacement or (previous) => next. Equal values use Object.is and do not rerender. |
| pp.effect(fn, deps?) | Runs after commit; may return a synchronous cleanup. Start async work inside — do not return a Promise. [] runs once per mount. When a subtree is removed, all of its layout-effect cleanups run before any of its effect cleanups. An effect that sets state on every run is stopped after 50 renders in a row with [PP-WARN] Maximum update depth exceeded. |
| pp.layoutEffect(fn, deps?) | Runs synchronously after DOM mutation, before normal effects. For measurement. |
| pp.ref(initial?) | A stable { current } object, for pp-ref, portals and imperative handles. |
| pp.memo(factory, deps?) | Memoises a computed value. |
| pp.callback(fn, deps?) | Memoises a function identity, for stable subscriptions. |
| pp.event(fn) | A stable callback that reads the current state and props when a long-lived listener or library calls it. |
| pp.reducer(reducer, initial, init?) | [state, dispatch], with an optional initialiser. |
| pp.createContext(default) / pp.context(token) | Logical ancestor context. Read it in the render phase, not inside a later callback. |
| pp.portal(ref, target?) | Moves content elsewhere in the DOM while preserving logical ancestry, context and lifecycle. |
| pp.id() | A stable component-local identifier for id, for and ARIA pairs. |
| pp.errorBoundary() | [error, reset] catches this component's and descendants' render/effect failures. The error stays until reset; after five failures without reset, the boundary stops catching. A throw from the fallback itself goes to the next boundary up. Event-handler errors are logged separately. Distinct from server error.rs. |
| pp.syncExternalStore(subscribe, getSnapshot) | Subscribes to browser or external state. getSnapshot returns the same value until the store changes; one that builds a new object each call is reported with a [PP-WARN] on mount. |
| pp.imperativeHandle(ref, create, deps?) | Publishes a controlled imperative API. |
| pp.transition() | [isPending, startTransition]. Pending until the scope or returned Promise settles. |
| pp.deferredValue(value, initial?) | A value that updates after the current commit. |
| pp.optimistic(passthrough, reducer?) | [optimisticValue, addOptimistic]. Pending actions replay over the confirmed value until it changes. An action added inside a pp.transition() scope is also dropped when that transition settles, so a refused request rolls back. |
| pp.props | The props of the block that wrote the expression, read from its root attributes with kebab-case names in camelCase. A server value the component writes on its root arrives as a string; a caller's {…} prop it writes there keeps its real type. A Rust argument is here only when the component writes it on its root. |
pp.effect(() => {
const id = setInterval(() => setTick(t => t + 1), 1000);
return () => clearInterval(id); // synchronous cleanup only
}, []);Controller effects
A boundary re-renders when its own state changes and whenever anything above it re-renders, exactly as a React child does — server-rendered markup included. Every pp.effect written without a dependency list runs again with it.
An effect that drives a subtree imperatively — attaching listeners, starting an IntersectionObserver, MutationObserver or ResizeObserver, measuring a layout, applying an opening scroll or focus position — is a controller, and a controller takes []. Without it, every ancestor render tears the controller down and sets it up again, which undoes what the user has done since it mounted: a reader who had scrolled is put back where they started.
html! {
<div data-slot="viewport" pp-ref={viewRef}>
<script>r##"
const viewRef = pp.ref(null);
pp.effect(() => {
const view = viewRef.current;
if (!view) return;
const onScroll = () => { /* … */ };
view.addEventListener("scroll", onScroll, { passive: true });
const sizer = new ResizeObserver(() => { /* … */ });
sizer.observe(view);
// Once per element, not once per run of the effect.
if (!view.opened) {
view.opened = true;
view.scrollTop = view.scrollHeight;
}
return () => {
view.removeEventListener("scroll", onScroll);
sizer.disconnect();
};
}, []);
"##</script>
</div>
}[]on the effect. It mounts once, and its cleanup runs on unmount.- One-time setup is idempotent against the element, not the effect. A morph that replaces the element is a genuinely new subtree and does mount again; a property on the DOM node tells that apart from a rerun. An attribute would be visible in the served markup and reconciled away.
html! {
<section>
<button onclick={setCount(count + 1)}>"Count: "{count}</button>
<p>"Last ping: "{echo}</p>
<script>r##"
const [count, setCount] = pp.state(0);
const [echo, setEcho] = pp.state(null);
const ping = pp.event(() => setEcho(count));
pp.effect(() => {
window.addEventListener('app:ping', ping);
return () => window.removeEventListener('app:ping', ping);
}, []);
"##</script>
</section>
}const [pending, startTransition] = pp.transition();
async function save() {
await startTransition(async () => {
const saved = await pp.rpc("save_note", { text });
setNote(saved);
});
}const [likes, addLike] = pp.optimistic(confirmedLikes, (count, delta) => count + delta);
const [liking, startLiking] = pp.transition();
function like() {
startLiking(async () => {
addLike(1); // shown at once
try {
setConfirmedLikes(await pp.rpc("like_post", { post }));
} catch (failure) {
// refused: the guess is dropped when the transition settles
}
});
}// A provider is the lowercase token-derived `.provider` tag.
<theme.provider value="{scheme}">
<slot />
</theme.provider>
<script>r##"
const theme = pp.createContext("light");
const scheme = pp.context(theme);
"##</script>Runtime utilities
| Call | What it does |
|---|---|
| pp.mount() | Mounts the document. public/js/main.js calls it. |
| pp.redirect(url) | A PulsePoint-aware navigation. |
| pp.rpc(name, data?, optionsOrAbort?) | Calls a Rahti #[rpc]. See RPC & uploads. |
| pp.socket(name, args?, handlers?) | Opens a WebSocket to a #[socket] function, with heartbeats and reconnect after unexpected closes. See WebSockets. |
| pp.enablePerf() / pp.disablePerf() | Toggle runtime performance sampling. |
| pp.getPerfStats() / pp.resetPerfStats() | Per-component render-phase aggregates. |
In a Tailwind project, twMerge is a browser global published by public/js/main.js — not pp.twMerge, and absent from the plain CSS scaffold. No class attribute is merged automatically, so call it in a binding or script wherever class layers can conflict. Pass the server's class strings into the script as data and merge them there; never format a binding as a Rust string. Here the initial padding is px-8, and compact state replaces it with px-2 while keeping py-2.
// Class strings from Rust are data; the browser merges them in a binding.
let base_classes = "rounded-md px-4 py-2";
let caller_classes = "px-8";
html! {
<section>
<button
class={twMerge(baseClasses + " " + callerClasses + (compact ? " px-2" : ""))}
onclick={setCompact(!compact)}
>
"Toggle compact padding"
</button>
<script>r##"
const baseClasses = @{base_classes};
const callerClasses = @{caller_classes};
const [compact, setCompact] = pp.state(false);
"##</script>
</section>
}Type-check application modules
The bundle ships with public/js/pp.d.ts and a root jsconfig.json. Add // @ts-check to an application module and run npx tsc -p jsconfig.json to check it. The global pp exposes runtime utilities such as RPC, sockets, and navigation; hooks belong to the component's script. PulsePoint names the types for JSDoc. The declarations are generated with the bundle; do not edit them.
Native web APIs
A component's <script> is plain browser JavaScript, evaluated as a function body in the page's own global scope. It is not a sandbox and no build step rewrites it: window, document and navigator are the objects every other script on the page sees, and DevTools debug the script as written. Every web API the browser ships is therefore available to a component directly.
| API | For |
|---|---|
WebGPU (navigator.gpu) | GPU rendering and compute: large charts, simulations, image and video processing, in-browser ML inference. |
| Canvas 2D / WebGL | Drawing, charts, image processing. |
| Web Workers / OffscreenCanvas | Parsing, number crunching or rendering off the main thread. |
| WebAssembly | Native-speed modules compiled from Rust, C or Go. |
| Web Audio, media capture, WebRTC | Synthesis, camera, microphone, screen share, calls. |
| IndexedDB / Cache Storage, observers | Client storage; Intersection, Resize and Mutation observers. |
| Web Serial / WebUSB / WebHID / Web Bluetooth | Hardware, plus Clipboard, Notifications, File System Access and Geolocation. |
Who does what
| Job | Use |
|---|---|
| Data from the server | #[rpc] + pp.rpc, RpcStream, #[socket] + pp.socket, or @{Json(&value)} for the first render. |
| Values the markup shows | pp.state — a change re-renders only the nodes that differ. |
| Handles to browser objects | pp.ref — devices, buffers, contexts, workers, audio graphs, streams. A ref change never re-renders. |
| Acquire, feed, release | pp.effect — create on mount, push new state in when it changes, dispose in the cleanup. |
| The heavy work | The browser API itself. Shaders, threads, codecs and hardware run at native speed, outside PulsePoint. |
A WebGPU chart fed by an RPC. The server renders the first series into the page, and each click asks for a new one. One effect acquires the device and releases it on unmount; a second feeds it every new series.
use crate::rahti::{Html, Json, html, rpc};
fn series(points: u32, phase: f32) -> Vec<f32> {
(0..points.clamp(8, 512))
.map(|i| 0.5 + 0.4 * (phase + i as f32 / 6.0).sin())
.collect()
}
#[rpc]
pub async fn gpu_series(points: u32, phase: f32) -> Vec<f32> {
series(points, phase)
}
pub async fn page() -> Html {
let initial = series(48, 0.0);
html! {
<section>
<canvas pp-ref={canvas} width="640" height="240"></canvas>
<button onclick={load()}>"Refresh"</button>
<p hidden={gpuSupported}>"WebGPU is unavailable; drawing with Canvas 2D."</p>
<script>r##"
const canvas = pp.ref(null);
const gpu = pp.ref(null); // device, pipeline, buffers: never state
const [series, setSeries] = pp.state(@{Json(&initial)});
const [ready, setReady] = pp.state(false);
const gpuSupported = !!navigator.gpu;
// Acquire the GPU once; release it on unmount.
pp.effect(() => {
if (!navigator.gpu) { setReady(true); return; }
let cancelled = false;
initGpu(canvas.current).then((g) => {
if (cancelled) return g?.device.destroy();
gpu.current = g;
setReady(true);
});
return () => {
cancelled = true;
gpu.current?.device.destroy();
gpu.current = null;
};
}, []);
// Every new series: write it to a GPU buffer and draw.
pp.effect(() => {
if (!ready) return;
gpu.current ? drawGpu(gpu.current, series) : draw2d(canvas.current, series);
}, [series, ready]);
async function load() {
const values = await pp.rpc("gpu_series", { points: 64, phase: Math.random() * 6.28 });
setSeries(values);
}
// initGpu, drawGpu, and draw2d are plain WebGPU and Canvas code:
// navigator.gpu.requestAdapter(), adapter.requestDevice(),
// canvas.getContext("webgpu"), a render pipeline,
// device.queue.writeBuffer(...), a render pass.
"##</script>
</section>
}
}A continuous animation belongs to the browser's frame loop, not to the render cycle. State only starts and stops it; the per-frame value lives in a ref.
const frame = pp.ref(0);
const [running, setRunning] = pp.state(true);
pp.effect(() => {
if (!running) return;
let id = requestAnimationFrame(function tick(t) {
frame.current += 1; // a ref: no render per frame
renderFrame(gpu.current, t); // the GPU does the per-frame work
id = requestAnimationFrame(tick);
});
return () => cancelAnimationFrame(id);
}, [running]);A worker takes data from the server and hands its answer back to state. A WebAssembly module is loaded the same way: started in an effect, guarded against an unmount that lands first, and kept in a ref.
const worker = pp.ref(null);
const [result, setResult] = pp.state(null);
pp.effect(() => {
const w = new Worker("/js/parse-worker.js", { type: "module" });
w.onmessage = (event) => setResult(event.data);
worker.current = w;
return () => w.terminate();
}, []);
async function analyze() {
worker.current.postMessage(await pp.rpc("export_rows"));
}// A module in public/wasm/, compiled once per mount. WebAssembly
// compilation needs 'unsafe-eval', which Rahti's default CSP grants.
const wasm = pp.ref(null);
const [ready, setReady] = pp.state(false);
pp.effect(() => {
let cancelled = false;
WebAssembly.instantiateStreaming(fetch("/wasm/filters.wasm")).then(({ instance }) => {
if (cancelled) return;
wasm.current = instance.exports;
setReady(true);
});
return () => { cancelled = true; wasm.current = null; };
}, []);Rules
- Browser objects — GPU devices and buffers, contexts, workers, audio contexts, media streams, peer connections, observers, database handles — live in
pp.ref, never inpp.state. - Acquire in an effect with
[]dependencies and release in its cleanup:device.destroy(),worker.terminate(),audioContext.close(),track.stop(),observer.disconnect(). SPA navigation unmounts the component, so a missing cleanup leaks a GPU device or a running worker into the next page. - Cleanups are synchronous. Start async setup —
requestAdapter(),getUserMedia(),WebAssembly.instantiateStreaming()— inside the effect and guard it with acancelledflag. - Feed the API from a second effect whose dependencies are the state it reads. That effect is the bridge from server data to the GPU, worker or audio graph.
- Per-frame values live in refs and per-frame work runs on
requestAnimationFrame. Never call a state setter every frame. - Feature-detect (
if (!navigator.gpu)) and keep a fallback. WebGPU and most device APIs need a secure context: HTTPS, orlocalhostin development. - APIs that need a user gesture — the hardware
request*()pickers, clipboard writes, fullscreen, the firstAudioContext.resume()— run inside theon…handler that received it, not in an effect. - A component script has no static
import/exportand no top-levelawait. Load a library withimport()inside an effect, or with its own<script type="module">in a root layout. - Worker scripts,
.wasmmodules, shaders and model files go inpublic/, which serves them at the URL root. - Results that must stay authoritative or secret — prices, permissions, anything persisted — are computed in Rust behind
#[rpc]. The browser API is for rendering, interaction and client-side acceleration.
SPA navigation
After mount, PulsePoint intercepts eligible same-origin links, fetches the next document, morphs owned DOM, preserves component identity where it can, and manages focus, scroll, history, redirects and loading regions.
// Opt one link out of SPA interception — an external site, a download, a
// route that must reload the document.
<a href="/report.pdf" pp-spa="false">"Download"</a>Crossing root layouts
A body swap only makes sense while the document stays the same. When an application has more than one root layout, the two shells have different heads — different stylesheets, different scripts — and swapping one body into the other would leave the page running the wrong shell.
So PulsePoint compares the X-PP-Root-Layout header of the navigation response with the <meta name="pp-root-layout"> of the current document. When both are present and they differ, it abandons the SPA path and performs an ordinary full load. Equal values navigate in place as usual, and Rahti sends both halves for every page a root layout wraps.
Loading regions
While a navigation is in flight the runtime replaces the first element marked pp-loading-content="true" — or the whole <body> when nothing is marked — with the nearest loading region, then restores it from the response. Ownership, the literal-path walk and the transition JSON are all in Routing.
APIs that are not there
Do not invent React compatibility. PulsePoint v2 has no direct equivalent for forwardRef, component-wrapper memo, lazy, Suspense, useInsertionEffect, useActionState, useFormStatus, or a free-standing startTransition.
The full reference
Everything above is PulsePoint as a Rahti page meets it — the boundaries html! writes, the bindings it accepts, and the rules that keep the two dialects apart. The runtime itself is a separate project and is documented separately: pulsepoint.tsnc.tech has the deeper account of each hook, the scheduler, the reconciler, and the behaviour this page summarises in a table.
Two things to carry across when you read it. Its examples are written in plain HTML, because it is backend-agnostic; in Rahti the same markup is authored inside html!, so quoted text is a Rust string and a server value arrives through @{…}. And the version that matters here is the one in public/js/pp-reactive-v2.min.js, which cargo rahti upgrade replaces — a runtime feature documented upstream but not yet in the bundle your project ships is not one you have.
