Guides

The DevTools Contract

The __MOTIF_DEVTOOLS__ object turned on by useDevelopment(true); paths, events, the tree, component contents, the reactivity trace, counters, router and error records, write operations.

The core does not include a DevTools UI; it offers a single object that a UI can read and write. This page describes that object. It is for people writing a DevTools UI. A package author who wants to open their package's own state to DevTools reads the DevTools for Packages page; this page is the ground that one stands on.

Turning it on

DevTools is turned on only with app.useDevelopment(true). This call turns on development mode as well. useDevelopment(false) turns both off. A parameter in the address bar or a global written by hand does not turn DevTools on.

While it is on, globalThis.__MOTIF_DEVTOOLS__ holds the contract object; when it is turned off, the object is removed. While it is off, the core records nothing and produces no events. Counters and records are kept from the moment DevTools is turned on.

Module-level stores (export const cart = reactive({ … })) are created during import, that is, before the useDevelopment(true) call. When developing with the @motifx/compiler Vite plugin, every top-level const or let whose value comes from a reactive, useModel, createSignal, createComputed or createLazyComputed call of @motifx/core is named after its variable, in all .ts, .tsx, .js and .jsx files. These stores are listed in getStores() with a name (cart) and a file (src/stores/cart.ts, relative to the Vite root). Nothing is added to a production build.

Early stores held in a field of a component or a service enter the list through the scan done in the getStores() call; only stores held inside a closure and not named by the compiler stay invisible.

import type { MotifDevtools } from "@motifx/core/devtools";

app.useDevelopment(true);
const devtools = (globalThis as any).__MOTIF_DEVTOOLS__ as MotifDevtools;

app.useDevelopment(true);
const devtools = globalThis.__MOTIF_DEVTOOLS__;

version is the version of the contract, 2 today. It goes up when the meaning of a field changes; adding a new field does not change the version. coreVersion is the version of the @motifx/core package the application runs on ('1.2.0').

Paths

Components have no id numbers. The tree is a forest: [] is the virtual Application node that holds all the roots, the first number of a path picks the root, and the rest are controls indices down from that root. The roots, in order, are the application shell that run() builds ([0]), the page layer app.layer (Layer) if it has been created, and the host component wrapping the body of every window opened or connected with app.windows (Window); the windows are in the order of app.windows.list. [0, 2] is the shell's third child, and [1, 0] is the layer's first child. The path of a component that is under no root is null.

A path depends on the component's position in the list. When a component is added in front of it or the list is re-sorted, the path changes. That is why every addition, removal and move in the tree is reported with the tree:changed event; the event carries the current paths of the parent components that need to be read again. When the layer is created, or when a window opens or closes, the list of roots changes; that is reported in the same event with the path [].

Events

on(fn) adds a listener and returns a function that removes it. Every event has the form { type, payload }. The payload of component events always contains { path, type, tag }; for a component that is under no root, path is null.

There is no event for the moment a component enters the page. Whether a component is on the page is read from the connected field in the tree.

Tree

• getTree(path = [], depth = Infinity): returns the component at the path and its subtree, down to the given depth, as plain data. Every node carries { path, type, tag, built, visible, waiting, disposed, connected, document, childCount, children? }. type is the class's name for a class component and the function's name for a function component. The [] node's type is Application and its tag is #roots; the shell root is named Component, the layer Layer, and a window root Window, and the window root also carries the window's title as title. document is the position, in getDocuments(), of the document the element is in, the page being 0; a component whose element the application moves to another document itself keeps its place in the tree, and only document points to that document. A list ({items.map(…)} in JSX, or bindings.list) adds two fragments: List, which is the spot of the .map() expression among its siblings, and ListItems inside it, which is the range where the items sit; a component that builds its own list keeps its name and carries the ListItems. A condition appears under the name of the binding that builds it: Ternary (bindings.ternary, a ? b : c in JSX), When (bindings.when, a && b in JSX), Expression (a bindings.method that returns a component, {() => …} in JSX) or Switch (bindings.switchCase); as long as it shows nothing, an Empty sits inside it in place of what it shows. x-wait and x-display add nothing to the tree: the component keeps its name and appears as waiting. Nodes beyond the depth have no children, but they do have childCount.
• getElement(path): the DOM node of the component at that path; for highlighting and scrolling. null for [].
• pathOfElement(node): climbs up from a DOM node and returns the path of the first component, whatever document the node is in; null if it is under no root.
• getDocuments(): the page's document and the documents connected to the application (app.windows windows, those connected with connectDocument), in the order the document field counts.

tag is the element's tag name; #fragment for a fragment and #text for text.

Component contents

inspect(path) returns the inside of a single component as plain data. No internal object is created on the component while reading, and no user code is called.

