@gjsify/devtools 0.8.0 → 0.12.0

package/README.md

@@ -0,0 +1,85 @@
+# @gjsify/devtools
+
+The in-app **DBus devtools control plane** for GTK/GJS apps. Opt in with one call and your running app exposes `org.gjsify.Devtools` — a control plane you can drive from `gdbus`, d-feet, GNOME Builder, headless CI, or (via [`@gjsify/devtools-mcp`](../devtools-mcp)) an AI agent.
+
+It implements the toolkit-neutral [`@gjsify/devtools-protocol`](../devtools-protocol) contract over DBus and re-exports it, so a consumer needs one import.
+
+## Install it in your app
+
+`installDevtools` is a no-op unless `GJSIFY_DEVTOOLS=1` (or `enabled: true`). Call it from `onStartup`/`vfunc_startup`, after the actions and the active window exist.
+
+```ts
+import Adw from '@girs/adw-1';
+import GObject from '@girs/gobject-2.0';
+import { installDevtools } from '@gjsify/devtools';
+
+export class MyApplication extends Adw.Application {
+    static { GObject.registerClass(MyApplication); }
+
+    vfunc_startup(): void {
+        super.vfunc_startup();
+        // … create actions + the main window …
+
+        installDevtools(this, {
+            // Adw.ApplicationWindow does NOT expose its win.* actions as a group —
+            // pass one explicitly so win.* commands are bridged.
+            winActionGroup: this._window,
+            // Optional: contribute app-specific methods (see below).
+            extend: [],
+            // Optional: gate mutating methods behind your own pause state.
+            paused: () => this._externalControlPaused,
+        });
+    }
+}
+```
+
+Then drive it without any AI:
+
+```bash
+GJSIFY_DEVTOOLS=1 gjsify run dist/index.js &
+gdbus call --session -d org.example.App -o /org/example/App/devtools \
+  -m org.gjsify.Devtools.GetStatus
+gdbus call --session -d org.example.App -o /org/example/App/devtools \
+  -m org.gjsify.Devtools.Screenshot 'window'   # PNG bytes as a GVariant `ay`
+```
+
+## Generic methods (out of the box)
+
+`GetStatus`, `Screenshot` (GSK widget snapshot PNG), `ListActions` / `ActivateAction` / `ChangeActionState` (GAction bridge), `PresentWindow`, `ResizeWindow`, plus full introspection: `ListToplevels`, `DumpTree`, `GetProperty` (by index path), `GetFocused`, `DumpGSettings`, `DumpCss` / `SwapCss` (live CSS hot-swap).
+
+GActions are auto-bridged into the command registry (handling the `Adw.ApplicationWindow` non-export gotcha via `winActionGroup`).
+
+## App-specific methods — a `DevtoolsExtension`
+
+Add your own methods without forking the core. The `<method>` XML is merged into the interface, handlers attach as DBus methods, and each method declares a kind the pause guard enforces.
+
+```ts
+import type { DevtoolsExtension } from '@gjsify/devtools';
+
+const myExtension: DevtoolsExtension = {
+    methodsXml: ['<method name="DoThing"><arg type="s" direction="in" name="what"/></method>'],
+    handlers: { DoThing: (what: string) => { /* … */ } },
+    methodKinds: { DoThing: 'mutating' },
+    contributeStatus: () => ({ thing: currentThing }),
+};
+
+installDevtools(this, { extend: [myExtension] });
+```
+
+## Exports
+
+- `installDevtools(app, options)` → returns a `DevtoolsService` (or `null` when the env gate is off); `uninstallDevtools(service)` — opt-in lifecycle.
+- `DevtoolsService` — the exported service object `installDevtools` returns and `uninstallDevtools` accepts.
+- `DevtoolsExtension`, `InstallDevtoolsOptions` — the extension + options types.
+- `captureWidgetPng` (GSK screenshot), `buildVariant` / `variantKindFor` / `VariantKind` (GVariant), `activateAction` / `changeActionState` / `describeActions` (GAction bridge).
+- widget-tree helpers (`dumpTree`, `getWidgetProperty`, `listToplevels`, `resolveWidgetPath`, …), `dumpCss` / `swapCss` / `removeCss`, `dumpGSettings`, `buildDevtoolsIfaceXml`.
+- the re-exported `@gjsify/devtools-protocol` contract.
+
+> **GJS gotcha:** the long-lived `Gio.DBusExportedObject` is reachable only through a self-cycle, which SpiderMonkey's GC can collect mid-run. `installDevtools` roots the service in a module-level set to defeat this — keep that rooting if you wire the service by hand.
+
+## Build / test
+
+```bash
+gjsify workspace @gjsify/devtools build
+gjsify workspace @gjsify/devtools test
+```

