DevTools.

What it is

DevTools is a second, opt‑in entry point of the same package. It renders a panel inside its own shadow root — floating or docked to any edge — so it cannot be restyled by the app it inspects and can still debug a program that is throwing.

Everything you see is the real runtime. State edits go through the genuine reactive pipeline, prop overrides enter the component where the value normally would, the profiler reads the actual per‑instance memoization decisions, the timeline is fed by the real effect runner, and the network tab taps the real HTTP layer. Nothing is simulated.

Enable it

The runtime never installs the panel. You do, from anywhere in your own code, and the whole surface is one function call.

From a bundler

import "aktion-runtime";                              // registers <aktion-app>
import { mountDevtools } from "aktion-runtime/devtools";

mountDevtools();   // opens immediately, attaches to every app on the page

That is the whole setup. mountDevtools() installs the global hook, appends the panel to document.body, and adopts every <aktion-app> already in the document — including apps that mounted long before the panel opened.

From a CDN

<script type="module">
  import "https://cdn.jsdelivr.net/npm/aktion-runtime/dist/aktion.js";
  import { mountDevtools } from "https://cdn.jsdelivr.net/npm/aktion-runtime/dist/devtools.js";
  mountDevtools();
</script>

Both bundles are self‑contained ES modules, so no build step is involved. The DevTools bundle talks to the runtime only through the global hook, which is why loading them from two different URLs still works.

Behind a flag or a keyboard shortcut

Because it is a separate entry, a dynamic import() keeps the panel out of your main chunk entirely until someone asks for it.

let devtools = null;

async function toggleDevtools() {
  if (!devtools) {
    const { mountDevtools } = await import("aktion-runtime/devtools");
    devtools = mountDevtools();     // first press mounts it, already open
  } else {
    devtools.toggle();              // later presses just show / hide
  }
}

// Ctrl+Shift+D, or ?debug in the URL.
addEventListener("keydown", (e) => {
  if (e.ctrlKey && e.shiftKey && e.key === "D") toggleDevtools();
});
if (new URLSearchParams(location.search).has("debug")) toggleDevtools();

Aktion ships no keyboard shortcut of its own, so the binding above is yours to choose. Mount once and keep the controller: every call to mountDevtools() adds another panel element, even though they all share one hook and one event stream.

Try it live

The app below is an ordinary <aktion-app> rendered from the program on the left. Press Launch DevTools to open the real panel over this page, then interact with the app and watch it fill up. Press Ctrl / Cmd + K inside it for the command palette, or ? for the shortcuts.

$count = 0
$seconds = 0
$user = { name: "Ada", role: "engineer", prefs: { notify: true } }

// An interval effect: one `run` event per second, so the Effect timeline fills live.
$effect(() => { $seconds = $seconds + 1 }, ["every(1000)"])

// A user component: its own instance, and its own memo record, in the profiler.
function Stat(label, value, tone) {
  return Card([Column([
    Text(label, { variant: "small", tone: "muted" }),
    Text(value, { variant: "title" }),
    Badge(tone, { tone: tone })
  ], { gap: "xs" })])
}

$app(Column([
  CardHeader("DevTools demo", { subtitle: "Open the inspector, then interact." }),
  Row([Stat("Count", `${$count}`, "info"), Stat("Uptime", `${$seconds}s`, "success")], { grow: true }),
  Button("Increment", { onClick: () => $count = $count + 1, variant: "primary" }),
  Text(`Signed in as ${$user.name} (${$user.role})`, { variant: "small", tone: "muted" })
], { gap: "md" }))

Three things to look at, in order:

• State — expand user, then prefs, click notify, type false, press Enter. The write lands in the real store and the app re‑renders.
• Profiler — press Increment a few times. Each press adds one blue bar to the commit strip; the first bar of the session is green.
• Effects — the every(1000) effect adds a run event per second, so its lane grows while you read this.

The command palette, and the keyboard

