@gjsify/devtools 0.52.0 → 0.54.0

package/README.md

@@ -149,14 +149,61 @@ Three of those need their reason stated, because the obvious use is the wrong on
 
 `opts.extend` adds app-specific methods (§ below); `opts.instance` / `GJSIFY_DEVTOOLS_INSTANCE` scope a multi-instance app.
 
-### Calling one by hand
+### Calling one by hand — or from `gjsify devtools`
+
+`gdbus` reaches the plane, and it is the right tool for reading a status string. It cannot do the
+two things a script actually needs: `gdbus` cannot write BINARY (so a screenshot comes back as an
+`ay` variant nobody can save), and it speaks only the session bus (which macOS and Windows do not
+have — see above). So both halves live in this package instead of in every consumer's own script:
 
 ```bash
-gdbus call --session --dest <app-id> --object-path <path>/devtools \
-  --method org.gjsify.Devtools.Screenshot ""
+gjsify devtools shot /tmp/app.png --bus-name org.example.App   # PNG on disk + its real size
+gjsify devtools find Adw.StatusPage:error --bus-name org.example.App   # → a widget path
+gjsify devtools activate /toplevel:0/child:3 --bus-name org.example.App
+gjsify devtools help                                          # every operation and flag
 ```
 
-That returns an `ay` variant. `gdbus` itself cannot save binary, so unpack it from a tiny GJS caller.
+Set `gjsify.devtools.busNameBase` in `package.json` once and the flag stops being needed. Progress
+goes to **stderr**, the result to **stdout**, so `$(gjsify devtools find …)` is the widget path.
+**Exit codes are the contract**: `0` done, `1` the app said no (no match, refused key, no image),
+`2` the request itself was wrong (unknown operation, no `--bus-name`).
+
+`gjsify devtools` is the scriptable peer of [`gjsify debug`](../devtools-mcp) (MCP over stdio, for
+an AI agent) — same transport, same client, different front end. `--address` reaches the peer
+socket on a bus-less host, and `--timeout <s>` waits for `GetStatus` to answer rather than sleeping:
+a cold start measured 94 s before the first call was served.
+
+### Getting a screenshot onto disk — `captureShot`
+
+`gdbus call … Screenshot` returns an `ay` variant, and unpacking one into a file was a 60-line GJS
+script per consumer. `captureShot` is that script, once:
+
+```ts
+import { captureShot } from '@gjsify/devtools/shot';
+
+const shot = await captureShot(
+    async (scope) => client.control(instance, 'Screenshot', tuple(scope), '(ay)'),
+    '/tmp/app.png',
+    'window',
+);
+shot.width; // 1100 — read out of the PNG, NOT the size asked for
+```
+
+The `./shot` entry point is deliberately GTK-free: the client side of a screenshot needs Gio and
+GLib only, so a headless client does not drag this package's app-side GTK adapter in with it.
+
+Two invariants ride along, each paid for with a measured incident:
+
+- **Empty bytes are a FAILURE, not a picture.** `Screenshot` answers `ay[0]` when there is no active
+  window or the window was never realised — a deliberate contract, see `CaptureBlocker`. Writing
+  that yields a 0-byte `.png`, a success line and exit 0: a rig that reports success while handing
+  on a file nothing can open. `captureShot` retries, then throws `CaptureShotError('empty-answer')`
+  **without writing the file**.
+- **The size comes from the PNG, never from the request.** `ResizeWindow` answers with the size it
+  was ASKED for, whether or not the window honoured it, and `default-width` reads back that same
+  asked-for value. Measured in a consumer: 1280 requested, 1100 in the file, four checks green.
+  `pngSize()` reads the IHDR header instead, which is the one number about a screenshot that cannot
+  be faked — so `resize` cannot report its own failure and `shot` can.
 
 ## App-specific methods — a `DevtoolsExtension`
 