package/lib/esm/css.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import e from"@girs/gtk-4.0";import t from"@girs/gdk-4.0";const n=new Map;function swapCss(r,i){let a=t.Display.get_default();if(!a)return!1;let o=n.get(r);return o||(o=new e.CssProvider,e.StyleContext.add_provider_for_display(a,o,e.STYLE_PROVIDER_PRIORITY_USER+1),n.set(r,o)),o.load_from_string(i),!0}function removeCss(r){let i=n.get(r);if(!i)return!1;let a=t.Display.get_default();return a&&e.StyleContext.remove_provider_for_display(a,i),n.delete(r),!0}function dumpCss(){return{providers:[...n.keys()]}}export{dumpCss,removeCss,swapCss};
+import"./_virtual/_rolldown/runtime.js";import e from"@girs/gdk-4.0";import t from"@girs/gtk-4.0";const n=new Map;function swapCss(r,i){let a=e.Display.get_default();if(!a)return!1;let o=n.get(r);return o||(o=new t.CssProvider,t.StyleContext.add_provider_for_display(a,o,t.STYLE_PROVIDER_PRIORITY_USER+1),n.set(r,o)),o.load_from_string(i),!0}function removeCss(r){let i=n.get(r);if(!i)return!1;let a=e.Display.get_default();return a&&t.StyleContext.remove_provider_for_display(a,i),n.delete(r),!0}function dumpCss(){return{providers:[...n.keys()]}}export{dumpCss,removeCss,swapCss};

