API reference > @kontsedal/olas-devtools

olas-devtools package

Classes

Class	Description
DevtoolsStore	Subscribes to a root's debug bus and maintains live state for the devtools panel. Exposes signals so the React layer can consume them via@kontsedal/olas-react's useValue(). Pure logic — no DOM, no React. Construct one per root. Applying one event costs O(1) plus O(path depth): nothing here scans the tree or a log.

Functions

Function	Description
DevtoolsLauncher(props)	A floating devtools window for one root, behind a launcher button in the bottom-right corner. The window's header drags it and its corner grip resizes it. Position, size, and open and minimized state persist tolocalStorage under storageKey. Render <DevtoolsLauncher root={root} /> once, near the app's root, typically only in development builds. The launcher owns the panel's store: it records from mount, and the history survives closing and minimizing the window. A devtools error never unmounts the host app; a failure outside the panel hides the launcher.
DevtoolsPanel(props)	Drop-in devtools panel for an Olas root. Features: - **Omnibox** (/ to focus) — one search over controllers, queries, mutations, form fields and payloads; Enter jumps to the match. - **Timeline** — every event in a ring buffer, grouped by cause, with one lane per plugin that can be shown or hidden. - **Tree / Cache / Inspector / Mutations / Fields** — each a windowed list that mounts only the rows in view. - **Filter** field per tab — text-matches kind, path, name, payload. - **Pause** toggle freezes the log without stopping ingestion. Styled inline (no CSS import needed) and scoped to the .olas-devtools-* class prefix. Hosts override the palette via --olas-* custom properties. A render error inside the panel shows in the panel, never unmounting the host app. Spec §14.
formatPath(path)	Render a controller path / query key as a compact string. An object member of a key renders as JSON cut at 60 characters, so ['users', { page: 1 }] and ['users', { page: 2 }] read differently. Never throws, so a null-prototype object in a key renders too.
formatPayload(value, maxLen)	Render a payload (props, vars, result, etc.) as a single-line string for the panel. Cuts at maxLen so a giant blob doesn't blow up the layout. Never throws: a cycle reads [Circular], and a value that cannot be read at all reads [unserializable].
formatTime(t)	Render an HH:MM:SS.mmm timestamp from epoch ms.
insertNode(root, path, props, debug)	Insert (or update) a node at path inside the tree. Auto-creates any missing intermediate ancestors as 'active' placeholders. Returns a NEW tree object (immutable update).
setNodeDebug(root, path, debug)	Set the debug variables record on the node at path. Returns the tree unchanged if the node doesn't exist (out-of-order delivery).
setNodeState(root, path, state)	Set state on the node at path. If the node doesn't exist (out-of-order event delivery), the tree is returned unchanged.

Variables

Variable	Description
DEFAULT_MAX_TIMELINE_ENTRIES	Capacity of the unified timeline's ring buffer (events$). The panel renders it through a windowed list, so the bound is about memory, not DOM. Past it the oldest event is overwritten and droppedEvents$ counts it.

Type Aliases

Type Alias	Description
CacheEntry	One entry in the cache timeline.
ControllerNode	Per-path node in the live controller tree. state reflects the most recently observed lifecycle event; path is the array reported by the devtools bus.
DevtoolsLauncherProps	Props of <DevtoolsLauncher>: the panel's props, plus where the window keeps its state and where it first opens.
DevtoolsPanelProps	Props of <DevtoolsPanel>.
DevtoolsStoreOptions	Options for new DevtoolsStore(options?). Every field is optional.
DevtoolsTab	A panel tab, by id. defaultTab takes one.
FieldEntry	One entry in the field validation log.
MutationEntry	One entry in the mutation log. id numbers the log entry; mutationId is the mutation's own id, absent for an inline spec without one. durationMs is set on success/error when the store saw the run start: it pairs the two by the run id core sends as causeId. A cancel closes a run core cancelled, and says why; the store logs one only for a run it saw start.
SearchGroup	Every hit of one kind: the first limit of them, and how many matched.
SearchHit	One omnibox result: what to show, and the tab + row key a jump lands on.
SearchKind	What a search result points at. Groups come back in this order.
SearchStats	Index diagnostics. indexed counts values turned into search text.
TimelineEvent	One entry in the unified causal timeline — a normalized view over EVERYDebugEvent, ordered by seq. The panel groups these by causeId into collapsible cause-chains and renders a structural before/after diff forcache:set-data.