@gjsify/gtk-host 0.52.0 → 0.54.0

package/lib/types/registry.d.ts

@@ -4,6 +4,60 @@ export declare function registerWidget(descriptor: WidgetDescriptor): void;
 export declare function registerWidgets(descriptors: readonly WidgetDescriptor[]): void;
 export declare function lookupWidget(tag: string): WidgetDescriptor;
 export declare const hasWidget: (tag: string) => boolean;
+/** A row's class, in the shape every consumer here needs it. */
+export type InstalledClass = GObject.ObjectClass & (new (props?: Record<string, unknown>) => GObject.Object);
+/**
+ * The class the RUNNING typelib has for this row, or `null` when it has none.
+ *
+ * The general form of "does this GTK have that class", and the only honest place
+ * to ask it: the generated table is produced from ONE platform's GIR (#1446), and
+ * a platform does not build every class that GIR describes — GTK `#ifdef`s its
+ * Unix print stack out on Windows, so `GtkPrintUnixDialog` and
+ * `GtkPageSetupUnixDialog` are rows whose class is `undefined` there and a real
+ * class on Linux and macOS. Nothing narrower is available: the vocabulary comes
+ * from one GIR pool with no second platform to compare against, and a claim
+ * derived from a NAME (`*Unix*`) breaks precisely when it matters, on the next
+ * absent class nobody spelled that way.
+ *
+ * THE CAST is where the gap between the declared type and the runtime is
+ * admitted, ONCE, with the reason. `ctor` is typed as promising a constructor
+ * unconditionally, which is what lets `new Klass(props)` read as a constructor
+ * call; the promise is true on every host the table was generated on and false
+ * on a host that omits a class, and the admission belongs beside the question
+ * rather than at each of the dozen call sites.
+ *
+ * WHY THE ROW'S OWN `ctor()` IS THE ORACLE, and it is a measured trap rather
+ * than a stylistic choice. `GObject.type_from_name` is the one-call version of
+ * this question and it answers WRONG in the direction that costs a working row:
+ * measured on gjs 1.88.1 / Homebrew GTK 4.24.0, `type_from_name('GtkPrintUnixDialog')`
+ * answers **0** while `Gtk.PrintUnixDialog` is present and constructs — a typelib
+ * registers a class when the namespace member is first READ, not when the
+ * typelib loads. `ctor()` IS that read, which is why it answers correctly in
+ * both directions and why nothing here calls `type_from_name`. It also costs
+ * nothing to ask per row: an oracle over the WHOLE table has to force the
+ * registration of every class it walks, whereas a row is only ever asked about
+ * when something is about to use it.
+ */
+export declare function classOf(descriptor: {
+    readonly ctor: () => unknown;
+}): InstalledClass | null;
+/** Whether this host has the class a row names — a table sweep's way to not be a row. */
+export declare const hasClass: (descriptor: {
+    readonly ctor: () => unknown;
+}) => boolean;
+/**
+ * {@link classOf}, refusing BY NAME rather than handing back `undefined`.
+ *
+ * The single gate every read of a row's class goes through, so an absent class is
+ * one named refusal instead of six anonymous `TypeError`s — dereferencing it
+ * produced `Cannot read properties of undefined (reading 'list_properties')` and
+ * `… (reading '$gtype')` with no row in either message, which is how a
+ * one-platform-generated table arrived as six failures that named one class.
+ */
+export declare function requireClass(descriptor: {
+    readonly gtype: string;
+    readonly ctor: () => unknown;
+}): InstalledClass;
 /** Every registered GType name — the conformance suite walks this, so coverage is data. */
 export declare const registeredTags: () => string[];
 /**

package/lib/types/testing/gate.d.mts

@@ -10,9 +10,9 @@ export declare const gated: (gate: DiagnosticsGate, name: string, body: () => Pr
  * failure mode rather than taste.
  *
  * A capability can only be PROBED — nothing about `(os, env)` answers "is the Gtk
- * typelib reachable from this process", and `@gjsify/unit` is Tier 1 and must not
- * import `gi://` to find out. A probe that answers "no" makes the whole suite STAND
- * DOWN, and `requireAxes` cannot catch that: it only holds axes the host MATCHES.
+ * typelib reachable from this process". A probe that answers "no" makes the whole
+ * suite STAND DOWN, and `requireAxes` cannot catch that: it only holds axes the
+ * host MATCHES (`GJSIFY_TEST_EXPECT_AXES` can, but only on a leg that sets it).
  * So a container that lost its GTK would run zero tests and report success — the
  * green-that-checked-nothing shape, arriving through the very gate meant to widen
  * coverage. Measured once already: gated on `'Gjs'` alone, this suite built for the

package/lib/types/types.d.ts

@@ -13,11 +13,7 @@ export interface HostText extends HostNodeBase {
     readonly kind: 'text';
     data: string;
 }
-/**
- * A position marker. Vue's `createComment` and Svelte's comment markers land here.
- * An anchor NEVER enters the GTK tree; `insert` resolves forward past it to the
- * next node that actually owns a widget.
- */
+/** A position marker. Vue's `createComment` and Svelte's comment markers land here. */
 export interface HostAnchor extends HostNodeBase {
     readonly kind: 'anchor';
     data: string;
@@ -36,9 +32,9 @@ export interface HostElement extends HostNodeBase {
     /**
      * signal name -> the one native handler, and the prop that owns it.
      *
-     * One handler per signal name, ever. The owner is recorded because two props
-     * can resolve to the same signal (`onClicked` and `on:clicked`), and the
-     * second used to disconnect the first without saying so.
+     * One handler per signal name, ever. The owner is recorded because two props can
+     * resolve to the same signal (`onClicked` and `on:clicked`), and the second used
+     * to disconnect the first without saying so.
      */
     handlers: Map<string, {
         id: number;
@@ -54,10 +50,10 @@ export interface HostElement extends HostNodeBase {
     /**
      * The authored ARIA object, or null — the accessibility GTK holds for this widget.
      *
-     * A field of its own and NOT a key in `props`, for the reason `layout` is one: `props`
-     * is replayed into `g_object_new` by `materialize`, and none of these names is a
-     * construct property. It is the LAST authored value, so a patch can compute which
-     * slots the new object no longer sets and reset exactly those.
+     * A field of its own and NOT a key in `props`, because `props` is replayed into
+     * `g_object_new` by `materialize` and none of these names is a construct property. It is
+     * the LAST authored value, so a patch can compute which slots the new object no longer
+     * sets and reset exactly those.
      */
     accessibility: Record<string, unknown> | null;
     /** True once text CHILDREN wrote the sink, so removing the last one clears it
@@ -66,11 +62,10 @@ export interface HostElement extends HostNodeBase {
     /**
      * True while this element is actually IN its parent's GTK tree.
      *
-     * Owning a widget is not the same thing: every framework builds bottom-up,
-     * so a subtree is materialised long before it is inserted. Deriving "is my
-     * sibling in the tree" from `widget !== null` made the remove-all policy
-     * detach non-children and re-add already-parented ones — two Adwaita
-     * criticals per replay, at exit 0.
+     * Owning a widget is not the same thing: every framework builds bottom-up, so a subtree
+     * is materialised long before it is inserted. Deriving "is my sibling in the tree" from
+     * `widget !== null` made the remove-all policy detach non-children and re-add
+     * already-parented ones — two Adwaita criticals per replay, at exit 0.
      */
     attached: boolean;
     /** True once `destroy` has torn this element down. It never comes back. */
@@ -78,19 +73,18 @@ export interface HostElement extends HostNodeBase {
     /**
      * Children this element already had before the host adopted it.
      *
-     * Only an ADOPTED root has any: a renderer mounts into a container the
-     * application built, and those children are in the GTK tree while being absent
-     * from the shadow tree. Placement offsets past them, or the first insertion
-     * computes "first" and the whole rendered tree lands ABOVE the app's own chrome.
+     * Only an ADOPTED root has any: a renderer mounts into a container the application built,
+     * and those children are in the GTK tree while being absent from the shadow tree.
+     * Placement offsets past them, or the first insertion computes "first" and the whole
+     * rendered tree lands ABOVE the app's own chrome.
      */
     foreign: readonly Gtk.Widget[];
     /**
      * A PORTAL node's subscription to its parent's `root`, or null.
      *
-     * Only a `portal` placement ever has one, and it is per-attachment state
-     * exactly like `wrapper` — a side table keyed on the element would be a second
-     * tree that can disagree with this one. See {@link NodePlacement}'s portal arm
-     * for what the subscription is for and what it was measured against.
+     * Only a `portal` placement ever has one, and it is per-attachment state exactly like
+     * `wrapper` — a side table keyed on the element would be a second tree that can disagree
+     * with this one. See {@link NodePlacement}'s portal arm for what the subscription is for.
      */
     portalWatch: {
         widget: Gtk.Widget;
@@ -101,36 +95,36 @@ export type HostNode = HostElement | HostText | HostAnchor;
 /**
  * The axis ABOVE `ChildPolicy`, and the two are orthogonal on purpose.
  *
- * `ChildPolicy` answers "how does this parent adopt a child". It presumes the
- * answer to a question nobody had to ask until now: *does this node go into its
- * parent at all?* For every widget in the table it does. For an `Adw.Dialog` it
- * does not, and the difference is not a degradation the parent can absorb —
- * MEASURED on libadwaita 1.9.3 / GTK 4.22.4 / gjs 1.88.1, `box.append(dialog)`
- * with the box ROOTED IN A WINDOW reaches
+ * `ChildPolicy` answers "how does this parent adopt a child". It presumes the answer
+ * to a question nobody had to ask until now: *does this node go into its parent at
+ * all?* For every widget in the table it does. For an `Adw.Dialog` it does not, and
+ * the difference is not a degradation the parent can absorb — MEASURED on libadwaita
+ * 1.9.3 / GTK 4.22.4 / gjs 1.88.1, `box.append(dialog)` with the box ROOTED IN A WINDOW
+ * reaches
  *
  *     Adwaita-ERROR **: Trying to add AdwDialog 0x… to GtkBox 0x…. Use
  *     adw_dialog_present() to show dialogs.
  *
- * which is `g_error()`: SIGABRT, exit 134, a core dump. Not an exception a `try`
- * in the reconciler can catch and not a warning a diagnostics gate can count.
+ * which is `g_error()`: SIGABRT, exit 134, a core dump. Not an exception a `try` in
+ * the reconciler can catch and not a warning a diagnostics gate can count.
  * `adw_dialog_root()` raises it from the ROOT vfunc, which is why a DETACHED box
- * accepts the very same append in silence at exit 0 — re-testing this on a bare
- * box "disproves" it and puts the append back.
+ * accepts the very same append in silence at exit 0 — re-testing this on a bare box
+ * "disproves" it and puts the append back.
  *
- * THE ABORT IS THE LOUD HALF OF A CLASS, and its quiet half arrives through the
- * same door (ADR 0054). MEASURED on the same libraries, one process per case:
+ * THE ABORT IS THE LOUD HALF OF A CLASS, and its quiet half arrives through the same
+ * door (ADR 0054). MEASURED on the same libraries, one process per case:
  * `box.append(new Gtk.Window())` with the box rooted is **exit 0, silent**, and
  * afterwards `win.get_parent()` is the box while `win.get_root()` is the window
  * ITSELF — a `GtkRoot` with a parent, which is a contradiction GTK states nowhere.
- * Presenting that window then draws it as a toplevel AND leaves it in the box's
- * child list, so the container measures and allocates a window. One node kind
- * aborts, its neighbour says nothing; both are the same question answered wrong,
- * so both are answered here.
+ * Presenting that window then draws it as a toplevel AND leaves it in the box's child
+ * list, so the container measures and allocates a window. One node kind aborts, its
+ * neighbour says nothing; both are the same question answered wrong, so both are
+ * answered here.
  *
  * So the descriptor declares the axis, and `policies.ts` is the only reader.
- * `parented` is every other widget and is what an ABSENT `placement` means; the
- * union still cannot be forgotten because there is exactly one normaliser
- * (`placementOf`) and every switch over it ends in `unhandledPlacement`.
+ * `parented` is every other widget and is what an ABSENT `placement` means; the union
+ * still cannot be forgotten because there is exactly one normaliser (`placementOf`)
+ * and every switch over it ends in `unhandledPlacement`.
  */
 export type NodePlacement = 
 /**
@@ -152,19 +146,17 @@ export type NodePlacement =
  * Three measurements shape the two method names, all on libadwaita 1.9.3:
  *
  *  - `present` TAKES THE PARENT WIDGET (`adw_dialog_present` arity 1, against
- *    `gtk_window_present`'s 0). That is what makes this a portal rather than a
- *    toplevel: the node has a place in the shadow tree and a different place in
- *    the GTK tree, and the parent is what joins them.
- *  - `close` IS THE UNCONDITIONAL ONE, `force_close` and not `close`. An
- *    unmount is not a user request: with `can-close: false` (which is how
- *    `onRequestClose` is honoured one layer up) `adw_dialog_close()` returns
- *    FALSE, emits `close-attempt` and LEAVES THE DIALOG ON SCREEN — measured.
- *    `force_close()` closes it and emits `closed`.
- *  - AND `force_close` IS SAFE ON A NODE THAT WAS NEVER PRESENTED, where
- *    `close` is not: measured, `close()` on an unpresented dialog answers
- *    `Adwaita-CRITICAL **: Trying to close AdwDialog 0x… that's not presented`
- *    at exit 0, and `force_close()` is silent. So the host needs no
- *    "is it up?" probe before retracting one.
+ *    `gtk_window_present`'s 0). That is what makes this a portal rather than a toplevel:
+ *    the node has a place in the shadow tree and a different place in the GTK tree, and
+ *    the parent is what joins them.
+ *  - `close` IS THE UNCONDITIONAL ONE, `force_close` and not `close`. An unmount is not
+ *    a user request: with `can-close: false` (how `onRequestClose` is honoured one layer
+ *    up) `adw_dialog_close()` returns FALSE, emits `close-attempt` and LEAVES THE DIALOG
+ *    ON SCREEN — measured. `force_close()` closes it and emits `closed`.
+ *  - `force_close` IS SAFE ON A NODE THAT WAS NEVER PRESENTED, where `close` is not:
+ *    measured, `close()` on an unpresented dialog answers `Adwaita-CRITICAL **: Trying to
+ *    close AdwDialog 0x… that's not presented` at exit 0, and `force_close()` is silent.
+ *    So the host needs no "is it up?" probe before retracting one.
  */
  | {
     readonly kind: 'portal';
@@ -174,34 +166,33 @@ export type NodePlacement =
 /**
  * The node IS a root: `present()` / `destroy()`, and no parent anywhere.
  *
- * WHAT SEPARATES IT FROM A PORTAL IS THE ARITY, and that is a fact about the
- * two libraries rather than a convention: measured, `adw_dialog_present` takes
- * 1 argument and `gtk_window_present` takes 0. A portal has two positions in
- * the tree and the parent is what joins them; a toplevel has ONE, its own, so
- * there is nothing to present it against. `descriptorProblems()` holds both
- * arities, so the two arms cannot be swapped by a copy/paste.
+ * WHAT SEPARATES IT FROM A PORTAL IS THE ARITY, and that is a fact about the two
+ * libraries rather than a convention: measured, `adw_dialog_present` takes 1 argument
+ * and `gtk_window_present` takes 0. A portal has two positions in the tree and the
+ * parent is what joins them; a toplevel has ONE, its own, so there is nothing to
+ * present it against. `descriptorProblems()` holds both arities, so the two arms
+ * cannot be swapped by a copy/paste.
  *
- * MEMBERSHIP IS `Gtk.Root`, measured with `GObject.type_is_a` and not read
- * from documentation — `GtkWindow` and `AdwApplicationWindow` down to
- * `GtkPrintUnixDialog`. It is GTK's own word for "this widget is a toplevel",
- * which is why the generic code asks it instead of forming a second opinion,
- * and `placement.spec.ts` is where the membership is walked and counted.
+ * MEMBERSHIP IS `Gtk.Root`, measured with `GObject.type_is_a` and not read from
+ * documentation — `GtkWindow` and `AdwApplicationWindow` down to
+ * `GtkPrintUnixDialog`. It is GTK's own word for "this widget is a toplevel", which
+ * is why the generic code asks it instead of forming a second opinion, and
+ * `placement.spec.ts` walks and counts the membership.
  *
- * `close: 'destroy'` IS THE FORCED ONE, the same choice the portal arm makes
- * and for the same measured reason. On GTK 4.22.4: `gtk_window_close()` emits
- * `close-request`, and a handler returning TRUE leaves the window mapped and
- * visible — which is exactly how an application vetoes a user's close. An
- * unmount is not a user request, so the conditional call is the wrong one;
- * `gtk_window_destroy()` takes it down regardless. Both are silent on a window
- * that was never presented (measured), so the host needs no "is it up?" probe.
+ * `close: 'destroy'` IS THE FORCED ONE, the same choice the portal arm makes and for
+ * the same measured reason. On GTK 4.22.4: `gtk_window_close()` emits `close-request`,
+ * and a handler returning TRUE leaves the window mapped and visible — exactly how an
+ * application vetoes a user's close. An unmount is not a user request, so the
+ * conditional call is the wrong one; `gtk_window_destroy()` takes it down regardless.
+ * Both are silent on a window that was never presented (measured), so the host needs
+ * no "is it up?" probe.
  *
- * AND THE FORCED CALL IS TERMINAL HERE, which is where this arm stops being a
- * copy of the portal one. MEASURED: `present()` after either `close()` or
- * `destroy()` answers `Gtk-WARNING **: A window is shown after it has been
- * destroyed. This will leave the window in an inconsistent state.` — GTK4's
- * default `close-request` handler destroys the window, so `close()` is a
- * conditional destroy rather than a hide. A retracted toplevel is therefore
- * gone for good, and a re-mount is a fresh widget (which is what `rebuild`
+ * AND THE FORCED CALL IS TERMINAL HERE, which is where this arm stops being a copy of
+ * the portal one. MEASURED: `present()` after either `close()` or `destroy()` answers
+ * `Gtk-WARNING **: A window is shown after it has been destroyed. This will leave the
+ * window in an inconsistent state.` — GTK4's default `close-request` handler destroys
+ * the window, so `close()` is a conditional destroy rather than a hide. A retracted
+ * toplevel is gone for good, and a re-mount is a fresh widget (which is what `rebuild`
  * already does for a construct-only write).
  */
  | {
@@ -426,6 +417,20 @@ export type ChildPolicy = {
 export interface GeneratedWidget {
     readonly gtype: string;
     readonly tag: string;
+    /**
+     * Availability-CONDITIONAL, and the declared type deliberately does not say so.
+     *
+     * A row comes from one platform's GIR, so on a platform whose GTK does not
+     * build the class this reads `Gtk.PrintUnixDialog` and gets `undefined` —
+     * the whole of GTK's Unix print stack is compiled out on win32 (#1446).
+     * Widening the signature to `| undefined` would force every `ctor()` reader
+     * to handle the absence, and they all handle it through ONE predicate
+     * instead (`classOf`/`requireClass`, `registry.ts`); annotating the signature
+     * as well would be a second statement of the same fact that nothing checks.
+     * The gap this leaves is real and deliberate: a reader that bypasses both
+     * gets `undefined` where the type promised a class — which is why every
+     * call site refuses rather than dereferences.
+     */
     readonly ctor: () => GObject.ObjectClass & (new (props?: Record<string, unknown>) => GObject.Object);
 }
 export interface WidgetDescriptor {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/gtk-host",
-    "version": "0.52.0",
+    "version": "0.54.0",
     "description": "Framework-agnostic GTK4/Adwaita host: the element model UI-framework renderers bind to",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -75,8 +75,8 @@
         "build:gjsify": "gjsify build --library 'src/**/*.{ts,js}' --exclude 'src/**/*.spec.{mts,ts}' 'src/test.{mts,ts}'",
         "build:types": "gjsify tsc",
         "build:test": "gjsify run build:test:gjs",
-        "build:test:node": "gjsify build src/test.mts --app node --outfile dist/test.node.mjs --define __VUE_OPTIONS_API__=false --define __VUE_PROD_DEVTOOLS__=false --define __VUE_PROD_HYDRATION_MISMATCH_DETAILS__=false --define \"process.env.NODE_ENV='production'\" --exclude-globals navigator",
-        "build:test:gjs": "gjsify build src/test.mts --app gjs --outfile test.gjs.mjs --define __VUE_OPTIONS_API__=false --define __VUE_PROD_DEVTOOLS__=false --define __VUE_PROD_HYDRATION_MISMATCH_DETAILS__=false --define \"process.env.NODE_ENV='production'\" --exclude-globals navigator",
+        "build:test:node": "gjsify build src/test.mts --app node --outfile dist/test.node.mjs --define __VUE_OPTIONS_API__=false --define __VUE_PROD_DEVTOOLS__=false --define __VUE_PROD_HYDRATION_MISMATCH_DETAILS__=false --define \"process.env.NODE_ENV='production'\"",
+        "build:test:gjs": "gjsify build src/test.mts --app gjs --outfile test.gjs.mjs --define __VUE_OPTIONS_API__=false --define __VUE_PROD_DEVTOOLS__=false --define __VUE_PROD_HYDRATION_MISMATCH_DETAILS__=false --define \"process.env.NODE_ENV='production'\"",
         "test": "gjsify run build:gjsify && gjsify run build:test && gjsify run test:gjs",
         "test:gjs": "gjsify run test.gjs.mjs",
         "test:gjs-on-node": "gjsify run build:gjsify && gjsify run build:test:node && node dist/test.node.mjs",
@@ -102,7 +102,8 @@
         "@girs/gtk-4.0": "5.4.0",
         "@girs/pango-1.0": "5.4.0",
         "@girs/pangocairo-1.0": "5.4.0",
-        "@gjsify/adwaita-core": "^0.52.0"
+        "@gjsify/adwaita-core": "^0.54.0",
+        "@gjsify/utils": "^0.54.0"
     },
     "peerDependencies": {
         "@vue/runtime-core": "^3.5.0",
@@ -125,10 +126,10 @@
         }
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.52.0",
+        "@gjsify/cli": "^0.54.0",
         "@vue/runtime-core": "^3.5.0",
         "solid-js": "^1.9.0",
-        "@gjsify/unit": "^0.52.0",
+        "@gjsify/unit": "^0.54.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3",
         "@gjsify/node-gi": "file:../../node-gi/node-gi",