package/lib/esm/devtools-service.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import{captureWidgetPng as e}from"./screenshot.js";import{buildDevtoolsIfaceXml as t}from"./devtools-iface.js";import{dumpCss as n,swapCss as r}from"./css.js";import{activateAction as i,changeActionState as a,describeActions as o}from"./actions.js";import{dumpGSettings as s}from"./gsettings.js";import{dumpTree as c,getWidgetProperty as l,listToplevels as u,pathOfWidget as d,resolveWidgetPath as f,widgetType as p}from"./widget-tree.js";import m from"@girs/gtk-4.0";import{GENERIC_METHODS as h,formatDbusErrorMessage as g}from"@gjsify/devtools-protocol";import _ from"@girs/gio-2.0";var DevtoolsService=class{constructor(e,t){this._app=e,this._options=t,this._exported=null,this._kinds=new Map,this._extensions=t.extend??[];for(let[e,t]of Object.entries(h))this._kinds.set(e,t);for(let e of this._extensions){for(let[t,n]of Object.entries(e.methodKinds))this._kinds.set(t,n);for(let[t,n]of Object.entries(e.handlers)){let e=n;this[t]=(...n)=>(this._guard(t),e(...n))}}}export(e,n){if(this._exported)return;let r=t(this._extensions.flatMap(e=>e.methodsXml??[])),i=_.DBusExportedObject.wrapJSObject(r,this);i.export(e,n),this._exported=i}unexport(){this._exported?.unexport(),this._exported=null}GetStatus(){let e=this._app.get_active_window(),t={appId:this._app.get_application_id()??`unknown`,instance:this._options.instance??`default`,activeWindow:e?{id:e.get_name()||`window`,title:e.get_title()??``,mapped:e.get_mapped()}:null,toplevelCount:m.Window.get_toplevels().get_n_items(),focusedWidget:null,paused:this._isPaused()};for(let e of this._extensions){let n=e.contributeStatus?.();n&&Object.assign(t,n)}return JSON.stringify(t)}async Screenshot(t){let n=this._app.get_active_window();return n?e(n)??new Uint8Array:new Uint8Array}ListActions(){let e={app:o(this._actionGroup(`app`)),win:o(this._actionGroup(`win`))};return JSON.stringify(e)}ActivateAction(e,t,n){this._guard(`ActivateAction`);let r=this._scope(e);i(this._requireGroup(r,t),t,this._parseValue(n))}ChangeActionState(e,t,n){this._guard(`ChangeActionState`);let r=this._scope(e);a(this._requireGroup(r,t),t,this._parseValue(n))}PresentWindow(){this._app.get_active_window()?.present()}ResizeWindow(e,t){this._guard(`ResizeWindow`);let n=this._app.get_active_window();if(!n)throw Error(g(`unavailable`,`no active window to resize`));let r=Math.max(1,Math.round(e)),i=Math.max(1,Math.round(t));return n.is_maximized()&&n.unmaximize(),n.is_fullscreen()&&n.unfullscreen(),n.set_default_size(r,i),[r,i]}ListToplevels(){return JSON.stringify(u())}DumpTree(e,t){let n=this._resolveRootWidget(e);if(!n)throw Error(g(`not-found`,`no widget at '${e||`active window`}'`));return JSON.stringify(c(n.widget,t>0?t:8,n.path))}GetProperty(e,t){let n=this._resolveRootWidget(e);if(!n)throw Error(g(`not-found`,`no widget at '${e}'`));let r=l(n.widget,t);if(r===void 0)throw Error(g(`not-found`,`widget has no property '${t}'`));return JSON.stringify(r)}GetFocused(){let e=this._app.get_active_window(),t=e?e.get_focus():null;return JSON.stringify(t?{path:d(t),name:t.get_name()||null,type:p(t)}:null)}DumpGSettings(e){return JSON.stringify(s(e))}DumpCss(){return JSON.stringify(n())}SwapCss(e,t){return this._guard(`SwapCss`),r(e,t)}_resolveRootWidget(e){if(!e||e===`window`||e===`active`){let e=this._app.get_active_window();return e?{widget:e,path:d(e)??`toplevel:0`}:null}let t=f(e);return t?{widget:t,path:e}:null}_isPaused(){return this._options.paused?.()??!1}_guard(e){let t=this._kinds.get(e);if(!t)throw Error(g(`internal`,`unclassified devtools method '${e}'`));if(t===`mutating`&&this._isPaused())throw Error(g(`paused`,`${e} rejected — external control is paused. Read-only methods keep working.`))}_scope(e){return e===`app`?`app`:`win`}_actionGroup(e){if(e===`app`)return this._app;if(this._options.winActionGroup)return this._options.winActionGroup;let t=this._app.get_active_window();return t instanceof m.ApplicationWindow?t:null}_requireGroup(e,t){let n=this._actionGroup(e);if(!n)throw Error(g(`unavailable`,`no '${e}' action group`));if(!n.has_action(t))throw Error(g(`not-found`,`unknown action ${e}.${t}`));return n}_parseValue(e){if(!e||e===`null`)return null;try{return JSON.parse(e)}catch{throw Error(g(`invalid-params`,`value_json is not valid JSON: ${e}`))}}};export{DevtoolsService};
+import"./_virtual/_rolldown/runtime.js";import{activateAction as e,changeActionState as t,describeActions as n}from"./actions.js";import{dumpCss as r,swapCss as i}from"./css.js";import{buildDevtoolsIfaceXml as a}from"./devtools-iface.js";import{captureWidgetPng as o}from"./screenshot.js";import{dumpGSettings as s}from"./gsettings.js";import{dumpTree as c,getWidgetProperty as l,listToplevels as u,pathOfWidget as d,resolveWidgetPath as f,widgetType as p}from"./widget-tree.js";import m from"@girs/glib-2.0";import h from"@girs/gtk-4.0";import{GENERIC_METHODS as g,formatDbusErrorMessage as _}from"@gjsify/devtools-protocol";import v from"@girs/gio-2.0";function frameDelay(e){return new Promise(t=>{m.timeout_add(m.PRIORITY_DEFAULT,e,()=>(t(),m.SOURCE_REMOVE))})}async function captureWidgetWhenRenderable(e,t=12,n=50){for(let r=0;r<t;r++){let t=o(e);if(t)return t;await frameDelay(n)}return o(e)}var DevtoolsService=class{constructor(e,t){this._app=e,this._options=t,this._exported=null,this._kinds=new Map,this._extensions=t.extend??[];for(let[e,t]of Object.entries(g))this._kinds.set(e,t);for(let e of this._extensions){for(let[t,n]of Object.entries(e.methodKinds))this._kinds.set(t,n);for(let[t,n]of Object.entries(e.handlers)){let e=n;this[t]=(...n)=>(this._guard(t),e(...n))}}}export(e,t){if(this._exported)return;let n=a(this._extensions.flatMap(e=>e.methodsXml??[])),r=v.DBusExportedObject.wrapJSObject(n,this);r.export(e,t),this._exported=r}unexport(){this._exported?.unexport(),this._exported=null}GetStatus(){let e=this._app.get_active_window(),t={appId:this._app.get_application_id()??`unknown`,instance:this._options.instance??`default`,activeWindow:e?{id:e.get_name()||`window`,title:e.get_title()??``,mapped:e.get_mapped()}:null,toplevelCount:h.Window.get_toplevels().get_n_items(),focusedWidget:null,paused:this._isPaused()};for(let e of this._extensions){let n=e.contributeStatus?.();n&&Object.assign(t,n)}return JSON.stringify(t)}async Screenshot(e){let t=this._app.get_active_window();if(!t)return new Uint8Array;let n=o(t);return n||=(t.present(),await captureWidgetWhenRenderable(t)),n??new Uint8Array}ListActions(){let e={app:n(this._actionGroup(`app`)),win:n(this._actionGroup(`win`))};return JSON.stringify(e)}ActivateAction(t,n,r){this._guard(`ActivateAction`);let i=this._scope(t);e(this._requireGroup(i,n),n,this._parseValue(r))}ChangeActionState(e,n,r){this._guard(`ChangeActionState`);let i=this._scope(e);t(this._requireGroup(i,n),n,this._parseValue(r))}PresentWindow(){this._app.get_active_window()?.present()}ResizeWindow(e,t){this._guard(`ResizeWindow`);let n=this._app.get_active_window();if(!n)throw Error(_(`unavailable`,`no active window to resize`));let r=Math.max(1,Math.round(e)),i=Math.max(1,Math.round(t));return n.is_maximized()&&n.unmaximize(),n.is_fullscreen()&&n.unfullscreen(),n.set_default_size(r,i),[r,i]}ListToplevels(){return JSON.stringify(u())}DumpTree(e,t){let n=this._resolveRootWidget(e);if(!n)throw Error(_(`not-found`,`no widget at '${e||`active window`}'`));return JSON.stringify(c(n.widget,t>0?t:8,n.path))}GetProperty(e,t){let n=this._resolveRootWidget(e);if(!n)throw Error(_(`not-found`,`no widget at '${e}'`));let r=l(n.widget,t);if(r===void 0)throw Error(_(`not-found`,`widget has no property '${t}'`));return JSON.stringify(r)}GetFocused(){let e=this._app.get_active_window(),t=e?e.get_focus():null;return JSON.stringify(t?{path:d(t),name:t.get_name()||null,type:p(t)}:null)}DumpGSettings(e){return JSON.stringify(s(e))}DumpCss(){return JSON.stringify(r())}SwapCss(e,t){return this._guard(`SwapCss`),i(e,t)}_resolveRootWidget(e){if(!e||e===`window`||e===`active`){let e=this._app.get_active_window();return e?{widget:e,path:d(e)??`toplevel:0`}:null}let t=f(e);return t?{widget:t,path:e}:null}_isPaused(){return this._options.paused?.()??!1}_guard(e){let t=this._kinds.get(e);if(!t)throw Error(_(`internal`,`unclassified devtools method '${e}'`));if(t===`mutating`&&this._isPaused())throw Error(_(`paused`,`${e} rejected — external control is paused. Read-only methods keep working.`))}_scope(e){return e===`app`?`app`:`win`}_actionGroup(e){if(e===`app`)return this._app;if(this._options.winActionGroup)return this._options.winActionGroup;let t=this._app.get_active_window();return t instanceof h.ApplicationWindow?t:null}_requireGroup(e,t){let n=this._actionGroup(e);if(!n)throw Error(_(`unavailable`,`no '${e}' action group`));if(!n.has_action(t))throw Error(_(`not-found`,`unknown action ${e}.${t}`));return n}_parseValue(e){if(!e||e===`null`)return null;try{return JSON.parse(e)}catch{throw Error(_(`invalid-params`,`value_json is not valid JSON: ${e}`))}}};export{DevtoolsService};

