@gjsify/devtools 0.36.0 → 0.38.0

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

@@ -3,24 +3,20 @@ import Gtk from '@girs/gtk-4.0';
 import type { InstallDevtoolsOptions } from './extension.js';
 import { type DevtoolsPeerServer } from './peer-transport.js';
 /**
- * The permanent `org.gjsify.Devtools` DBus interface for a GTK app — lets
- * external tooling (the MCP bridge, `gdbus`, scripts) inspect, screenshot,
- * and drive the running app. Generic methods are implemented here; app
- * extensions contribute extra methods that are attached (pause-guarded) and
- * merged into the same interface. Resolves the live window lazily per call so
- * it survives window recreation.
+ * The permanent `org.gjsify.Devtools` DBus interface for a GTK app, through which
+ * external tooling (the MCP bridge, `gdbus`, scripts) inspects, screenshots and drives
+ * it. Generic methods live here; app extensions contribute pause-guarded methods merged
+ * into the same interface. The live window is resolved lazily per call, so the service
+ * survives window recreation.
  */
 export declare class DevtoolsService {
     private readonly _app;
     private readonly _options;
     /**
-     * One `Gio.DBusExportedObject` PER CONNECTION. The session bus is a single
-     * shared pipe, but the peer transport (`peer-transport.ts`) hands out one
-     * `Gio.DBusConnection` per client with no shared object registry — a
-     * single-slot field would export the interface to the FIRST peer only, and
-     * every later client would see `UnknownMethod` for all 26 methods. Keyed by
-     * connection, so `export()` stays idempotent PER connection while serving
-     * any number of them.
+     * One `Gio.DBusExportedObject` PER CONNECTION. The session bus is a single shared
+     * pipe, but the peer transport hands out one `Gio.DBusConnection` per client with no
+     * shared object registry, so a single-slot field would export to the FIRST peer only
+     * and every later client would see `UnknownMethod` for every method.
      */
     private readonly _exported;
     private _peer;
@@ -40,9 +36,9 @@ export declare class DevtoolsService {
      */
     unexport(connection?: Gio.DBusConnection): void;
     /**
-     * Record the peer server hosting this service — plus the file its address was
-     * published to, if any — so `unexport()` closes the socket AND retracts the
-     * claim, and callers can read both back rather than scraping the app's stderr.
+     * Record the peer server hosting this service and the file its address went to, so
+     * `unexport()` closes the socket AND retracts the claim, and callers can read both
+     * back instead of scraping the app's stderr.
      */
     attachPeerServer(peer: DevtoolsPeerServer, addressFile?: string | null): void;
     /** The peer address clients must dial, or `null` when this service is on a bus. */
@@ -54,29 +50,23 @@ export declare class DevtoolsService {
     /**
      * `Screenshot(scope) -> ay` — PNG bytes of the active window via the GSK renderer.
      *
-     * Implemented with the `<Name>Async` manual-reply convention (the method
-     * gets the raw `invocation` and calls `return_value()` itself) rather than a
-     * plain `async Screenshot(): Promise<Uint8Array>` ON PURPOSE. On gjs 1.86.0 a
-     * Promise-returning exported DBus method mis-marshals its resolved value and
-     * the caller sees `org.gnome.gjs.JSError.ValueError: Service implementation
-     * returned an incorrect value type` — the `_handleDBusReply` continuation in
-     * the Gio override fails for EVERY resolved type (a bare `s`, a pre-packed
-     * `GLib.Variant`, an `ay`), not just byte arrays; only Screenshot surfaced it
-     * because it is the sole async method in the interface. Replying manually
-     * through the invocation is unaffected. The wire method stays `Screenshot`
-     * (the interface XML is unchanged) — `wrapJSObject` falls back to
-     * `<Name>Async` when the bare name is absent. Tracked upstream in
-     * status/upstream-patch-candidates.md; collapse back to a plain `async
-     * Screenshot` once the gjs fix ships.
+     * Uses the `<Name>Async` manual-reply convention: the method takes the raw
+     * `invocation` and calls `return_value()` itself, and `wrapJSObject` finds it because
+     * it falls back to `<Name>Async` when the bare name is absent, so the wire method
+     * stays `Screenshot`.
+     *
+     * The shape exists because gjs 1.86.0 mis-marshalled the resolved value of ANY
+     * Promise-returning exported method (`org.gnome.gjs.JSError.ValueError: Service
+     * implementation returned an incorrect value type`), while a manual reply was
+     * unaffected. That no longer reproduces on gjs 1.88.1 — a plain `async Screenshot()`
+     * returning `ay` marshals correctly — so this can collapse back into one.
      */
     ScreenshotAsync(_params: unknown[], invocation: Gio.DBusMethodInvocation): Promise<void>;
     /**
-     * Capture the active window to PNG, warming up across frames when needed. A
-     * just-launched or mid-layout window yields a zero-size GSK frame, so the
-     * first `captureWidgetPng` can be empty; presenting it and retrying across a
-     * few main-loop iterations turns that into a real screenshot. The empty-bytes
-     * contract is preserved as the genuine-failure signal (window truly never
-     * realises / is occluded).
+     * Capture the active window to PNG, warming up across frames: a just-launched or
+     * mid-layout window yields a zero-size GSK frame, so the first `captureWidgetPng` can
+     * be empty. Empty bytes remain the genuine-failure signal, for a window that never
+     * realises at all.
      */
     private _captureActiveWindowPng;
     /** `ListActions() -> s` — JSON of the `app.*` + `win.*` actions. */

package/lib/types/extension.d.ts

@@ -1,11 +1,10 @@
 import type Gio from '@girs/gio-2.0';
 import type { MethodKind } from '@gjsify/devtools-protocol';
 /**
- * App-specific extension of the devtools control plane. The host contributes
- * extra DBus methods (e.g. the map-editor's PaintTile) without forking the
- * generic core: the `<method>` XML is merged into `org.gjsify.Devtools`, the
- * handlers are attached as concrete methods (positional DBus args), and each
- * carries a pause classification the guard enforces.
+ * App-specific extension of the devtools control plane: extra DBus methods (the
+ * map-editor's PaintTile, say) without forking the generic core. The `<method>` XML is
+ * merged into `org.gjsify.Devtools`, the handlers attach as concrete methods taking
+ * positional DBus args, and each carries a pause classification the guard enforces.
  */
 export interface DevtoolsExtension {
     /** `<method>…</method>` XML fragments merged into the interface. */

package/lib/types/install.d.ts

@@ -18,8 +18,7 @@ export type DevtoolsTransportChoice =
     kind: 'unregistered';
 };
 /**
- * The transport PRECEDENCE, as one pure function so it is machine-checked
- * rather than merely described:
+ * The transport PRECEDENCE, as one pure function so a spec can check it:
  *
  * | requested address | app has bus connection | session bus answers | choice |
  * |---|---|---|---|
@@ -28,16 +27,11 @@ export type DevtoolsTransportChoice =
  * | unset | no  | no  | `peer`, auto-picked — this machine has no usable bus |
  * | unset | no  | yes | `unregistered` — the bus is fine, the CALL SITE is early |
  *
- * The third row is the point of the whole transport, and it AUTO-PICKS rather
- * than failing: `GJSIFY_DEVTOOLS=1` is an explicit request for a control plane,
- * and answering it with "no control plane, one line on stderr" is exactly the
- * silent absence being removed. It cannot regress Linux — a host whose bus
- * answers never reaches that row.
- *
- * The fourth row deliberately does NOT fall back. The bus works, so the honest
- * diagnosis is that `installDevtools` ran before the application registered
- * (call it from `startup`); standing a socket up there would paper over a
- * call-site bug and hide it behind a working-looking address.
+ * Row three AUTO-PICKS rather than failing: `GJSIFY_DEVTOOLS=1` is an explicit request
+ * for a control plane, so refusing it with one stderr line is the silent absence this
+ * transport exists to remove. Row four deliberately does NOT fall back — the bus works,
+ * so the honest diagnosis is a call site that ran before registration, and a socket
+ * there would hide that behind a working-looking address.
  */
 export declare function chooseDevtoolsTransport(input: {
     requestedAddress?: string | null;
@@ -45,11 +39,9 @@ export declare function chooseDevtoolsTransport(input: {
     sessionBusUsable: boolean;
 }): DevtoolsTransportChoice;
 /**
- * The diagnostic for "no connection to export on". It must NAME THE RIGHT
- * CAUSE: the old message blamed the call site unconditionally ("call
- * installDevtools() from the startup handler"), which on macOS sent every reader
- * hunting a bug in their own app when the machine simply has no session bus.
- * Three distinguishable states, three answers.
+ * The diagnostic for "no connection to export on", which must NAME THE RIGHT CAUSE:
+ * blaming the call site unconditionally sent every macOS reader hunting a bug in their
+ * own app when the machine simply has no session bus. Three states, three answers.
  */
 export declare function describeMissingConnection(sessionBusAddress: string | null, busAnswers: boolean): string;
 /**
@@ -59,15 +51,14 @@ export declare function describeMissingConnection(sessionBusAddress: string | nu
  * handler — the session-bus connection + object path are only available after
  * the application has registered.
  *
- * Needs NO session bus (macOS, Windows): with none, it listens on a socket of
- * its own and publishes the address. {@link chooseDevtoolsTransport} documents
- * the precedence; `options.address` / `GJSIFY_DEVTOOLS_ADDRESS` pins it.
+ * Needs NO session bus (macOS, Windows): with none it listens on a socket of its own
+ * and publishes the address — precedence in {@link chooseDevtoolsTransport},
+ * `options.address` / `GJSIFY_DEVTOOLS_ADDRESS` pins it.
  *
- * TOTAL BY CONTRACT: it never throws. Every failure — an address already in use,
- * a stale socket that cannot be reclaimed, a malformed address — is reported on
- * stderr with the address and the way out, and returns `null` like the disabled
- * path. Callers wire it into `startup`/`activate` handlers whose remaining
- * statements (`present()`, `onStartup()`) GJS would silently skip on a throw.
+ * TOTAL BY CONTRACT: it never throws. Every failure is reported on stderr with the
+ * address and the way out, and returns `null` like the disabled path, because callers
+ * wire it into `startup`/`activate` handlers whose remaining statements GJS would
+ * silently skip on a throw.
  *
  * @example
  * ```ts

package/lib/types/peer-transport.d.ts

@@ -11,20 +11,16 @@ export interface DevtoolsPeerServer {
     stop(): void;
 }
 /**
- * A peer transport that could not be stood up. `message` is already the
- * operator-facing sentence — `installDevtools` logs it verbatim rather than
- * paraphrasing a localised GIO error (on a German desktop the bare
- * `Gio.DBusServer` failure reads `Fehler beim Binden an Adresse
- * (GUnixSocketAddress): Die Adresse wird bereits verwendet`, which names neither
- * the address nor a way out).
+ * A peer transport that could not be stood up. `message` is already the operator-facing
+ * sentence, which `installDevtools` logs verbatim: the bare `Gio.DBusServer` failure is
+ * LOCALISED and names neither the address nor a way out.
  */
 export declare class DevtoolsPeerServerError extends Error {
     readonly address: string;
     readonly reason: 'address-in-use' | 'occupied-by-other-file' | 'listen-failed';
     /**
-     * The GIO failure underneath, when there was one. A field rather than the
-     * `Error(message, { cause })` option because this package compiles to
-     * `lib: es2020`, which predates it.
+     * The GIO failure underneath, as a field rather than `Error(message, { cause })`:
+     * this package compiles to `lib: es2020`, which predates that option.
      */
     readonly cause?: unknown;
     constructor(message: string, address: string, reason: 'address-in-use' | 'occupied-by-other-file' | 'listen-failed', cause?: unknown);
@@ -33,17 +29,14 @@ export declare class DevtoolsPeerServerError extends Error {
  * Listen on `address` (auto-picked when omitted) and export `service` at
  * `objectPath` on every incoming peer connection.
  *
- * Each peer connection is its own `Gio.DBusConnection` with no shared name
- * registry, so the interface has to be exported per connection — which is why
- * `DevtoolsService.export()` tracks exports per connection rather than once. A
- * second client would otherwise attach to a connection with nothing on it and
- * see `UnknownMethod` for every call, the exact silent-absence failure this
- * whole transport exists to remove.
+ * Each peer connection is its own `Gio.DBusConnection` with no shared name registry, so
+ * the interface must be exported PER CONNECTION — hence `DevtoolsService.export()`
+ * tracking exports per connection. A second client would otherwise attach to a
+ * connection with nothing on it and see `UnknownMethod` for every call.
  *
- * Throws a {@link DevtoolsPeerServerError} when the address cannot be listened on
- * — an explicitly requested address that does not work is a configuration error
- * the operator must see, and the message says what to do about it. `installDevtools`
- * catches it: an opt-in diagnostic must never abort an app's lifecycle.
+ * Throws a {@link DevtoolsPeerServerError} when the address cannot be listened on, with
+ * a message saying what to do about it; `installDevtools` catches it, because an opt-in
+ * diagnostic must never abort an app's lifecycle.
  */
 export declare function startDevtoolsPeerServer(service: DevtoolsService, objectPath: string, address?: string): DevtoolsPeerServer;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/devtools",
-    "version": "0.36.0",
+    "version": "0.38.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": "^4.1.0",
         "@girs/graphene-1.0": "^4.1.0",
         "@girs/gtk-4.0": "^4.1.0",
-        "@gjsify/devtools-protocol": "^0.36.0"
+        "@gjsify/devtools-protocol": "^0.38.0"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.36.0",
-        "@gjsify/unit": "^0.36.0",
+        "@gjsify/cli": "^0.38.0",
+        "@gjsify/unit": "^0.38.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },