Browser execution and network access

Trusted input

Notebook cells run as JavaScript in the page that hosts the widget. Treat imported Notebook Kit HTML, ObservableHQ notebooks, and their remote modules as trusted code because they can use the page's browser privileges.

JavaScript evaluates in the browser page that hosts the view. Notebook Kit supplies the cell languages and standard library. Python constructs the definition and sends values to its browser runtime.

Notebook Kit's node, python, and r cells read precomputed interpreter results from .observable/cache paths served by the host page. Calculate with the host Python kernel through Python variables.

Runtime profiles

The notebook source selects the runtime profile before a view starts. The profile is fixed for the notebook session and inherited by each view.

Source	Profile
Python-authored cells	Notebook Kit
Notebook Kit HTML	Notebook Kit
Observable model with stdlib: "1" or classic nodes with no library declaration	Observable
Observable model with stdlib: "2" or native cells with no library declaration	Notebook Kit
HTML serialized by to_notebook_html()	Preserved source profile

The Notebook Kit profile uses the builtins exported by Notebook Kit. The Observable profile uses the classic Observable standard library, which adds classic names such as require and DOM. Both profiles receive view-scoped FileAttachment, document, width, and dark values from pyobservablejs.

Notebook Kit SQL cells retain native database results, including columnar Apache Arrow tables. Classic Observable imports expose row arrays, so dependent cells can call methods such as .map(). Their queries follow the cell lifecycle and can stream results.

Builtins

The selected profile resolves builtins when cells reference them.

Builtin	Contract
Inputs	Creates controls, tables, and other input elements. Pass an input to view(...) to expose its changing value.
Plot	Creates charts from data and mark specifications. Plot.plot() and a mark's .plot() return browser elements.
sql	Builds composable SQL query fragments. A query's .query(db) executes it against a database client.
html, md	Creates reactive HTML and Markdown DOM values from tagged templates.
Generators	Provides input, observe, and queue in both profiles. Other methods come from the selected standard library.
Mutable	Creates a reactive source with a .value getter and setter. Consumers rerun after the value changes.
width	Yields the notebook root content width through Notebook Kit’s Generators.width(root). The first value arrives after browser layout, then updates after resize.
dark	Yields whether the notebook root uses a dark color scheme. Theme changes rerun dependent cells.

The Notebook Kit profile also exposes sample datasets such as aapl, cars, and penguins. Runtime-owned builtin names cannot be Python variables. See the naming rules in Variables and serialization.

Module imports and the network

Standard JavaScript cells can import an npm package or browser module:

obs.js(
    """
    import {format} from "npm:d3-format@3";

    const compact = format(".2s");
    display(compact(42000));
    """
)

External libraries, sample datasets, module imports, and source notebooks can require browser network access. Notebook Kit resolves npm: specifiers from jsDelivr, a package delivery network, at render time. The page's content security policy, which limits browser scripts and network requests, must permit every package, data, and module origin used by its cells. To carry local source and data with a widget, embed modules with rewrite_imports=True and data with embed_file_attachments=True. Library and dataset builtins can still fetch remote resources. See Add files and local modules.

Network access happens at two distinct times:

When	What	Where it runs
Notebook construction	from_observablehq fetches original notebook source. Local files are read and embedded.	Python
View render	npm imports, URL-backed attachments, remote datasets, imported notebooks.	Browser

Promises, generators, and invalidation

Notebook Kit tracks asynchronous values as part of the graph.

Value	Evaluation	Invalidation
Promise	Dependent cells wait for the resolved value.	A stale resolution is ignored. The operation continues unless the cell cancels it.
Generator or async generator	The first yield defines the value. Later yields rerun dependent cells.	The runtime calls the generator's return() method.
invalidation	Provides a promise for the current cell evaluation.	Resolves when the evaluation is invalidated or its runtime is disposed.

Use invalidation to release resources owned by a cell. See Display views for the corresponding Python lifecycle.