package/lib/esm/index.js

@@ -1 +1 @@
-import{captureWidgetPng as e}from"./screenshot.js";import{buildDevtoolsIfaceXml as t}from"./devtools-iface.js";import{buildVariant as n,variantKindFor as r}from"./gvariant.js";import{dumpCss as i,removeCss as a,swapCss as o}from"./css.js";import{activateAction as s,changeActionState as c,describeActions as l}from"./actions.js";import{dumpGSettings as u}from"./gsettings.js";import{buildWidgetPath as d,dumpTree as f,getWidgetProperty as p,listToplevels as m,parseWidgetPath as h,pathOfWidget as g,resolveWidgetPath as _,widgetType as v}from"./widget-tree.js";import{DevtoolsService as y}from"./devtools-service.js";import{installDevtools as b,uninstallDevtools as x}from"./install.js";export*from"@gjsify/devtools-protocol";export{y as DevtoolsService,s as activateAction,t as buildDevtoolsIfaceXml,n as buildVariant,d as buildWidgetPath,e as captureWidgetPng,c as changeActionState,l as describeActions,i as dumpCss,u as dumpGSettings,f as dumpTree,p as getWidgetProperty,b as installDevtools,m as listToplevels,h as parseWidgetPath,g as pathOfWidget,a as removeCss,_ as resolveWidgetPath,o as swapCss,x as uninstallDevtools,r as variantKindFor,v as widgetType};
+import{buildVariant as e,variantKindFor as t}from"./gvariant.js";import{activateAction as n,changeActionState as r,describeActions as i}from"./actions.js";import{dumpCss as a,removeCss as o,swapCss as s}from"./css.js";import{buildDevtoolsIfaceXml as c}from"./devtools-iface.js";import{captureWidgetPng as l}from"./screenshot.js";import{dumpGSettings as u}from"./gsettings.js";import{buildWidgetPath as d,dumpTree as f,getWidgetProperty as p,listToplevels as m,parseWidgetPath as h,pathOfWidget as g,resolveWidgetPath as _,widgetType as v}from"./widget-tree.js";import{DevtoolsService as y}from"./devtools-service.js";import{installDevtools as b,uninstallDevtools as x}from"./install.js";export*from"@gjsify/devtools-protocol";export{y as DevtoolsService,n as activateAction,c as buildDevtoolsIfaceXml,e as buildVariant,d as buildWidgetPath,l as captureWidgetPng,r as changeActionState,i as describeActions,a as dumpCss,u as dumpGSettings,f as dumpTree,p as getWidgetProperty,b as installDevtools,m as listToplevels,h as parseWidgetPath,g as pathOfWidget,o as removeCss,_ as resolveWidgetPath,s as swapCss,x as uninstallDevtools,t as variantKindFor,v as widgetType};