Fourteen tabs is more surface than anyone wants to hunt through. Press Ctrl / Cmd + K anywhere on the page — the panel does not need focus — and type: the palette fuzzy‑matches every tab and every action the panel can perform, so pick an element, arm a break, reset the theme, or export the session are one phrase away instead of three clicks inside a tab you have not opened.

• Type a word that names a tab — theme, network — and the first result takes you there.
• ↑ / ↓ move, Enter runs, Escape closes.
• Matching is on the action, its group, and its synonyms, so curl finds the copy button and slow finds the delay rule.

Press ? for the full list of shortcuts at any time:

The palette, the picker, and the Alt tab shortcuts work anywhere on the page — you are usually clicking the app, not the panel, when you want to change what the panel is showing — and they never fire while you are typing in the app's own fields. The rest need the panel focused; click it once.

Watching an app while you use it

Four things the panel can do continuously, so you can put it in a corner and go use the app rather than clicking back and forth. All four are switches in Settings → While you work, and each is off by default because each costs something.

• Watch expressions. Pin an Aktion expression — $todos.length, $user.role, $cart.items[0].qty — in the Console tab, or with the eye button on any REPL result. It is re‑evaluated on every render, so the value moves as you click. Watches are remembered across a page reload, and the Overview tab shows them too.
• Highlight re‑renders. Flash a box over every component that actually re‑rendered in the last commit — memoized instances are not flashed — which is the fastest way to see that one keystroke is repainting a whole page.
• Break on change. Arm an atom from the State tab (the ● button beside it) and the browser pauses in the debugger the moment anything writes to it, with the write still on the stack. Needs devtools open in the browser, the way any debugger statement does.
• Browser performance marks. Mirror every commit into performance.measure(), so Aktion commits appear as named measures in the browser's own performance profiler, lined up with layout, paint, and your own marks.