readValue(path, source, keys) opens one level of a value inside props, functionProps or fields (source): keys is the path to the value (['stat', 'tags']). The result is { ok: true, value: { value, entries: [{ key, value, getter? }], total } } in the same preview form; at most 100 fields are returned, and total gives the full count. Getters and functions are never called: a getter appears as getter: true, and a path that goes through a getter returns { ok: false, error: 'getter' }. Arrays, plain objects, class instances, Map (with keys as text) and Set (by position) can be opened; a path that goes through a signal or a computed continues into its value. readStore(id, keys) opens the inside of a store in getStores() the same way; for signals and computeds, the inside of the value is opened.

getServices() lists the services registered in the application as { token, lifetime, created }.

getScopes() lists the DI scopes and the services created in each:

A scope opened with createScope is listed for as long as it is used, and leaves the list with dispose(). The scopes:changed event says when to read the list again.

readService(scope, token, keys) opens one level of a service instance in the same form as readValue: scope is the number in getScopes(), and token is the name shown in that scope's services list. Singletons are read from the root scope, and scoped services from the scope that created them. Reading never creates the service: a service that has not been created yet returns { ok: false, error: 'no service' }. Only the instance's own fields are listed; getters on the class and #private fields are not.

Reactivity trace

inspect(path).effects lists the effects the component owns. A record looks like this:

const effect = {
  kind: "binding:textContent", runs: 4, lastDuration: 0.1,
  lastTrigger: { target: { kind: "object", type: "Object", keys: 7 }, key: "title" },
  deps: [{ target: { kind: "object", type: "Object", keys: 7 }, key: "title" }],
};

const effect = {
  kind: "binding:textContent", runs: 4, lastDuration: 0.1,
  lastTrigger: { target: { kind: "object", type: "Object", keys: 7 }, key: "title" },
  deps: [{ target: { kind: "object", type: "Object", keys: 7 }, key: "title" }],
};

kind tells where the effect comes from: binding:<property>, list, when, method, ternary, watch, switch, conditional, class, attr:<name>, style, virtual-data, computed. Those created directly with effect() appear as effect and have no owner.

The reactivity:flush event arrives once per round. triggers carries the changes that started that round, with their counts, and effects carries the effects that ran, with the paths of their owning components. If the changed object belongs to a store in getStores(), the trigger also carries a store: { id, path } field: path is the keys from the store's root to the changed object (a change to stats[1].value arrives as { path: ['stats', '1'] } and key: 'value'). For signals and computeds the key is value. A thousand changes to the same value in one round are still a single event.

Every flush has an increasing id. A trigger that happens inside an operation carries an operationId; operations lists the ids of the operations the triggers of that round belong to. Changes to the same value in different operations are counted separately.

Counters

getCounters() returns, in a single call, an object that carries these fields:

All the fields are numbers; byType is an object from type name to number.

live goes up when a component is built and down when it is disposed. inTree, bindings and listeners are counted by walking the tree at the time of the call. notInTree is the components that are alive but not in the tree; if it does not drop even after leaving the page, those components are being held somewhere. The counters start from zero every time DevTools is turned on.

Router, errors and warnings

• getRoute(): the current { uri, params, chain }.
• getNavigations(): the last 50 navigations, { requested, uri, outcome, reason?, params, duration, at }. outcome: done, skipped, cancelled (reason: middleware, onLeave, guard or the reason given by onLeave), notFound, error. When a guard redirects to another address, two records are created: first the redirected navigation, then the outer navigation that keeps the requested address and the reached address apart.
• getRoutes(): the defined routes.
• getWarnings(): warnings are merged by code and message: { code, message, details, count, firstAt, lastAt }. At most 200 records are kept; when full, the one not seen for the longest time is deleted. details stays as it was on the first occurrence.
• getErrors(): errors are merged the same way, by context, name and message; at most 100 records.
• getStores(): the reactive, useModel, signal and computed records created while devtools is on and still in use; stores held in a field of a component or a service that were created before devtools was turned on are also taken into the list during the scan. Each record is { id, name, file?, type, value, stale?, released?, holders }; the name and file fields of a module store come from the compiler (see above). holders lists the components ({ kind: 'component', path, type, field }) and services ({ kind: 'service', token, lifetime, field }; field: null if the service itself is the store) that hold the store in one of their fields; the list is worked out on every call by scanning the component tree and the created services, without calling getters. An empty list means the store is held at module level or inside a closure. A store that used to be held in a field of a component or a service and no longer is comes with released: true (for example the state field of a component that has closed). An unused store drops out of the list when the garbage collector collects it; the browser decides when that happens. The value of a signal or a computed is its current value; a computed's getter is not run while reading it, and a computed that has never been calculated or is stale comes with stale: true.

Write operations

Every write goes through the public API that application code uses too. The result is { ok: true, value? } or { ok: false, error }; the operations do not throw.

The keys __proto__, prototype and constructor are not written.

Next step

A package that shows its own state in DevTools registers with registerDevtools: DevTools for Packages. For a summary of every exported symbol, go on to API Reference.