package/lib/esm/screenshot.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import e from"@girs/graphene-1.0";import t from"@girs/gtk-4.0";function captureWidgetPng(n){let r=n.get_native()?.get_renderer();if(!r)return null;let i=n.get_width(),a=n.get_height();if(i<=0||a<=0)return null;let o=t.WidgetPaintable.new(n),s=t.Snapshot.new();o.snapshot(s,i,a);let c=s.to_node();if(!c)return null;let l=new e.Rect;l.init(0,0,i,a);let u=r.render_texture(c,l).save_to_png_bytes().get_data();return u?new Uint8Array(u):null}export{captureWidgetPng};
+import"./_virtual/_rolldown/runtime.js";import e from"@girs/gtk-4.0";import t from"@girs/graphene-1.0";function captureWidgetPng(n){let r=n.get_native()?.get_renderer();if(!r)return null;let i=n.get_width(),a=n.get_height();if(i<=0||a<=0)return null;let o=e.WidgetPaintable.new(n),s=e.Snapshot.new();o.snapshot(s,i,a);let c=s.to_node();if(!c)return null;let l=new t.Rect;l.init(0,0,i,a);let u=r.render_texture(c,l).save_to_png_bytes().get_data();return u?new Uint8Array(u):null}export{captureWidgetPng};