Alongside them, the panel reports main‑thread blocking it observed (via PerformanceObserver's long‑task entries) on the Overview tab, so a janky interaction points at the frame that caused it.

Component inspector

The Inspect tab is the one that changes how you debug an Aktion app. It shows the component‑instance tree the renderer actually built — not the DOM, and not the source — and lets you change what any instance received and what it holds.

The element picker

Press ◎ Pick and the page gets a crosshair. Hover anything and the real box model is drawn over it — margin, border, padding, content, each labelled with its measured value — with a tooltip naming the component, the element, and its size. Click to select; Esc cancels.

The picker reaches inside the app's shadow root. A naive implementation cannot: document.elementFromPoint stops at the <aktion-app> host, so every hover would resolve to the same element. This one descends through each shadow root until it reaches a leaf, then walks back up to the nearest component instance — so clicking the text inside a Badge selects the Badge, not an anonymous <span>. Hovering the panel itself is ignored, and clicking it does not cancel the pick you are halfway through.

Reading the component tree

Every row is one instance: the component name (your function components in purple, library primitives in grey), the author's key: if there is one, a memo chip when the last commit skipped its body, its prop count, how many times it has rendered this session, and its last self time. Hovering highlights it on the page; clicking selects it. A row marked no dom rendered a fragment with no host element (a Show / Async / Lazy branch), so there is nothing to highlight.

The tree comes from the instance keys the renderer derives, which encode the whole hierarchy — $/0#Page@1:0/1#Card@7:4>0#Button@9:12 is a Button inside a Card inside a Page. Filtering flattens the tree into a result list, because keeping the hierarchy would mean showing unmatched ancestors as though they matched.

Given room — a panel wider than about 700 pixels, so any side dock or a floating panel at its default size — the tab splits: the tree on the left, the selected instance's detail on the right, both scrolling independently. Narrower than that, the detail replaces the tree, because two 300‑pixel columns help nobody. ↑ / ↓ walk the rows, ← / → collapse and expand, and the ⊟ / ⊞ buttons in the toolbar collapse or expand everything at once.

Every other tab that names a component links here: a bar in the flamegraph, an effect's owner, a timeline row. Following one of those links clears whatever was hiding the row — a collapsed ancestor, a filter that excludes it, the Library toggle when the target is a library component — tells you what it cleared, and scrolls the row into view, so the jump never lands on an empty‑looking tree.

Editing props, hooks, and component state

Selecting an instance opens six panes. Everything editable is edited in place: click the value, type, Enter to commit, Esc to cancel. Input is parsed as JSON when it can be (42, true, ["a"]) and as a plain string otherwise, so Ada is not rejected for being invalid JSON.

The ＋ row at the bottom of the Props pane adds an override for a prop the call site never passed — which is usually the interesting experiment. Trying variant: "danger" or sx: { padding: 24 } on one live component takes a second and leaves no edit behind in the program.

Remount drops the instance's memo, hook cells, and UI‑state slots so it mounts fresh — the fastest way to check that a component's initial state is what you think it is, without reloading the page.

State inspector

The State tab is a live tree of every reactive $state atom, updated on every state flush — including flushes the render gate decides not to re‑render for. So the tree mirrors the store even when the screen does not move.

Reading the tree

One row per atom, indented by depth. Values are coloured by type and collapsed to a preview until you expand them.

Only $‑prefixed reactive atoms appear here. Plain top‑level let / const bindings are re‑seeded every render and are not part of the store, so they are never listed — see Reactivity for the distinction.

Editing a value

Click any leaf value to turn it into an input. Enter commits, Escape cancels, and clicking away also commits. What you type is run through JSON.parse first and kept as raw text only if that fails.

A dotted row such as user.prefs.notify writes through the store’s path API, which rebuilds user immutably: sibling fields survive and every dependent of user wakes up. The edit is indistinguishable from one an onClick handler would make.

Filtering and reactivity heat

Every top‑level atom carries a heat badge: a bar sized against the busiest atom and a count of how many flushes changed it this session. The toolbar shows the session total.

• Filter atoms… — case‑insensitive substring match on top‑level atom names. Expanded children are not searched.
• Sort by activity — ranks atoms by change count, descending, falling back to alphabetical for ties. Off by default; the default order is alphabetical.
• 12 atoms · 1.4k changes — atoms in the snapshot, and every counted change across them.

Sort by activity is the fastest way to find the atom your UI actually churns on. An atom with a heat count far above the rest is usually a timer, a scroll position, or a pointer coordinate that belongs in an instance hook rather than the global store.

Time travel

The runtime attaches a $state snapshot to every commit, so the State tab keeps a bounded history of moments you can recognise — “two clicks ago” — rather than raw flushes. Drag the scrubber back and the tree shows that snapshot, read‑only, with a banner saying how long ago it was. Restore hydrates it back into the live store; Live follows the app again.

Restoring is a real hydration, not a rewind: effects do not un‑run and requests do not un‑send. It puts the data back so you can re‑drive the UI from a state you have already seen.

Diffing two snapshots

Reading two state trees side by side and spotting the difference is a job for a computer. The State tab's Diff view takes any two of the captured commits and lists only what changed between them — added, removed, or changed, at the leaf, with both values — which is usually three lines instead of two hundred. Coming from a bug report ("it was fine, then I clicked twice"), this is the shortest path from "something changed" to "this changed".

It needs captureSnapshots on (it is, by default) because it reads the same per‑commit snapshots time travel uses.

Render profiler

Every commit is captured with its trigger, its wall‑clock duration, and one record per component instance. Open the Profiler tab, interact with the app, and read it top‑to‑bottom: summary, strip, insights, commit detail, reactivity, ranked components.

The commit strip

One bar per commit, oldest on the left. Bar height is that commit’s duration relative to the slowest one captured, so the strip is a shape, not an axis. Click a bar to pin it; the Commit detail section below follows your selection instead of the latest commit.

Green wins over amber, so the first captured commit reads green even though it is also a full render. Hover any bar for #7 · 3.10 ms · 4 rendered / 9 memoized, and look for runs of amber: repeated full renders are the single most common Aktion performance bug.

The flamegraph

Commit detail lists every instance in the selected commit, in render order, indented by tree depth. Bar width is that instance’s self time relative to the widest one in the same commit. Library components are prefixed with a small square; user components are not.

Hover a bar for the reason the phase was chosen. These strings come straight from the renderer, so they name the exact decision it made:

Performance summary and the components table

The stat grid at the top of the tab aggregates every captured commit. Several tiles change colour once they cross a fixed threshold, so you can read the grid without knowing what “good” looks like.

Below the flamegraph, Components — ranked by self time aggregates the same records by component name across every captured commit. Click any header to sort by it; clicking the active header flips the direction. It opens sorted by Total, descending.

A healthy row has Memo comfortably above Renders. A user component with a large Renders and Memo of zero reads a $state path that changes on nearly every commit.

Insights and the reactivity panel

Insights is a fixed set of heuristics over the captured commits, capped at six entries. Each one names the component and the number that triggered it, so you can verify the claim in the table below.

• A component averaging ≥ 8 ms per render — split it, or move the work into a $memo.
• A user component that rendered ≥ 12 times, was never memoized, across at least four commits — check what $state its body reads.
• Three or more non‑initial commits that forced a full re‑render — usually an async resolution, a timer, or an effect calling notify.
• Nothing found, with at least one commit — a single green “no render hot‑spots detected”.

Reactivity — state paths that triggered commits ranks the top eight $state paths by how many commits they caused. It answers a different question from the heat badges on the State tab: heat counts every write, this panel counts only the writes that actually cost you a render.

Flash on commit outlines the inspected element for 140 ms on every commit — the quickest way to tell which of several apps on a page is the one re‑rendering. Clear empties the strip without stopping recording.

Effect timeline

Every transition of every effect, attributed to the trigger that caused it. This is where you take an effect that “runs too often” and find out what is firing it.

Phases and triggers

Five phases, each with its own colour and its own extra payload. They arrive in lifecycle order, and a re‑run emits cleanup before its run whenever the previous run registered any cleanup handlers.

The reason column is the attribution — the answer to “what fired this?”

Alongside the reason, each effect shows its declared trigger list exactly as you wrote it — [$count, "mount"], [every(1000)], [debounce(250), $query]. An effect that declares no triggers at all reads [mount], which is the rule the runtime applies to it.

Timeline versus Log

The Timeline view (the default) gives each effect a lane and places one dot per event on a shared time axis measured from the first event this app emitted. Bursts, overlapping runs, and cleanup→run pairing are obvious at a glance; exact ordering within a burst is not.

Press the toggle for the Log view: a flat, newest‑first list of the last 250 matching events with a relative timestamp, the phase chip, the effect label, and the reason. Use Timeline to find the effect, Log to read the sequence.

The five phase chips in the toolbar filter both views — all on by default. Turn off run and mount and a noisy timeline collapses to just the cleanups and errors you care about.

Lanes, summary, and insights

Between the insights and the visualisation, one lane per effect lists its label, its declared triggers, its run count, and its total run time, sorted by run count. Effects declared inside a function body carry an instance tag, and report their unmount when that component leaves the tree.

Effect labels are always derived from source position — effect @ L3:C1 is the effect declared at line 3, column 1. There is no way to name an effect, so the position is the identity: move the declaration and its lane is a new lane.

The Insights list applies three rules per effect, capped at six entries: any error at all is flagged red; ≥ 20 runs is flagged as a hot trigger worth re‑checking the dependency list for; otherwise an average of ≥ 6 ms per run is flagged as heavy work in an effect body.

Network, and request rules

Every request the Aktion HTTP layer issues — $query, $mutation, Http({...}), and $http — is listed with its status, method, path, size, duration, and a waterfall bar. The detail pane has the response body, the request body, both header sets, and a timing breakdown, plus Copy as curl for reproducing it outside the app.

Rules is the half that makes this a testing tool. A rule matches by URL (substring, or a glob with *) and optionally by method, and then does one of four things:

Rules are evaluated in order and the first enabled match wins; each rule shows how many recorded requests it would have claimed, so a rule that matches nothing is visibly different from a rule that is not working. A mocked or blocked row is labelled with the rule that produced it, so a mocked 500 never reads as a real one. Mock this on any recorded request seeds a rule that replays its response.

The program sees exactly what it would see from the network: a mocked response arrives through the same code path as a real one, and a failure surfaces as a transport error. Rules live on the inspected element and are dropped when it unmounts.

Console and the expression REPL

The panel mirrors the page console, which matters more than it sounds: the runtime's own diagnostics land there — “a reactive $state write happened during render…”, “failed to render Button”, “handler rejected” — and they are usually the most direct explanation of a reactivity bug. Runtime lines carry a runtime chip, consecutive duplicates collapse into a count, and uncaught errors and unhandled promise rejections are captured too.

Below it, a REPL that evaluates Aktion expressions — not JavaScript — against the live program scope:

› $user.name
‹ "Ada"

› $todos.filter(t => !t.done).length
‹ 3

› $count = 5          // writes through the real reactive pipeline
‹ 5

The same bindings, the same atoms, the same helpers the program sees. An assignment to a $ atom is indistinguishable from one a button made. Reads are deliberately not tracked as render dependencies, so poking at state from the console cannot change what the app re‑renders on. ↑ / ↓ walk the history.

Routes and data

Routes lists the patterns the program declares, read statically from its $router({ … }) arms rather than from observation — a router only discovers a pattern when it matches, so a history‑based view could only ever show you where you have already been. Every concrete route is clickable, and the navigation history records each change with the arm that claimed it. A navigation that matched nothing is called out: without a default: arm the router renders nothing at all for that path.

Data covers the three places state hides from the State tab:

• Queries — the shared $query / Http({...}) cache, keyed by request rather than by atom, with each resource's state, status, data, and age. Refetch or cancel one, or invalidate by key substring the way invalidates: does.
• Stores & forms — a $store keeps everything in one machine‑named atom (__store_3_10), which is why the State tab shows a name nobody wrote. Here it is named by its declaration site, with its methods listed and callable.
• Storage — localStorage, sessionStorage, and cookies, read straight from the page so the view is correct even for keys the program has never touched. That is where stale‑value bugs live — and you can write there too: add a key, edit a value in place, or delete one, which is how you reproduce "works for me, broken for the user who has been here before" without hand‑editing storage in another devtools panel.

Theme tokens

Aktion's components take almost no styling props: they read --rui-* custom properties, and a theme is a map of those. That makes the token editor the highest leverage surface in the panel — one edit restyles every Button, Card, and Table at once.

Tokens are grouped the way a designer thinks about them (surfaces, text, brand, status, typography, spacing, elevation), colour‑valued ones get a picker, and edits are applied as inline custom properties exactly the way an in‑script $theme({...}) block applies them. Copy as $theme hands you the block that reproduces what you just did. A token the program's own $theme({...}) sets is marked, because that block is re‑applied every render and wins.

Below the tokens, contrast checks for the pairs the stylesheet actually paints — body text, muted text, text on a surface, primary buttons, accent fills, links, control borders — each with its measured ratio against the WCAG minimum. “Check your contrast” is useless without knowing which pairs matter.

Source

Aktion programs are usually generated, which changes what a source view is for: you are rarely reading code you wrote, you are checking what the model emitted and where the validator disagreed. So this tab leads with diagnostics placed on their lines and an outline of every declaration — components, effects, actions, hooks, atoms, imports — that you can jump through.

Edit turns it into an editor. The draft is parsed and schema‑checked as you type, so Apply is never a surprise, and mounting goes through the same path a streamed update takes: $state is preserved across the diff. The analysis runs the runtime's own parser and validator — the panel deliberately does not carry a second one, because an inspector that disagreed with the runtime about whether a program is valid would be worse than no inspector.

Because an edit can break the program badly enough that there is nothing left to edit, the tab keeps a history: every version that has been mounted this session, with the diagnostics it produced and a one‑click Revert. A bad apply is a two‑second undo rather than a reload that loses your $state.

Ctrl + F searches the program and marks every hit; Ctrl + Enter applies a draft. Large programs stay cheap: the view renders a window of lines around what you are looking at rather than rebuilding every line on every runtime event.

Test toolkit

Five tools that turn “it broke” into something you can commit.

Timeline

Every commit, effect event, request, navigation, emitted event, log line, and error in one ordered stream, with idle gaps marked. The per‑subsystem tabs each answer their own question well and none of them answers the most common one: what happened when I clicked that? A real interaction is a commit, two effect runs, a request, and a route change inside forty milliseconds, spread across four tabs.

Rows are clickable — a commit opens in the Profiler, an effect in Effects, a request in Network. Export session writes the whole capture (events, state, program, totals) to a JSON file, which is what you attach to a bug report.

Settings, and what you are paying for

Instrumentation is not free, and a debugger that silently changes the timings it reports is a bad debugger. Five switches gate the work inside the runtime, so turning one off makes the app faster, not just the panel:

A second group, While you work, holds the continuous aids described under Watching an app while you use it — highlight re‑renders, flash on commit, browser performance marks, console capture. Those cost the panel, not the runtime, and are off by default.

The same tab holds the panel's own preferences — dock to any edge or float, a light theme for a light host page, compact rows for a narrow dock, console capture on or off — and they are remembered between sessions.

API reference

aktion-runtime/devtools is a self‑contained ES module. Importing it registers the <aktion-devtools> custom element as a side effect, so you can also drop the tag straight into your HTML instead of calling the mount function.

The event shapes themselves are exported as types — DevtoolsEvent, CommitRecord, ComponentRenderRecord, StateEvent, EffectEvent, RenderPhase, EffectPhase — so a custom frontend can be fully typed. See TypeScript.

mountDevtools(options?)

One call does three things: it installs the hook, registers and appends the panel element, and adopts every app on the page. It is idempotent at the hook level but not at the panel level — a second call mounts a second panel.

const devtools = mountDevtools({
  container: document.querySelector("#debug-dock"),  // default: document.body
  appId: "aktion-app-2",                             // default: the first app that registered
  tab: "inspect",                                    // default: last used, else "overview"
  dock: "bottom",                                    // "float" | "right" | "bottom" | "left"
  open: false                                        // default: true — mounts already open
});

Nothing here is required. mountDevtools() with no arguments is the call you want almost always — reach for the options only when the panel has to live somewhere other than document.body, open on a particular tab, or start hidden.

Floating, the panel is position: fixed at a very high z‑index, sized 560×620 and placed 16 px from the bottom‑right corner. Drag the header to move it, use the corner grip to resize down to 360×260, and the header buttons to switch dock, pause recording, collapse, or close. Docked, it spans an edge and the drag/resize handles retire. Position, size, dock, theme, density, and the last tab are remembered in localStorage.

The controller

mountDevtools() returns a plain object. Keep it: it is the only handle on that panel.

close() and destroy() are not interchangeable. close() is a UI state; destroy() is the one that turns the instrumentation back off.

The hook and the app record

The hook is the wire between the runtime and any frontend. You rarely touch it directly, but reading it in the console is a fast way to confirm DevTools is wired up at all.

const hook = window.__AKTION_DEVTOOLS_HOOK__;

hook.aktion;            // true — the marker that says you found the real hub
hook.protocolVersion;   // 2
hook.apps.size;         // how many <aktion-app> elements registered
hook.active;            // true only while a frontend is subscribed
hook.buffer.length;     // recent events, capped at hook.bufferLimit (default 2000)
hook.options;           // the instrumentation switches the runtime reads

hook.setOptions({ captureProps: false });   // stop serialising per-instance props
hook.clearBuffer();                         // drop the backfill buffer

const stop = hook.subscribe((event) => console.log(event.kind, event));
// ... later
stop();

subscribe(fn) and subscribeApps(fn) both return an unsubscribe function. A listener that throws is caught and logged, so a broken frontend can never break the app it inspects.

Events come in eight kinds. commit, state, and effect are the original three; protocol 2 adds network (one start plus one terminal event per request), route (emitted after the render that resolves which arm matched, so it can report the pattern), emit (every $emit(…), mirrored before dispatch so a host that stops propagation cannot hide it), log, and error (a failure the app survived — a plan error, a render throw, a budget abort).

Each entry in hook.apps is a deliberately narrow handle. It exposes what a debugger legitimately needs and nothing else — there is no path from it to the raw runtime internals, values are serialised before they cross, and every write goes through the same reactive pipeline an event handler uses. The first seven members are the version‑1 contract and are always present; everything after them is optional, so a frontend feature‑detects and degrades instead of throwing.

So data-devtools-label is the one authoring hook on the app side. With several apps on a page, name them — otherwise the picker reads aktion-app-1, aktion-app-2, and you will pick the wrong one.

<aktion-app data-devtools-label="Checkout form"></aktion-app>
<aktion-app data-devtools-label="Live order feed"></aktion-app>

There is also el.connectDevtools() on the element itself. The panel calls it on every aktion-app it finds when it opens, which is what makes late‑attach work; call it yourself for an app the panel cannot reach with a document query.

How it works

The architecture is the browser‑DevTools split: a backend (the runtime) and a frontend (the panel) that only ever talk through structured, JSON‑serialisable events.

• The runtime emits to a global hook at window.__AKTION_DEVTOOLS_HOOK__, exactly like React’s __REACT_DEVTOOLS_GLOBAL_HOOK__. Nothing installs that hook until a frontend does.
• The hook buffers. Recent events are kept in a ring buffer, so a panel that opens after an app has already rendered can backfill its timeline instead of starting blank.
• Panels share one hub. installDevtoolsHook() is idempotent, so a second mountDevtools() attaches to the same registry and the same event stream.
• The protocol is transport‑agnostic. No payload contains a DOM node, a class instance, or a function, so the same events could cross a postMessage boundary into a browser‑extension panel.

Everything is bounded, so a session can run for hours without the panel’s model growing without limit. When a cap is hit the oldest entries are dropped.

What it costs when it is not open

The runtime always attempts to talk to the hook, so the cost question is really about which of three states you are in. Only the third one is not free.

The gate is decided once per commit, so the profiler flag stays consistent across a whole render pass. A hidden panel skips its own rendering, but it is still subscribed — which is why destroy(), not close(), is what you call before measuring real performance numbers.

Within the third state, the Settings tab decides how much you pay: prop capture serialises every instance's arguments per commit, DOM tagging writes an attribute per rendered element, and snapshots clone the store per commit. Turning one off makes the app faster, not just the panel — which is what you want when the thing you are measuring is render time itself.

Troubleshooting

A handful of failures account for almost every “DevTools isn’t working” report. Work down the list in order — each one rules out the ones below it.

No panel appears

• The import alone does nothing. You have to call mountDevtools(), or place an <aktion-devtools> element in the document. A bundler may also have tree‑shaken an import whose result you never used.
• You passed open: false. The panel is mounted and recording, just hidden. Call controller.open().
• It is off‑screen. The corner position is computed once, at mount, from the viewport size. Shrink the window afterwards and the panel can sit outside it. Drag the header back, or destroy() and mount again.
• A container ancestor traps it. A transform, filter, backdrop-filter, or contain on an ancestor establishes a containing block for position: fixed, which clips or mispositions the panel. Mount into document.body, which is the default.

The hook is not installed

Type window.__AKTION_DEVTOOLS_HOOK__ in the console. If it is undefined, no frontend has run — the runtime never installs the hook by itself.

• Confirm from code with isDevtoolsInstalled(), and check whether anything is actually listening with isDevtoolsActive().
• Two realms will not see each other. A panel mounted inside an iframe installs the hook on that iframe’s globalThis; an app in the parent document emits to the parent’s. Mount the panel in the same document as the app.
• Check the load order of the bundles only if the app itself is broken: the hook does not depend on the runtime, and either import may come first.

“No Aktion app detected”

The panel adopts apps two ways: they register themselves when they render, and on open the panel calls connectDevtools() on every aktion-app it can find with a document query. If the picker is still empty:

• The element never upgraded. import "aktion-runtime" has to run for <aktion-app> to become a custom element. An un‑upgraded tag has no connectDevtools and is skipped silently.
• The app is inside a shadow root or an iframe. document.querySelectorAll pierces neither. Reach the element yourself and call el.connectDevtools().
• The tag is created later. An app added to the DOM after the panel opened registers on its first render, so give it one interaction — or call connectDevtools() right after you insert it.

The Profiler tab is empty

• Commits are only recorded while a frontend is subscribed. Renders that happened before you opened the panel were never instrumented. Attaching forces one full render per app, so you should see at least one commit immediately — if you see exactly one, that is it.
• Recording is paused. The header button flips to Paused and the dot goes grey. Paused events are dropped by the panel, not queued, so they do not appear when you resume.
• You pressed Clear, which empties the strip and un‑pins the selected commit.
• The app is idle. Nothing has changed, so nothing has committed. Interact with it, or give it an every(N) effect.

The State tab is empty, or an edit does nothing

• Only $‑prefixed atoms are state. Plain let / const bindings are re‑seeded each render and never appear in the tree.
• You clicked a container. Only leaf values are editable. Expand the object and edit the value inside.
• The row is tagged reserved. route is runtime‑owned; change the URL through the router instead. See Routing.
• Your input parsed as a string. JSON.parse runs first, so true writes a boolean but yes writes the text "yes". Quote it — "true" — when you really want the string.
• The value snaps back. Something re‑derives it: an effect, an $http resolution, or a $memo. Watch the Effects tab immediately after the edit to see which.

The Inspect tab is empty, or the picker selects nothing

• The tree comes from the last commit. An app that has not rendered since the panel opened has no tree. Attaching forces one render, so this is normally only a problem right after hook.clearBuffer().
• tagDom is off. Without it there is no data-aktion-instance attribute to resolve, so the picker cannot map a click to a component and highlighting does nothing. Turn it back on in Settings.
• The row says no dom. That instance rendered a fragment with no host element — a Show / Async / Lazy branch. Its props and state are still inspectable; there is just nothing to outline.
• You picked something the panel is covering. The hit test is positional, so a floating panel over the element wins. Dock the panel to an edge, or scroll the element clear of it.
• The node belongs to no component. A preserved third‑party widget's internals, or part of the host page. The panel says so and still shows the DOM, attributes, and styles.

A prop edit does not stick

• The prop is $‑bound. Then the atom is the source of truth and the edit writes it — look for the change in the State tab, and expect other readers of that atom to move too.
• The value is not serialisable. A callback, a live resource, or a DOM node is shown read‑only, because an inspector that offered an edit it cannot apply is worse than one that does not offer it.
• The program was re‑planned. Overrides are keyed by instance and are dropped on setResponse, appendChunk, or reload().
• The instance remounted under a new key. A changed key:, or a conditional branch flipping, produces a different instance — and the override belonged to the old one.

The Network tab shows nothing

• Only the Aktion HTTP layer is tapped. $query, $mutation, Http({...}), and $http appear here; a bare fetch() from a host page does not. Use the browser's own network panel for that.
• captureNetwork is off in Settings — which also disables request rules.
• A rule is answering everything. A mocked or blocked row is labelled with the rule that produced it, and each rule shows its match count. An offline rule with an empty pattern matches every request.

Next