@gjsify/gtk-host 0.47.0 → 0.49.0

package/lib/types/types.d.ts

@@ -74,8 +74,131 @@ export interface HostElement extends HostNodeBase {
      * 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.
+     */
+    portalWatch: {
+        widget: Gtk.Widget;
+        id: number;
+    } | null;
 }
 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
+ *
+ *     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.
+ * `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.
+ *
+ * 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.
+ *
+ * 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`.
+ */
+export type NodePlacement = 
+/**
+ * The parent's `ChildPolicy` places it — every widget but the two families below.
+ *
+ * DECLARING it is not the same as leaving it out, and the difference is an
+ * escape hatch rather than a nicety: the host refuses a node whose CLASS says
+ * it cannot be parented (`unparentableChild`), and that refusal fires only
+ * where the descriptor is SILENT. A consumer whose own widget trips the
+ * structural oracle — a `present(parent)` method on a widget that really is a
+ * child — writes this arm and is placed by its parent again.
+ */
+{
+    readonly kind: 'parented';
+}
+/**
+ * The node places ITSELF against its parent: `present(parent)` / `close()`.
+ *
+ * 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.
+ */
+ | {
+    readonly kind: 'portal';
+    readonly present: string;
+    readonly close: string;
+}
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * `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.
+ *
+ * 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`
+ * already does for a construct-only write).
+ */
+ | {
+    readonly kind: 'toplevel';
+    readonly present: string;
+    readonly close: string;
+};
 export type PolicyKind = 'none' | 'single' | 'ordered' | 'indexed' | 'slotted' | 'keyed' | 'coords';
 /**
  * How a parent adopts children. GTK4 deleted `GtkContainer`, so there is no
@@ -110,12 +233,52 @@ export type ChildPolicy = {
     remove: string;
     reorder: 'native' | 'remove-all';
 }
-/** `Gtk.ListBox`/`Gtk.FlowBox`: index-addressed, and the parent addresses a WRAPPER row. */
+/**
+ * `Gtk.ListBox`/`Gtk.FlowBox`: index-addressed, and the parent addresses a WRAPPER row.
+ *
+ * `perLineCap` names a property the host keeps EQUAL TO THE CHILD COUNT, and
+ * `Gtk.FlowBox:max-children-per-line` is the only one. It is a cap, so every
+ * value at or above the child count lays the children out identically — and
+ * that equivalence is exactly what hid the cost, because GTK MEASURES THE CAP
+ * RATHER THAN THE CHILDREN.
+ *
+ * MEASURED on GTK 4.22.4, one `Gtk.FlowBox` holding TWO children, per
+ * HEIGHT-FOR-WIDTH measure — `measure(VERTICAL, 400)`, which is the one a
+ * container in a window asks for:
+ *
+ * | cap | 7 | 64 | 1024 | 8192 | 32768 | 65535 |
+ * | --- | --- | --- | --- | --- | --- | --- |
+ * | ms | 0.021 | 0.025 | 0.43 | 18.6 | 391.5 | 1393.2 |
+ *
+ * Quadratic in the cap, so "as many as fit" spelled as G_MAXUINT cost a second
+ * and a half to measure two chips, and a real application froze its main loop
+ * for 12.7 s at startup over five two-child rows. The ORIENTATION is part of
+ * the claim and not a detail: `measure(HORIZONTAL, -1)` stays under 0.1 ms at
+ * every one of those caps, so a re-measurement that asks for the width alone
+ * reproduces none of this.
+ *
+ * The cap is wrong in the ANSWER too, not only in what the answer costs.
+ * Natural width is `content + column-spacing × (cap - 1)` — measured, exactly,
+ * over five caps — so a cap above the child count `n` carries
+ * `column-spacing × (cap - n)` px of gaps that do not exist. 12 children at
+ * `column-spacing: 8`: 683 px natural at a cap of 12 and 524 867 px at 65535,
+ * the excess exactly 8 × 65 523. At `column-spacing: 0` there is no difference
+ * at all, which is how a pinned cap passed for as long as it did.
+ *
+ * The child count is the exact answer rather than a smaller cap chosen to be
+ * safe: a line can never hold more children than exist, so it forbids nothing
+ * G_MAXUINT allowed, and it is the largest value that costs nothing.
+ *
+ * An AUTHORED value wins. `<GtkFlowBox maxChildrenPerLine={3}>` is someone
+ * asking for three per line, and a sync that overwrote it would be the same
+ * silent kind of wrong this field exists to remove.
+ */
  | {
     kind: 'indexed';
     insert: string;
     remove: string;
     wrap: 'list-box-row' | 'flow-box-child' | null;
+    perLineCap?: string;
 }
 /**
  * `Adw.HeaderBar`, `Adw.ToolbarView`, `Adw.ActionRow`: named attachment points.
@@ -261,6 +424,19 @@ export interface WidgetDescriptor {
     /** Lazy so `gi://` loads late and an unused descriptor costs nothing. */
     readonly ctor: () => GObject.ObjectClass & (new (props?: Record<string, unknown>) => GObject.Object);
     readonly children: ChildPolicy;
