Devtools and Inspection

Devtools and Inspection

gUI ships with a dedicated devtools entrypoint and raw DOM update hooks.

Install and import

import { createInspector } from "@bragamateus/gui/devtools";

The inspector is opt-in. Importing the root runtime does not mount visual tooling automatically.

Basic usage

createInspector({
  target: "#app",
  title: "Live DOM Lens",
});

What the inspector shows today

• exact text updates
• exact attribute updates
• structural inserts
• keyed moves
• removals
• runtime flushes
• cleanup cycles
• computed refreshes
• owner disposal

It is the fastest way to confirm that gUI is updating bindings instead of rerendering component trees.

Inspector options

Useful options include:

• title
• subtitle
• maxEntries
• overlayDuration
• position
• target
• container
• paused
• collapsed
• expanded
• overlay
• runtime
• domEventFilter
• runtimeEventFilter
• onDestroy

Example:

const inspector = createInspector({
  target: "#playground",
  title: "Playground Runtime",
  position: "bottom-left",
  maxEntries: 30,
  overlayDuration: 900,
});

Controller methods:

• clear()
• destroy()
• pause()
• resume()
• setExpanded(boolean)
• setTarget(target)
• toggleExpanded()
• entries()
• isExpanded()
• isPaused()

Raw DOM update hooks

From the root package:

import { setDomUpdateHook, subscribeDomUpdates } from "@bragamateus/gui";

setDomUpdateHook(fn)

Use this when you want a single global listener:

setDomUpdateHook((event) => {
  console.log(event.type, event);
});

subscribeDomUpdates(fn)

Use this when multiple tools need the same stream:

const unsubscribe = subscribeDomUpdates((event) => {
  console.log(event);
});

unsubscribe();

DOM event payload shape

DOM update events currently include:

• type: "text" | "attribute" | "structure"
• timestamp
• origin
• node
• element
• name
• value
• action
• anchor
• rect

This is enough to build overlays, logs, custom timelines, and test assertions.

Practical debugging patterns

Prove exact updates

Subscribe to DOM updates and log only events for one container.

Prove keyed movement

Reverse a list built with list() and observe structure events with action: "move".

Prove cleanup

Build a dynamic branch with Show() or a getter and watch the inspector timeline when the branch leaves the DOM.

Keep tooling local

Mount the inspector against one target region so documentation pages, playgrounds, or embedded widgets can be debugged independently.