package/lib/types/css.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Install or replace a named `Gtk.CssProvider` on the default display at a
+ * priority just above USER, so it overrides the app's baked styles. Re-applying
+ * is free (no widget re-registration) — this is what makes live CSS iteration
+ * (`gjsify serve` Tier 3) work. Returns false when there is no display.
+ */
+export declare function swapCss(name: string, css: string): boolean;
+/** Remove a previously-installed named provider. Returns false if unknown. */
+export declare function removeCss(name: string): boolean;
+/** List the devtools-installed CSS provider names. */
+export declare function dumpCss(): {
+    providers: string[];
+};

package/lib/types/devtools-iface.d.ts

@@ -1,5 +1,3 @@
-/** Well-known interface name implemented on each app's own bus name + object path. */
-export declare const DEVTOOLS_INTERFACE = "org.gjsify.Devtools";
 /**
  * Assemble the full `org.gjsify.Devtools` introspection node XML, merging any
  * app-specific `<method>…</method>` fragments contributed by extensions into

package/lib/types/devtools-service.d.ts

@@ -34,6 +34,21 @@ export declare class DevtoolsService {
     PresentWindow(): void;
     /** `ResizeWindow(w, h) -> (w, h)` — resize the active window; returns the requested size. */
     ResizeWindow(width: number, height: number): [number, number];
+    /** `ListToplevels() -> s` — JSON of live toplevel windows. */
+    ListToplevels(): string;
+    /** `DumpTree(root, depth) -> s` — JSON widget tree from `root` ('' = active window). */
+    DumpTree(root: string, depth: number): string;
+    /** `GetProperty(path, prop) -> s` — JSON value of a widget's GObject property. */
+    GetProperty(path: string, prop: string): string;
+    /** `GetFocused() -> s` — JSON {path,name,type} of the focused widget, or null. */
+    GetFocused(): string;
+    /** `DumpGSettings(schema_id) -> s` — JSON of a schema's keys + values. */
+    DumpGSettings(schemaId: string): string;
+    /** `DumpCss() -> s` — JSON of the devtools-installed CSS provider names. */
+    DumpCss(): string;
+    /** `SwapCss(name, css) -> b` — live-install/replace a named CSS provider. */
+    SwapCss(name: string, css: string): boolean;
+    private _resolveRootWidget;
     private _isPaused;
     private _guard;
     private _scope;