+    /**
+     * How this node reaches the screen. Absent means `{ kind: 'parented' }`.
+     *
+     * Optional rather than required, and the reason is the shape of the table
+     * rather than convenience: the generated half is the whole GIR widget set and
+     * not one row of it is a portal, so a required field would be ~900 identical
+     * lines. Nothing is left implicit by that — `placementOf()` normalises the
+     * absence in ONE place and every switch over the result has a `never` arm, so
+     * a third placement kind cannot be added without every reader failing to
+     * compile. `descriptorProblems()` holds the declared methods against the
+     * installed class, exactly as it does for `children`.
+     */
+    readonly placement?: NodePlacement;
     /**
      * Where a text child goes. Absent means text under this widget is an ERROR
      * that names the tag — never a silent drop.

package/lib/types/vue-components.d.ts

@@ -33,11 +33,11 @@
  * resolve goes unchecked.
  */
 import type { DefineComponent } from '@vue/runtime-core';
-import type { VueAttributes, WithOnce } from './attrs.js';
+import type { VueAttributes, WithOnce, WithPortableValues } from './attrs.js';
 import type { WidgetPropsByGType, WidgetPropsVueAliases } from './generated/props.js';
 type VueWidgetProps = WidgetPropsByGType & WidgetPropsVueAliases;
 export type GtkGlobalComponents = {
-    [K in keyof VueWidgetProps]: DefineComponent<WithOnce<VueWidgetProps[K]> & VueAttributes>;
+    [K in keyof VueWidgetProps]: DefineComponent<WithOnce<WithPortableValues<VueWidgetProps[K]>> & VueAttributes>;
 };
 declare module '@vue/runtime-core' {
     interface GlobalComponents extends GtkGlobalComponents {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/gtk-host",
-    "version": "0.47.0",
+    "version": "0.49.0",
     "description": "Framework-agnostic GTK4/Adwaita host: the element model UI-framework renderers bind to",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -80,7 +80,9 @@
         "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",
-        "generate": "gjsify build src/generator/main.mts --app gjs --outfile tmp/generate.gjs.mjs && gjsify run tmp/generate.gjs.mjs -- --out src/generated && gjsify format src/generated"
+        "generate": "gjsify build src/generator/main.mts --app gjs --outfile tmp/generate.gjs.mjs && gjsify run tmp/generate.gjs.mjs -- --out src/generated && gjsify format src/generated",
+        "generate:enum-values": "gjs -m ../../../scripts/generate-enum-values.mjs",
+        "generate:methods": "gjs -m ../../../scripts/generate-widget-methods.mjs"
     },
     "keywords": [
         "gjs",
@@ -98,7 +100,8 @@
         "@girs/gobject-2.0": "4.6.0",
         "@girs/gtk-4.0": "4.6.0",
         "@girs/pango-1.0": "4.6.0",
-        "@girs/pangocairo-1.0": "4.6.0"
+        "@girs/pangocairo-1.0": "4.6.0",
+        "@gjsify/adwaita-core": "^0.49.0"
     },
     "peerDependencies": {
         "@vue/runtime-core": "^3.5.0",
@@ -121,10 +124,10 @@
         }
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.47.0",
+        "@gjsify/cli": "^0.49.0",
         "@vue/runtime-core": "^3.5.0",
         "solid-js": "^1.9.0",
-        "@gjsify/unit": "^0.47.0",
+        "@gjsify/unit": "^0.49.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3",
         "@gjsify/node-gi": "file:../../node-gi/node-gi",