@@ -175,6 +222,31 @@ const myExtension: DevtoolsExtension = {
 installDevtools(this, { extend: [myExtension] });
 ```
 
+## The Adwaita markup trap
+
+A widget property that Pango parses as markup turns a bare `&` or `<` into a **parse error**, and
+the label renders **blank**. Nothing throws, nothing fails, and the only symptom is a screenshot
+somebody looks at. German UI text is full of `&` ("Kosten & Förderung"), so it is a recurring class.
+
+```ts
+import { hasRawPangoMarkup, isPangoMarkupSink } from '@gjsify/devtools';
+
+isPangoMarkupSink('AdwActionRow', 'title');        // true — `use-markup` is @default true
+hasRawPangoMarkup('Kosten & Förderung');           // true — the label would render empty
+hasRawPangoMarkup('Kosten &amp; Förderung');      // false — an entity is markup, and valid
+hasRawPangoMarkup('<b>Kosten</b> & Ertrag');       // false — markup you wrote on purpose
+```
+
+The interesting half is `PANGO_MARKUP_SINKS`, the list of properties that parse markup at all,
+because the traps cut both ways. `Gtk.Label:label` and `AdwWindowTitle:title` are plain text —
+reporting `&` there teaches an audience to switch the check off. And **`AdwAlertDialog:heading` and
+`:body` are plain text by default**: `heading-use-markup` / `body-use-markup` are both
+`@default false` in `@girs/adw-1`, so a sink list that includes them is wrong, however plausible it
+looks. Every row class inherits markup titles from `AdwPreferencesRow:use-markup` (`@default true`,
+"subclasses may also use it for other labels, such as subtitle") — which is where the trap in most
+apps comes from. Runtime values need `GLib.markup_escape_text()` at the point of use; this checks
+literals, it does not claim a rendered string is clean.
+
 ## Exports
 
 - `installDevtools(app, options)` → returns a `DevtoolsService`, or `null` when the env gate is off **or the transport could not come up**. It never throws: every failure is one stderr line naming the address and the way out. `uninstallDevtools(service)` — opt-in lifecycle; it stops the socket *and* retracts the published address.
@@ -183,6 +255,8 @@ installDevtools(this, { extend: [myExtension] });
 - `startDevtoolsPeerServer(service, objectPath, address?)` → `DevtoolsPeerServer` — the bus-less transport by hand; it throws `DevtoolsPeerServerError` (with `address` + `reason`) when the address is unusable, which is what `installDevtools` catches. `chooseDevtoolsTransport(input)` — the precedence table above as a pure function; `writeDevtoolsAddressFile` / `removeDevtoolsAddressFile` — publish/retract a peer address.
 - `captureWidgetPng` (GSK screenshot), `buildVariant` / `variantKindFor` / `VariantKind` (GVariant), `activateAction` / `changeActionState` / `describeActions` (GAction bridge).
 - widget-tree helpers (`dumpTree`, `getWidgetProperty`, `listToplevels`, `resolveWidgetPath`, …), `dumpCss` / `swapCss` / `removeCss`, `dumpGSettings`, `buildDevtoolsIfaceXml`.
+- **client-side, from the GTK-free `./shot` entry point**: `captureShot(source, path, scope?, options?)` → `ShotResult` (with `width`/`height` read from the PNG) or `CaptureShotError`; `pngSize(bytes)` → `{ width, height }` or `null` for bytes that are not a PNG.
+- markup-trap helpers (root entry point): `hasRawPangoMarkup(text)`, `rawPangoMarkupIn(text)`, `isPangoMarkupSink(class, property)`, `PANGO_MARKUP_SINKS`.
 - 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.

package/lib/esm/index.js

@@ -1 +1 @@
-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{DevtoolsPeerServerError as l,removeDevtoolsAddressFile as u,startDevtoolsPeerServer as d,writeDevtoolsAddressFile as f}from"./peer-transport.js";import{captureWidget as p,captureWidgetPng as m}from"./screenshot.js";import{dumpGSettings as h}from"./gsettings.js";import{buildWidgetPath as g,dumpTree as _,getWidgetProperty as v,listToplevels as y,parseWidgetPath as b,pathOfWidget as x,resolveWidgetPath as S,widgetIsA as C,widgetType as w}from"./widget-tree.js";import{DevtoolsService as T}from"./devtools-service.js";import{chooseDevtoolsTransport as E,installDevtools as D,uninstallDevtools as O}from"./install.js";export*from"@gjsify/devtools-protocol";export{l as DevtoolsPeerServerError,T as DevtoolsService,n as activateAction,c as buildDevtoolsIfaceXml,e as buildVariant,g as buildWidgetPath,p as captureWidget,m as captureWidgetPng,r as changeActionState,E as chooseDevtoolsTransport,i as describeActions,a as dumpCss,h as dumpGSettings,_ as dumpTree,v as getWidgetProperty,D as installDevtools,y as listToplevels,b as parseWidgetPath,x as pathOfWidget,o as removeCss,u as removeDevtoolsAddressFile,S as resolveWidgetPath,d as startDevtoolsPeerServer,s as swapCss,O as uninstallDevtools,t as variantKindFor,C as widgetIsA,w as widgetType,f as writeDevtoolsAddressFile};
+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{DevtoolsPeerServerError as l,removeDevtoolsAddressFile as u,startDevtoolsPeerServer as d,writeDevtoolsAddressFile as f}from"./peer-transport.js";import{captureWidget as p,captureWidgetPng as m}from"./screenshot.js";import{dumpGSettings as h}from"./gsettings.js";import{buildWidgetPath as g,dumpTree as _,getWidgetProperty as v,listToplevels as y,parseWidgetPath as b,pathOfWidget as x,resolveWidgetPath as S,widgetIsA as C,widgetType as w}from"./widget-tree.js";import{DevtoolsService as T}from"./devtools-service.js";import{chooseDevtoolsTransport as E,installDevtools as D,uninstallDevtools as O}from"./install.js";import{CaptureShotError as k,captureShot as A,pngSize as j}from"./shot.js";import{PANGO_MARKUP_SINKS as M,hasRawPangoMarkup as N,isPangoMarkupSink as P,rawPangoMarkupIn as F}from"./pango.js";export*from"@gjsify/devtools-protocol";export{k as CaptureShotError,l as DevtoolsPeerServerError,T as DevtoolsService,M as PANGO_MARKUP_SINKS,n as activateAction,c as buildDevtoolsIfaceXml,e as buildVariant,g as buildWidgetPath,A as captureShot,p as captureWidget,m as captureWidgetPng,r as changeActionState,E as chooseDevtoolsTransport,i as describeActions,a as dumpCss,h as dumpGSettings,_ as dumpTree,v as getWidgetProperty,N as hasRawPangoMarkup,D as installDevtools,P as isPangoMarkupSink,y as listToplevels,b as parseWidgetPath,x as pathOfWidget,j as pngSize,F as rawPangoMarkupIn,o as removeCss,u as removeDevtoolsAddressFile,S as resolveWidgetPath,d as startDevtoolsPeerServer,s as swapCss,O as uninstallDevtools,t as variantKindFor,C as widgetIsA,w as widgetType,f as writeDevtoolsAddressFile};

package/lib/esm/pango.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";const e={AdwAboutDialog:[`comments`,`license`],AdwAboutWindow:[`comments`,`license`],AdwActionRow:[`title`,`subtitle`],AdwBanner:[`title`],AdwComboRow:[`title`,`subtitle`],AdwEntryRow:[`title`,`subtitle`],AdwExpanderRow:[`title`,`subtitle`],AdwPreferencesGroup:[`title`,`description`],AdwPreferencesPage:[`title`,`description`],AdwSpinRow:[`title`,`subtitle`],AdwStatusPage:[`title`,`description`],AdwSwitchRow:[`title`,`subtitle`],AdwToast:[`title`]},t=`&(?![a-zA-Z][a-zA-Z0-9]*;|#\\d+;|#x[0-9a-fA-F]+;)|<(?![a-zA-Z/!?])`,n=RegExp(t),r=RegExp(t,`g`);function rawPangoMarkupIn(e){let t=new Set;for(let n of e.matchAll(r))t.add(n[0]);return[...t]}function hasRawPangoMarkup(e){return e.length<2?!1:n.test(e)}function isPangoMarkupSink(t,n){let r=e[t];return r?r.includes(n):!1}export{e as PANGO_MARKUP_SINKS,hasRawPangoMarkup,isPangoMarkupSink,rawPangoMarkupIn};

package/lib/esm/shot.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import e from"gi://GLib?version=2.0";import t from"gi://Gio?version=2.0";const n=[137,80,78,71,13,10,26,10];var CaptureShotError=class extends Error{constructor(e,t,n,r){super(n),this.scope=e,this.reason=t,this.cause=r,this.name=`CaptureShotError`}};function pngSize(e){if(e.length<24)return null;for(let t=0;t<n.length;t++)if(e[t]!==n[t])return null;let t=new DataView(e.buffer,e.byteOffset,e.byteLength);return{width:t.getUint32(16),height:t.getUint32(20)}}function delay(t){return new Promise(n=>{e.timeout_add(e.PRIORITY_DEFAULT,t,()=>(n(),e.SOURCE_REMOVE))})}function writeBytes(e,n){t.File.new_for_path(e).replace_contents(n,null,!1,t.FileCreateFlags.REPLACE_DESTINATION,null)}async function captureShot(e,t,n=`window`,r={}){let{retries:i=8,retryDelayMs:a=250,settleMs:o=0}=r;o>0&&await delay(o);let s=new Uint8Array;for(let t=0;t<=i&&(s=await e(n),!(s.length>0));t++)t<i&&await delay(a);if(s.length===0)throw new CaptureShotError(n,`empty-answer`,`no image for scope "${n}" after ${i+1} attempts — the window is absent or was never realised`);let c=pngSize(s);if(!c)throw new CaptureShotError(n,`unreadable-png`,`scope "${n}" answered ${s.length} bytes that are not a PNG — refusing to write them out as an image`);try{writeBytes(t,new Uint8Array(s))}catch(e){throw new CaptureShotError(n,`write-failed`,`cannot write ${t}`,e)}return{path:t,byteLength:s.length,width:c.width,height:c.height}}export{CaptureShotError,captureShot,pngSize};

package/lib/types/index.d.ts

@@ -5,11 +5,14 @@ export type { DevtoolsExtension, InstallDevtoolsOptions } from './extension.js';
 export { DevtoolsPeerServerError, removeDevtoolsAddressFile, startDevtoolsPeerServer, writeDevtoolsAddressFile, } from './peer-transport.js';
 export type { DevtoolsPeerServer } from './peer-transport.js';
 export { captureWidget, captureWidgetPng, type CaptureBlocker, type CaptureResult } from './screenshot.js';
+export { CaptureShotError, captureShot, pngSize } from './shot.js';
+export type { CaptureShotOptions, PngSize, PngSource, ShotFailure, ShotResult } from './shot.js';
 export { buildVariant, variantKindFor } from './gvariant.js';
 export type { VariantKind } from './gvariant.js';
 export { activateAction, changeActionState, describeActions } from './actions.js';
 export { buildDevtoolsIfaceXml } from './devtools-iface.js';
 export { buildWidgetPath, dumpTree, getWidgetProperty, listToplevels, parseWidgetPath, pathOfWidget, resolveWidgetPath, widgetIsA, widgetType, } from './widget-tree.js';
 export { dumpCss, removeCss, swapCss } from './css.js';
+export { hasRawPangoMarkup, isPangoMarkupSink, PANGO_MARKUP_SINKS, rawPangoMarkupIn } from './pango.js';
 export { dumpGSettings } from './gsettings.js';
 export * from '@gjsify/devtools-protocol';

package/lib/types/pango.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Adw properties whose value Pango parses as markup, as `ClassName` → the properties it applies to.
+ *
+ * The `use-markup` / `*-use-markup` properties are the documented switches, and their DEFAULTS are
+ * what decide membership. Read out of `@girs/adw-1`:
+ *
+ * · `AdwPreferencesRow:use-markup` — `@default true`, "whether to use Pango markup for the title
+ *   label … subclasses may also use it for other labels, such as subtitle". So every
+ *   `AdwPreferencesRow` subclass has markup `title` AND `subtitle` unless it opts out.
+ * · `AdwBanner:use-markup` and `AdwToast:use-markup` — both `@default true`, for the title.
+ * · `AdwAlertDialog:heading-use-markup` and `:body-use-markup` — both **`@default false`**, so
+ *   `heading` and `body` are PLAIN TEXT by default and marking them raw would be a false finding.
+ *   This is where a sink list copied from a consumer's own script goes wrong.
+ * · `AdwMessageDialog` (deprecated since 1.6) is absent for the same practical reason: its heading
+ *   and body went through markup, but it has no toggle to read a default off and no reason to be
+ *   written in new code.
+ * · `AdwPreferencesGroup`, `AdwPreferencesPage` and `AdwStatusPage` carry no toggle and no GIR note;
+ *   their titles and descriptions are markup in libadwaita's implementation. Included, and noted
+ *   here as the one group not backed by GIR documentation, so a future correction has a home.
+ * · `AdwAboutDialog`/`AdwAboutWindow` — the GIR documents `comments` ("can also contain links and
+ *   Pango markup") and `license` ("can contain Pango markup and links") in prose. `debug_info` is
+ *   in the same class and explicitly cannot, which is why it is not here.
+ *
+ * `Gtk.Label:label` and `AdwWindowTitle:title` are plain text and are deliberately absent: a rule
+ * that reports `&` in those teaches its audience to switch it off.
+ */
+export declare const PANGO_MARKUP_SINKS: Readonly<Record<string, readonly string[]>>;
+/** The raw markup characters in `text`, deduplicated; empty when the string parses as markup. */
+export declare function rawPangoMarkupIn(text: string): string[];
+/**
+ * Would `text` render BLANK as an Adw markup property?
+ *
+ * The single-character cases are answered first because they are the ones that read as deliberate:
+ * an author who wrote `"&"` or `"<"` meant them, and flagging it teaches nothing.
+ */
+export declare function hasRawPangoMarkup(text: string): boolean;
+/** Is `property` of `className` (e.g. `'AdwActionRow'`, `'title'`) a markup sink? */
+export declare function isPangoMarkupSink(className: string, property: string): boolean;

package/lib/types/pango.spec.d.ts

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

package/lib/types/shot.d.ts

@@ -0,0 +1,60 @@
+/** Fetches PNG bytes for a scope (`''`/`window` for the active window, a widget path for one widget). */
+export type PngSource = (scope: string) => Promise<Uint8Array>;
+/** The pixel dimensions read out of a PNG's own IHDR header. */
+export interface PngSize {
+    width: number;
+    height: number;
+}
+/** A written screenshot: where it is, how big the file is, and how big the PICTURE is. */
+export interface ShotResult {
+    path: string;
+    /** Bytes on disk. Never 0 — a capture that produced none throws instead. */
+    byteLength: number;
+    /** From the PNG header, so it is what the file actually contains. */
+    width: number;
+    height: number;
+}
+/** Tunables for {@link captureShot}; the defaults are the measured ones from a consumer rig. */
+export interface CaptureShotOptions {
+    /**
+     * How many extra attempts after an empty answer. The window is often mid-layout, so one
+     * empty reply is normal right after `present()` — 8 × 250 ms was enough for every cold
+     * start measured, and 0 is the right answer for a caller that drives its own settling.
+     */
+    retries?: number;
+    /** Gap between attempts, milliseconds. */
+    retryDelayMs?: number;
+    /** Pause before the FIRST capture — the counterpart of a rig's `--settle`. */
+    settleMs?: number;
+}
+/** Why {@link captureShot} gave up. Named, because "it wrote nothing" is not a diagnosis. */
+export type ShotFailure = 'empty-answer' | 'unreadable-png' | 'write-failed';
+/** The capture that did not happen. Thrown so a caller cannot mistake it for a picture. */
+export declare class CaptureShotError extends Error {
+    readonly scope: string;
+    readonly reason: ShotFailure;
+    readonly cause?: unknown | undefined;
+    constructor(scope: string, reason: ShotFailure, message: string, cause?: unknown | undefined);
+}
+/**
+ * The pixel size of a PNG, read from its IHDR chunk — the width and height are the first two
+ * big-endian `uint32`s after the 8-byte signature and the chunk header.
+ *
+ * Returns `null` for anything that is not a PNG carrying an IHDR, rather than guessing: a
+ * caller printing a size is reporting what the file contains, and a plausible number derived
+ * from bytes that are not a header is worse than no number. Zero width or height cannot occur
+ * in a valid PNG (both are `>= 1`), so `null` is not reachable for a well-formed file.
+ */
+export declare function pngSize(bytes: Uint8Array): PngSize | null;
+/**
+ * Capture a screenshot through `source` and save it to `path`.
+ *
+ * Retries while the app answers empty bytes (see the file header), then throws
+ * {@link CaptureShotError} instead of writing a 0-byte file. The returned size is the PNG's
+ * own, not the size that was asked for.
+ *
+ * @throws {CaptureShotError} `empty-answer` after the retries are spent, `unreadable-png` when
+ * the bytes are not a PNG (a control plane that answered with something else is a different
+ * bug and must not be written out as an image), `write-failed` when the path is not writable.
+ */
+export declare function captureShot(source: PngSource, path: string, scope?: string, options?: CaptureShotOptions): Promise<ShotResult>;

package/lib/types/shot.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.52.0",
+    "version": "0.54.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",
@@ -9,6 +9,10 @@
         ".": {
             "types": "./lib/types/index.d.ts",
             "default": "./lib/esm/index.js"
+        },
+        "./shot": {
+            "types": "./lib/types/shot.d.ts",
+            "default": "./lib/esm/shot.js"
         }
     },
     "files": [
@@ -45,12 +49,12 @@
         "@girs/gobject-2.0": "5.4.0",
         "@girs/graphene-1.0": "5.4.0",
         "@girs/gtk-4.0": "5.4.0",
-        "@gjsify/devtools-protocol": "^0.52.0"
+        "@gjsify/devtools-protocol": "^0.54.0"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.52.0",
+        "@gjsify/cli": "^0.54.0",
         "@gjsify/node-gi": "file:../../node-gi/node-gi",
-        "@gjsify/unit": "^0.52.0",
+        "@gjsify/unit": "^0.54.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },