Use spaday in a Jupyter notebook¶
This guide shows you how to render a spaday UI in a notebook and round-trip its state with Python — no server. It works in Jupyter (Lab / Notebook / Colab / VS Code) and the wider anywidget ecosystem (Marimo, Shiny-for-Python, Solara, Panel) — and with no install at all in JupyterLite, where the kernel itself is WebAssembly (hosted demo at /spaday/lite/).
Install the host:
pip install "spaday[widget]"
Render a tree¶
Wrap any component tree in Widget and return it from a cell:
from spaday import Widget, element
Widget(element("button").text("Run"))
The widget bundles the spaday runtime and wasm core. It renders core spa-* components and native HTML
elements without additional packages.
Load a component package¶
Install the peer in the notebook’s kernel, then select it with packages=:
%pip install spaday-webawesome
from spaday import Widget, element, ui
w = Widget(
element("section", ui.TextInput(label="Name").bind("value", "name", mode="two-way")),
packages=["webawesome"],
state={"name": "Ada"},
)
w
The selected package’s design also applies to subsequent w.update(...) calls. Browser assets come
from the installed Python package over binary widget comms. Scripts and styles load before the tree
mounts and are shared across widgets in the same browser document. Displaying five widgets does not
register their custom elements five times or transfer five copies of the package.
After installing the packages and loading the notebook host, WebAwesome controls can render offline in JupyterLab and JupyterLite. Features that fetch external data or optional remote icons still need those resources. Package loading requires browser support for multiple import maps and permission to load blob modules and styles. Reload the notebook document after upgrading a loaded package. Conflicting library versions or custom elements registered outside this loader produce an error.
For package authors, the loader follows relative imports, declared bare import mappings, dynamic
imports, and stylesheet imports and URLs within assets_dir. Use import.meta.resolve("./asset")
for packaged images or WASM fetched at runtime. Arbitrary URLs constructed from import.meta.url
and worker module graphs are not supported by this loader. Test packages with such assets in a
notebook before advertising notebook support.
Update the rendered tree¶
Keep a reference and call update to replace the tree; the browser applies a minimal diff (live
elements are preserved, not rebuilt):
w = Widget(element("div").text("Lamp"))
w # display it
w.update(element("div").child("Lamp").child(element("div").text("Fan")))
Back reactive bindings with state¶
Pass a state dict to drive the tree’s reactive bindings. A two-way-bound control
updates the state from the browser, and assigning w.state updates the control:
from spaday import Widget, element
w = Widget(element("input", type="checkbox").bind("checked", "lamp", mode="two-way"), state={"lamp": True})
w
w.state # -> {'lamp': True}; flip the switch, then re-read -> {'lamp': False}
w.state = {"lamp": True} # turns the switch back on
React to changes (including browser-driven ones) with on_state:
w.on_state(lambda state: print("state:", state))
Bind transports models¶
Use session= for validated models, binary fields, or client-owned state. A widget accepts a
transports.Session or an existing transports.Server; state= and session= are mutually exclusive.
Select models with Wire, omitting its WebSocket URL:
from pydantic import BaseModel, Field
from transports import Session
from spaday import SetField, Widget, Wire, element
class Config(BaseModel):
bpm: int = Field(120, ge=1)
sample: bytes = b"pcm"
class Status(BaseModel):
playing: bool = Field(False, json_schema_extra={"owner": "client"})
config, status = Config(), Status()
session = Session()
config_id = session.host(config)
status_id = session.host(status)
tree = element(
"section",
element("label", "Tempo", element("input", type="number").bind("value", "config.bpm", mode="two-way")),
element("button").text("Play").on("click", SetField("status.playing", True)),
element("output").bind("textContent", "status.playing"),
)
w = Widget(tree, session=session, wires=[
Wire(model=config_id, namespace="config"),
Wire(model=status_id, namespace="status"),
])
w
Changing tempo submits an edit validated by Config. Invalid values revert and publish an error
under $errors.config.bpm. The owning view’s Play action updates locally before the kernel replies;
update_interval controls how often client-owned updates are sent (default 0.25 seconds).
Updates within one interval coalesce to the latest value per field. A value followed by a reset can
reach Python only as the reset; adding unique request tokens does not preserve intermediate values.
Use batched bindings for status and latest selections. For separate interactions while connected,
flush after each binding update with requestWire(element, namespace).client.flushOwned().
This does not acknowledge application completion or replay requests after disconnect. See
state and request delivery for event ordering,
shared-client effects, and request-handler alternatives.
Python assignments push automatically while the widget is open in an asynchronous kernel:
config.bpm = 140
config.sample = b"new pcm"
Bytes travel as separate comm buffers and arrive as Uint8Array values in browser bindings. Keep
large binary configuration separate from client-owned status models: ownership resynchronizes the
status model with a full snapshot.
Display w in another cell to open another view. Each display has a separate client; exactly one
owns a given client-owned field, and other views observe it. Closing an owning view transfers
ownership. Transports heartbeats expire abandoned views after the reconnect window. Call w.close()
to close all views and release the widget’s connections and sync task.
With several wires, each must select a model and use a distinct, non-overlapping namespace. Model
selection accepts numeric IDs or unique type names. flatten and connected work as on served pages;
namespaced wires default to <namespace>.connected. Codec, ownership participation, and
update_interval apply to the shared connection and must agree across the wires. Notebook codecs
are json, msgpack, and cbor. WebSocket URLs, session routing, batching, and reconnect/retry
settings are not notebook options.
One kernel timer drives transports.sync() per shared Server. Widgets given the same Session reuse
a Server. In a synchronous host, or when the application already drives comm syncing, use
autosync=False and call transports.sync(w.server) after mutations. Transports’ socket-oriented
autosync() is not the comm driver.
Configure session, wires, packages, and design when constructing the widget. update(tree)
changes the tree using that configuration; it does not replace the connection or selected packages.
Close the widget and construct another to change those settings. Removing one displayed view releases
that view’s ownership; w.close() releases every view and this widget’s share of the kernel sync task.
Notebook wires accept the shared Wire defaults, but reject nondefault WebSocket-only options rather
than silently ignoring them: url, session, batch, reconnect, retry, and authority.
Keep update_interval in seconds; the WebSocket-only retry setting uses milliseconds.
Handle client-owned state in a custom element¶
Bind $owned.status.playing to show whether this view owns the playing field in the status wire.
The flag updates on ownership transfer and becomes false on disconnect. Use ownership flags for
controls that should only be available in the owning view.
Commands issued with session.command(model_id, field, value) remain queued until an owning client
handles and acknowledges them. A custom element can request its wire in connectedCallback, before
initial snapshots or commands arrive:
import { requestWire } from "@1kbgz/spaday";
class PlaybackControl extends HTMLElement {
connectedCallback() {
const wire = requestWire(this, "status");
if (!wire) return;
this.stop = wire.client.onCommand((command) => {
if (command.id !== wire.link.modelId || command.field !== "playing") return;
wire.store.set("status.playing", command.value.Bool);
wire.client.ackCommand(command);
});
}
disconnectedCallback() {
this.stop?.();
}
}
customElements.define("playback-control", PlaybackControl);
Put this JavaScript in the component package selected by the widget. Apply the requested operation
before acknowledging it; for asynchronous operations, acknowledge after successful completion.
Transports delivers commands to the owner and replays pending commands to newly registered handlers.
wire.link.modelId becomes available after the snapshot; use wire.link.onModel(callback) when a
component needs notification of model discovery. Unsubscribe when the element disconnects.
requestWire finds the nearest widget root, including across shadow roots. Omit its namespace only
when the widget has one wire. To avoid importing the runtime, dispatch a bubbling, composed
spaday:wire-request event with a mutable detail = {namespace: "status"} object and read
detail.wire synchronously afterward. The returned context contains client, link, store, and
namespace. The root also emits spaday:wire-client after mount for host-level listeners.
Handle a SendPatch intent¶
A SendPatch action surfaces an intent the host forwards to Python. Register a handler
with on_intent:
w.on_intent(lambda content: print("intent:", content)) # content is {"type": "spaday:patch", "detail": {...}}
In session mode, SendPatch("config", "bpm", 120) also edits the config.bpm binding through
transports, with the same validation as a two-way control. The model argument names the wire’s
namespace; use an empty string for a wire without a namespace.
For most cases prefer a two-way binding over SendPatch + on_intent — the binding already carries the
control→state edit.
Embed in Panel¶
Because the widget is an anywidget, Panel renders it directly:
import panel as pn
pn.extension()
pn.panel(Widget(element("button").text("Run")))