package/lib/types/gsettings.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Dump every key + current value of an installed GSettings schema (read-only).
+ * Throws a `not-found`-coded error (the code survives the DBus wire) when the
+ * schema id is not installed.
+ */
+export declare function dumpGSettings(schemaId: string): Record<string, unknown>;

package/lib/types/index.d.ts

@@ -5,5 +5,8 @@ export { captureWidgetPng } from './screenshot.js';
 export { buildVariant, variantKindFor } from './gvariant.js';
 export type { VariantKind } from './gvariant.js';
 export { activateAction, changeActionState, describeActions } from './actions.js';
-export { buildDevtoolsIfaceXml, DEVTOOLS_INTERFACE } from './devtools-iface.js';
+export { buildDevtoolsIfaceXml } from './devtools-iface.js';
+export { buildWidgetPath, dumpTree, getWidgetProperty, listToplevels, parseWidgetPath, pathOfWidget, resolveWidgetPath, widgetType, } from './widget-tree.js';
+export { dumpCss, removeCss, swapCss } from './css.js';
+export { dumpGSettings } from './gsettings.js';
 export * from '@gjsify/devtools-protocol';

package/lib/types/widget-tree.d.ts

@@ -0,0 +1,37 @@
+import Gtk from '@girs/gtk-4.0';
+import type { NodeInfo } from '@gjsify/devtools-protocol';
+/** A parsed widget path: a toplevel index + a chain of child indices. */
+export interface ParsedWidgetPath {
+    toplevel: number;
+    children: number[];
+}
+/**
+ * Parse a stable widget path like `toplevel:0/child:2/child:0` into its
+ * indices. Pure (no GTK) so it is unit-testable on node + gjs. Returns null
+ * for a malformed path.
+ */
+export declare function parseWidgetPath(path: string): ParsedWidgetPath | null;
+/** Build a widget path from a toplevel index + child-index chain. */
+export declare function buildWidgetPath(toplevel: number, children: readonly number[]): string;
+/** The registered GType name of a widget instance (best-effort). */
+export declare function widgetType(widget: Gtk.Widget): string;
+/** Enumerate live toplevel windows as `{ path, type, title, mapped, focused }`. */
+export declare function listToplevels(): Array<{
+    path: string;
+    type: string;
+    title: string | null;
+    mapped: boolean;
+    focused: boolean;
+}>;
+/** Resolve a widget path to its live widget, or null if it no longer exists. */
+export declare function resolveWidgetPath(path: string): Gtk.Widget | null;
+/** Dump a widget subtree to {@link NodeInfo}, bounded by `maxDepth`. */
+export declare function dumpTree(root: Gtk.Widget, maxDepth: number, basePath: string): NodeInfo;
+/**
+ * Read a GObject property by name, trying the original, snake_case and
+ * camelCase accessor forms GJS exposes. Returns a JSON-safe value (non-scalars
+ * become a `[type]` marker).
+ */
+export declare function getWidgetProperty(widget: Gtk.Widget, prop: string): unknown;
+/** Compute the stable path of a live widget by walking up to its toplevel. */
+export declare function pathOfWidget(widget: Gtk.Widget): string | null;

package/lib/types/widget-tree.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/devtools",
-    "version": "0.8.0",
+    "version": "0.12.0",
     "description": "In-app DBus devtools control plane for GJS/GTK apps — inspect, screenshot, and drive a running app over org.gjsify.Devtools (gdbus or the MCP bridge)",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -43,11 +43,11 @@
         "@girs/gobject-2.0": "2.88.0-4.0.4",
         "@girs/graphene-1.0": "1.0.0-4.0.4",
         "@girs/gtk-4.0": "4.23.0-4.0.4",
-        "@gjsify/devtools-protocol": "^0.8.0"
+        "@gjsify/devtools-protocol": "^0.12.0"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.8.0",
-        "@gjsify/unit": "^0.8.0",
+        "@gjsify/cli": "^0.12.0",
+        "@gjsify/unit": "^0.12.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },