@gjsify/gtk-host 0.41.0

package/README.md

@@ -0,0 +1,140 @@
+# @gjsify/gtk-host
+
+The element model UI-framework renderers bind to, for GTK4 and libadwaita.
+
+Vue, React, Solid and Angular each publish a contract for rendering into
+something that is not the DOM. What none of them provides is the *something*:
+an object model that can create a widget, set a property, adopt a child, and
+navigate the result. That is this package.
+
+```ts
+import type Adw from '@girs/adw-1';
+import { createElement, insert, materialize, registerBuiltinWidgets } from '@gjsify/gtk-host';
+
+registerBuiltinWidgets();
+
+const window = createElement('AdwApplicationWindow', { title: 'Hello' });
+const box    = createElement('GtkBox', { orientation: 'vertical', spacing: 12 });
+const button = createElement('GtkButton', { label: 'Press me' });
+
+insert(box, window);
+insert(button, box);
+(materialize(window) as Adw.ApplicationWindow).present();
+```
+
+## Why a shared host
+
+NativeScript carries five framework flavours over one host, and the adapters are
+small because the host exists: its Solid adapter is **91 lines**, its React
+adapter **505** — and both hold *zero* lines of widget knowledge. Under GTK4 the
+shared share is larger still: GTK4 deleted `GtkContainer`, so there is no generic
+`add`, and `Gtk.Buildable.add_child` is introspected as a vfunc only. Every
+container's adoption rule has to be written down somewhere. Written once, it is a
+table; written per adapter, it is the same table three times — which is what
+stalled `react-gtk`, `react-native-gtk4` and `svelte-gjs`.
+
+See [ADR 0027](../../../docs/adr/0027-gtk-host-layer.md) and
+[ADR 0028](../../../docs/adr/0028-widget-table-provenance.md).
+
+## What it refuses to do quietly
+
+GTK's failure mode is exit 0, so this host is loud on purpose. Measured on
+gjs 1.88.1:
+
+| What you write | What GObject does | What this host does |
+|---|---|---|
+| `orientation: 'vertical'` | keeps `HORIZONTAL`; `set_property` logs `GLib-GObject-CRITICAL`, the JS setter says nothing at all | resolves the nick against the enum's GType |
+| `orientation: 'sideways'` | same silence | throws, naming `GtkOrientation` |
+| a read-only property | accepts the write, stores nothing | throws, naming the property |
+| a misspelled property | nothing | throws, naming the widget |
+| text inside `<GtkImage>` | nothing | throws, naming the tag and the fix |
+| a child under a childless widget | `Gtk-WARNING` at exit 0 | throws, naming the three fixes |
+| `selectable: 'false'` (a string) | JS truthiness makes it TRUE | honours `'true'`/`'false'`, throws on any other string |
+| a string for a flags property | dropped silently | throws, naming the flags GType and asking for the numeric value |
+
+## The node tree
+
+Three node kinds — `element`, `text`, `anchor` — linked by the host's own
+`parent`/`first`/`next`, never by `Gtk.Widget.get_parent()`. Text and anchors own
+no widget, so GTK cannot answer navigation questions about them.
+
+**Anchors never enter the GTK tree.** Vue's `createComment` and every
+`v-if`/`<Show>` boundary becomes one, and insertion resolves forward past it to
+the next node that owns a widget. An empty branch therefore cannot shift a
+sibling's index.
+
+**An element is `attached` only once GTK has taken it.** Owning a widget is not
+the same fact: every framework materialises a subtree bottom-up, long before
+inserting it. Placement reads `attached`, never `widget !== null` — deriving it
+from the widget made the `remove-all` policy detach non-children and re-add
+already-parented ones, at exit 0.
+
+**Text has no node in GTK.** It goes to the owning widget's declared `textSink`
+(`Gtk.Label:label`, `Gtk.Entry:text`, …). A widget without one rejects text by name.
+
+## Child placement
+
+Seven policy kinds, declared per widget as data and dispatched on the policy's
+own `kind`. Descriptor lookup is by exact GType name; `mountRoot` is the one path
+that walks the type hierarchy (`GObject.type_is_a`, via `nearestRegistered`), so
+an application's own subclass resolves to its ancestor's rules:
+
+| kind | example | how a child lands |
+|---|---|---|
+| `single` | `AdwBin`, `GtkWindow` | `set_child` / `set_content` |
+| `ordered` | `GtkBox` | `append` + `insert_child_after` |
+| `indexed` | `GtkListBox` | `insert(row, i)` — the parent addresses a **wrapper** row |
+| `slotted` | `AdwHeaderBar` | `pack_start` / `pack_end` / `set_title_widget`, chosen by the child's `slot` |
+| `keyed` | `GtkStack` | `add_titled(child, name, title)` |
+| `coords` | `GtkGrid` | `attach(child, column, row, …)` |
+| `none` | `GtkLabel` | rejected, with the three fixes named |
+
+A container that cannot reorder in place declares it. `Adw.PreferencesGroup` has
+`add` and `remove` and no `insert` — measured — so it declares
+`reorder: 'remove-all'` and pays a tail re-append. The degradation is in the
+table, not a surprise in an app. The re-append is ordered so a refusal costs
+nothing: the new child is appended FIRST, then the tail is rotated — detaching the
+tail first and failing on the append took already-rendered siblings with it.
+
+Its sibling `Adw.PreferencesPage` looks identical and is not: `insert(group, i)`
+exists there, so it uses `indexed` and reorders natively. Near-identical APIs with
+opposite capabilities are exactly why the table is measured per widget rather than
+inherited.
+
+`slot` and `layout` are props the CHILD declares: `slot="end"` picks a `slotted`
+attachment point, `layout={{ column, row, columnSpan, rowSpan }}` a `coords` cell,
+`layout={{ name, title }}` a `keyed` page. Both are read at placement time, so
+changing either RE-PLACES the child rather than doing nothing.
+
+## Lifetime
+
+`remove` detaches and is reversible, because frameworks move nodes. The wrapper
+row an `indexed` parent demanded is handed back at the same time — it belongs to
+that parent, and dragging a `GtkListBoxRow` into the next one would carry the
+still-parented widget with it — so a re-insert gets a fresh row. Author your own
+`<GtkListBoxRow>` when the row itself holds state. `destroy`
+tears a subtree down: it disconnects every handler, unparents, drops the
+reference, and closes a toplevel window (the one node unparenting cannot reach —
+it has no parent and its `GtkApplication` still holds it). It is recursive, it is
+eager, and it is the only place a handler is disconnected for good — a rebuild
+disconnects and re-binds, a re-render replaces. GJS blocks JS callbacks during GC,
+so **whatever is not disconnected here stays connected for the life of the
+process**.
+
+Construct-only properties cannot be patched; GObject accepts the write and keeps
+the old value. Changing one **rebuilds** the widget in place, preserving position,
+properties and listeners.
+
+## Conformance
+
+`@gjsify/gtk-host/conformance` exports the checks that keep the table honest and
+the readers every vector asserts through:
+
+- `descriptorProblems()` — every method and text sink a descriptor names must
+  exist on that GType in the *installed* GTK.
+- `gtkChildren()` / `gtkChildTypes()` / `dumpTree()` — read the **real** widget
+  tree. A renderer that asserts against its own bookkeeping agrees with itself
+  while the window is wrong.
+
+Adapters will run the same vectors, so "it works in Vue" and "it works in Solid"
+will mean the same thing. None is written yet — see `status/open-todos.md`.

package/lib/esm/_virtual/_rolldown/runtime.js

@@ -0,0 +1 @@
+var e=Object.defineProperty,__name=(t,n)=>e(t,`name`,{value:n,configurable:!0});export{__name};

package/lib/esm/conformance/diagnostics.js

@@ -0,0 +1,2 @@
+import"../_virtual/_rolldown/runtime.js";import e from"gi://GLib";let t=null;function installDiagnosticsGate(){if(t)return t;let n=[],r=new TextDecoder,i=e.getenv(`G_MESSAGES_DEBUG`)!==null;return e.log_set_writer_func((t,a)=>{try{let o=a?.MESSAGE,s=o instanceof Uint8Array?r.decode(o):String(o??``),c=t&e.LogLevelFlags.LEVEL_MASK;c<=e.LogLevelFlags.LEVEL_WARNING&&n.push(s),(i||c<=e.LogLevelFlags.LEVEL_MESSAGE)&&printerr(s)}catch{printerr(`<gtk-host: a log message could not be decoded>`)}return e.LogWriterOutput.HANDLED}),t={seen:n,reset(){n.length=0},assertQuiet(e){if(n.length===0)return;let t=n.length,r=n.join(`
+  `);throw n.length=0,Error(`${e?e+`: `:``}GTK reported ${t} diagnostic(s) that would have passed at exit 0:\n  ${r}`)}},t}export{installDiagnosticsGate};

package/lib/esm/conformance/index.js

@@ -0,0 +1,2 @@
+import"../_virtual/_rolldown/runtime.js";import{installDiagnosticsGate as e}from"./diagnostics.js";import{BUILTIN_DESCRIPTORS as t}from"../descriptors/index.js";import{addressOf as n}from"../policies.js";import r from"gi://GObject";function methodsOf(e){switch(e.kind){case`none`:return[];case`single`:return[e.set];case`ordered`:return e.after?[e.append,e.after,e.remove]:[e.append,e.remove];case`indexed`:return[e.insert,e.remove];case`slotted`:return[...Object.values(e.slots),e.remove];case`keyed`:return[e.add,e.remove];case`coords`:return[e.attach,e.remove]}}function descriptorProblems(e=t){let n=[];for(let t of e){let e;try{e=t.ctor()}catch(e){n.push({gtype:t.gtype,problem:`ctor() threw: ${e.message}`});continue}let i=r.type_name(e.$gtype);i!==t.gtype&&n.push({gtype:t.gtype,problem:`ctor() is ${i}, not ${t.gtype}`});for(let r of methodsOf(t.children))typeof e.prototype[r]!=`function`&&n.push({gtype:t.gtype,problem:`declares children.${r}(), which ${i} does not have`});if(t.textSink){let a=e.list_properties().find(e=>e.get_name()===t.textSink);a?(a.flags&r.ParamFlags.WRITABLE)===0?n.push({gtype:t.gtype,problem:`declares a READ-ONLY textSink "${t.textSink}"`}):r.type_is_a(a.value_type,r.TYPE_STRING)||n.push({gtype:t.gtype,problem:`declares textSink "${t.textSink}", which is ${r.type_name(a.value_type)}, not a string`}):n.push({gtype:t.gtype,problem:`declares textSink "${t.textSink}", which ${i} does not have`})}n.push(...policyProblems(t,e,i))}return n}function policyProblems(e,t,n){let r=[],i=t.prototype,a=e.children,requireGetter=(t,a)=>{let o=t.replace(/^set_/,`get_`);typeof i[o]!=`function`&&r.push({gtype:e.gtype,problem:`${a} uses ${t}() but ${n} has no ${o}(), so removal cannot check whether this child is still the one in place`})};if(a.kind===`single`&&requireGetter(a.set,`children.set`),a.kind===`slotted`){for(let[e,t]of Object.entries(a.slots))t.startsWith(`set_`)&&requireGetter(t,`slot "${e}"`);a.defaultSlot in a.slots||r.push({gtype:e.gtype,problem:`defaultSlot "${a.defaultSlot}" is not one of ${Object.keys(a.slots).join(`, `)}`})}if(a.kind===`ordered`&&a.reorder===`native`&&!a.after&&r.push({gtype:e.gtype,problem:`claims reorder: 'native' with no "after" method — reorderMode() would tell an adapter the wrong thing`}),a.kind===`keyed`){let t=i[a.add],o=a.titled?3:1;typeof t==`function`&&t.length!==o&&r.push({gtype:e.gtype,problem:`titled: ${a.titled} implies ${a.add}() takes ${o} argument(s), but ${n}'s takes ${t.length}`})}return r}function gtkChildren(e){let t=[],n=e;if(typeof n.get_first_child!=`function`)return t;for(let e=n.get_first_child();e;e=e.get_next_sibling())t.push(e);return t}const gtkChildTypes=e=>gtkChildren(e).map(e=>r.type_name(e.constructor.$gtype));function addressesOf(e){let t=[];for(let r=e.first;r;r=r.next)r.kind===`element`&&r.widget&&t.push(n(r));return t}function dumpTree(e,t=0){let n=r.type_name(e.constructor.$gtype),i=[`${`  `.repeat(t)}${n}`];for(let n of gtkChildren(e))i.push(dumpTree(n,t+1));return i.join(`
+`)}export{addressesOf,descriptorProblems,dumpTree,gtkChildTypes,gtkChildren,e as installDiagnosticsGate,methodsOf};

package/lib/esm/descriptors/adw.js

@@ -0,0 +1 @@
+import"../_virtual/_rolldown/runtime.js";import e from"gi://Adw?version=1";const t=[{gtype:`AdwApplicationWindow`,ctor:()=>e.ApplicationWindow,children:{kind:`single`,set:`set_content`}},{gtype:`AdwWindow`,ctor:()=>e.Window,children:{kind:`single`,set:`set_content`}},{gtype:`AdwBin`,ctor:()=>e.Bin,children:{kind:`single`,set:`set_child`}},{gtype:`AdwToolbarView`,ctor:()=>e.ToolbarView,children:{kind:`slotted`,slots:{top:`add_top_bar`,bottom:`add_bottom_bar`,content:`set_content`},defaultSlot:`content`,remove:`remove`}},{gtype:`AdwHeaderBar`,ctor:()=>e.HeaderBar,children:{kind:`slotted`,slots:{start:`pack_start`,end:`pack_end`,title:`set_title_widget`},defaultSlot:`start`,remove:`remove`}},{gtype:`AdwPreferencesGroup`,ctor:()=>e.PreferencesGroup,children:{kind:`ordered`,append:`add`,remove:`remove`,reorder:`remove-all`}},{gtype:`AdwPreferencesPage`,ctor:()=>e.PreferencesPage,children:{kind:`indexed`,insert:`insert`,remove:`remove`,wrap:null}},{gtype:`AdwActionRow`,ctor:()=>e.ActionRow,children:{kind:`slotted`,slots:{prefix:`add_prefix`,suffix:`add_suffix`},defaultSlot:`suffix`,remove:`remove`}},{gtype:`AdwStatusPage`,ctor:()=>e.StatusPage,children:{kind:`single`,set:`set_child`}}];export{t as ADW_DESCRIPTORS};

package/lib/esm/descriptors/gtk.js

@@ -0,0 +1 @@
+import"../_virtual/_rolldown/runtime.js";import e from"gi://Gtk?version=4.0";const t=[{gtype:`GtkBox`,ctor:()=>e.Box,children:{kind:`ordered`,append:`append`,after:`insert_child_after`,remove:`remove`,reorder:`native`}},{gtype:`GtkWindow`,ctor:()=>e.Window,children:{kind:`single`,set:`set_child`}},{gtype:`GtkApplicationWindow`,ctor:()=>e.ApplicationWindow,children:{kind:`single`,set:`set_child`}},{gtype:`GtkScrolledWindow`,ctor:()=>e.ScrolledWindow,children:{kind:`single`,set:`set_child`}},{gtype:`GtkFrame`,ctor:()=>e.Frame,children:{kind:`single`,set:`set_child`}},{gtype:`GtkLabel`,ctor:()=>e.Label,children:{kind:`none`},textSink:`label`},{gtype:`GtkButton`,ctor:()=>e.Button,children:{kind:`single`,set:`set_child`},textSink:`label`},{gtype:`GtkToggleButton`,ctor:()=>e.ToggleButton,children:{kind:`single`,set:`set_child`},textSink:`label`},{gtype:`GtkImage`,ctor:()=>e.Image,children:{kind:`none`}},{gtype:`GtkSwitch`,ctor:()=>e.Switch,children:{kind:`none`}},{gtype:`GtkEntry`,ctor:()=>e.Entry,children:{kind:`none`},textSink:`text`},{gtype:`GtkListBox`,ctor:()=>e.ListBox,children:{kind:`indexed`,insert:`insert`,remove:`remove`,wrap:`list-box-row`}},{gtype:`GtkFlowBox`,ctor:()=>e.FlowBox,children:{kind:`indexed`,insert:`insert`,remove:`remove`,wrap:`flow-box-child`}},{gtype:`GtkListBoxRow`,ctor:()=>e.ListBoxRow,children:{kind:`single`,set:`set_child`}},{gtype:`GtkStack`,ctor:()=>e.Stack,children:{kind:`keyed`,add:`add_titled`,remove:`remove`,nameFrom:`name`,titled:!0}},{gtype:`GtkGrid`,ctor:()=>e.Grid,children:{kind:`coords`,attach:`attach`,remove:`remove`}},{gtype:`GtkHeaderBar`,ctor:()=>e.HeaderBar,children:{kind:`slotted`,slots:{start:`pack_start`,end:`pack_end`,title:`set_title_widget`},defaultSlot:`start`,remove:`remove`}}];export{t as GTK_DESCRIPTORS};

package/lib/esm/descriptors/index.js

@@ -0,0 +1 @@
+import"../_virtual/_rolldown/runtime.js";import{registerWidgets as e}from"../registry.js";import{ADW_DESCRIPTORS as t}from"./adw.js";import{GTK_DESCRIPTORS as n}from"./gtk.js";const r=[...n,...t];function registerBuiltinWidgets(){e(r)}export{t as ADW_DESCRIPTORS,r as BUILTIN_DESCRIPTORS,n as GTK_DESCRIPTORS,registerBuiltinWidgets};

package/lib/esm/errors.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";var GtkHostError=class extends Error{constructor(e,t){super(t),this.code=e,this.name=`GtkHostError`}};const e={unknownTag:e=>new GtkHostError(`unknown-tag`,`No descriptor registered for <${e}>. Register one with registerWidget({ gtype: '${e}', … }) or use a raw GType tag that is present in the installed typelib.`),unknownProp:(e,t)=>new GtkHostError(`unknown-prop`,`<${e}> has no property "${t}". Check the spelling against the installed GTK (camelCase and kebab-case both resolve), or bind it as a signal with on${t[0]?.toUpperCase()}${t.slice(1)}.`),readOnlyProp:(e,t)=>new GtkHostError(`read-only-prop`,`<${e}>.${t} is read-only in the installed GTK. Writing it is a silent no-op in GObject, so this host refuses it instead of dropping the value.`),badEnum:(e,t,n,r)=>new GtkHostError(`bad-enum`,`<${e}>.${t} expects ${r}, and "${n}" is not one of its values. Note that GObject accepts the wrong string SILENTLY — the property would have kept its old value.`),unknownSignal:(e,t,n)=>new GtkHostError(`unknown-signal`,`<${e}> emits no signal "${n}" (bound as ${t}). Check the spelling against the installed GTK, or use the escape hatch on:<raw-signal-name> if the name is irregular.`),signalTaken:(e,t,n,r)=>new GtkHostError(`signal-taken`,`<${e}> already binds "${r}" through ${n}, so ${t} would silently replace it — GObject has one handler per connect, and this host keeps one per signal name. Use one spelling, or combine the two callbacks yourself.`),badString:(e,t,n)=>new GtkHostError(`bad-string`,`<${e}>.${t} is a string property and got a ${n}. Numbers and booleans are stringified; anything else has no unambiguous spelling, and GObject would have thrown from inside the next rebuild.`),badBoolean:(e,t,n)=>new GtkHostError(`bad-boolean`,`<${e}>.${t} is a boolean and got the string "${n}". JS truthiness would make "false" mean TRUE — the exact silent-wrong-value this host exists to refuse. Pass a real boolean.`),badFlags:(e,t,n,r)=>new GtkHostError(`bad-flags`,`<${e}>.${t} expects the flags type ${r}, and a string ("${n}") cannot be resolved to one. Pass the numeric value (bitwise-or the members). GObject would have dropped the string silently.`),unresolvableEnum:e=>new GtkHostError(`unresolvable-enum`,`Cannot resolve the enum type ${e} to a GI namespace. Pass the numeric value instead, or extend ENUM_NAMESPACES in props.ts.`),textNotAccepted:(e,t)=>new GtkHostError(`text-not-accepted`,`<${e}> has no text sink, so the text ${JSON.stringify(t.slice(0,32))} has nowhere to go. Wrap it in a widget that takes text (<GtkLabel>), or set the property directly.`),unclaimedChild:(e,t)=>new GtkHostError(`unclaimed-child`,`<${e}> declares children: { kind: 'none' }, so it cannot adopt <${t}>. Fix one of three things: give the parent a child policy, wrap the child in a container, or set the child on a property (e.g. a "child" or "content" property).`),unknownSlot:(e,t,n)=>new GtkHostError(`unknown-slot`,`<${e}> has no slot "${t}". Known slots: ${n.join(`, `)}.`),rejectedChild:(e,t,n)=>new GtkHostError(`rejected-child`,`<${e}> refused <${t}>: ${n}. The container accepts only certain child types (e.g. AdwPreferencesPage takes AdwPreferencesGroup); the descriptor cannot know that, GTK does.`),notAWidget:e=>new GtkHostError(`not-a-widget`,`<${e}> is not a Gtk.Widget, so it cannot be placed as a child. Non-widget GObjects (controllers, filters, models) attach to a property, not to a parent.`)};export{GtkHostError,e as err};

package/lib/esm/host.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{err as e}from"./errors.js";import{lookupWidget as t,nearestRegistered as n}from"./registry.js";import{addressOf as r,insertChild as i,makeWrapper as a,removeChild as o}from"./policies.js";import{beginHostWrite as s,clearHandlers as c,endHostWrite as l,isEventProp as u,setHandler as d,toSignalName as f}from"./signals.js";import{coerce as p,defaultValue as m,paramSpecs as h,requireSpec as g,toPropertyName as _}from"./props.js";import v from"gi://GObject";function createElement(e,n){let r={kind:`element`,descriptor:t(e),widget:null,wrapper:null,slot:null,parent:null,prev:null,next:null,first:null,last:null,handlers:new Map,listeners:new Map,props:{},layout:null,textFromChildren:!1,attached:!1};if(n)for(let[e,t]of Object.entries(n))setProp(r,e,t);return r}const createText=e=>({kind:`text`,data:e,parent:null,prev:null,next:null}),createAnchor=(e=``)=>({kind:`anchor`,data:e,parent:null,prev:null,next:null}),isText=e=>e.kind===`text`;function materialize(e){if(e.widget)return e.widget;let t=e.descriptor.ctor(),n=h(t,e.descriptor.gtype),r={};for(let[t,i]of Object.entries(e.props))r[t]=p(g(n,e.descriptor.gtype,t),i,e.descriptor.gtype);s();try{e.widget=new t(r)}finally{l()}try{replayInto(e)}catch(t){c(e);for(let t of childSnapshot(e))t.kind===`element`&&t.attached&&(o(e,t),t.attached=!1);throw e.widget=null,e.wrapper=null,t}return e.widget}function replayInto(e){for(let[t,n]of e.listeners)d(e,t,n);for(let t=e.first;t;t=t.next)t.kind===`element`&&attach(e,t);e.textFromChildren&&flushText(e)}function setProp(e,t,n,r){if(u(t))return setEventHandler(e,t,n);if(t===`slot`)return setSlot(e,n);if(t===`layout`){let t=n,r=e.parent;if(!r||!e.widget){e.layout=t;return}let i=e.layout;replaceAt(e,r,()=>{e.layout=t},()=>{e.layout=i});return}let i=_(t),a=g(h(e.descriptor.ctor(),e.descriptor.gtype),e.descriptor.gtype,i),o=n===void 0?m(a):p(a,n,e.descriptor.gtype),c=i in e.props?e.props[i]:void 0;if(n===void 0?delete e.props[i]:e.props[i]=n,e.widget){if((a.flags&v.ParamFlags.CONSTRUCT_ONLY)!==0)return rebuild(e,i,c);s();try{e.widget.set_property(i,o)}finally{l()}}}function setEventHandler(e,t,n){e.widget?d(e,t,n):n&&assertSignalExists(e,t),n?e.listeners.set(t,n):e.listeners.delete(t)}function assertSignalExists(t,n){let r=f(n,t.descriptor.eventAliases).split(`::`)[0],i=t.descriptor.ctor().$gtype;if(v.signal_lookup(r,i)===0)throw e.unknownSignal(t.descriptor.gtype,n,r)}function setSlot(e,t){if(e.slot===t)return;let n=e.parent;if(!n||!e.widget){e.slot=t;return}let r=e.slot;replaceAt(e,n,()=>{e.slot=t},()=>{e.slot=r})}function replaceAt(e,t,n,r){o(t,e),e.attached=!1,n();try{attach(t,e)}catch(n){r();try{attach(t,e)}catch{}throw n}}function rebuild(e,t,n){let r=e.parent;if(e.widget){c(e);for(let t of childSnapshot(e))t.kind===`element`&&(o(e,t),t.attached=!1);r&&o(r,e)}e.widget=null,e.wrapper=null,e.attached=!1;try{materialize(e)}catch(i){t!==void 0&&(n===void 0?delete e.props[t]:e.props[t]=n);try{materialize(e),r&&attach(r,e)}catch{}throw i}r&&attach(r,e)}function setText(e,t){e.data=t,e.kind===`text`&&e.parent&&flushText(e.parent)}function setElementText(e,t){writeTextSink(e,t),e.textFromChildren=!1;for(let t of childSnapshot(e))destroy(t)}function flushText(e){let t=``,n=!1;for(let r of childNodes(e))r.kind===`text`&&(t+=r.data,n=!0);t===``&&!e.textFromChildren||(writeTextSink(e,t),e.textFromChildren=n)}function writeTextSink(t,n){let r=t.descriptor.textSink;if(!r)throw e.textNotAccepted(t.descriptor.gtype,n);materialize(t);let i=g(h(t.descriptor.ctor(),t.descriptor.gtype),t.descriptor.gtype,r);s();try{t.widget.set_property(r,p(i,n,t.descriptor.gtype))}finally{l()}t.props[r]=n}function*childNodes(e){for(let t=e.first;t;t=t.next)yield t}function childSnapshot(e){let t=[];for(let n=e.first;n;n=n.next)t.push(n);return t}function link(e,t,n){t.parent=e,n?(t.prev=n.prev,t.next=n,n.prev?n.prev.next=t:e.first=t,n.prev=t):(t.prev=e.last,t.next=null,e.last?e.last.next=t:e.first=t,e.last=t)}function unlink(e){let t=e.parent;t&&(e.prev?e.prev.next=e.next:t.first=e.next,e.next?e.next.prev=e.prev:t.last=e.prev,e.prev=null,e.next=null,e.parent=null)}function attach(e,t){if(!e.widget)return;materialize(t),ensureWrapper(e,t);let n=null,a=0;for(let i=e.first;i&&i!==t;i=i.next)i.kind!==`element`||!i.attached||(n=r(i),a+=1);let o=[];for(let e=t.next;e;e=e.next)e.kind===`element`&&e.attached&&o.push(e);i({parent:e,child:t,prevWidget:n,index:a,following:o}),t.attached=!0}function ensureWrapper(e,t){if(t.wrapper)return;let n=a(e.descriptor.children,t.widget);n&&(t.wrapper=n)}function insert(e,t,n=null){let r=e.parent,i=e.next;e.parent&&remove(e),link(t,e,n);try{e.kind===`element`?attach(t,e):e.kind===`text`&&flushText(t)}catch(t){throw unlink(e),r&&restore(e,r,i),t}}function restore(e,t,n){try{link(t,e,n),e.kind===`element`?attach(t,e):e.kind===`text`&&flushText(t)}catch{unlink(e)}}function remove(e){let t=e.parent;t&&e.kind===`element`&&(o(t,e),e.attached=!1,e.wrapper&&=(e.wrapper.set_child(null),null)),unlink(e),t&&e.kind===`text`&&flushText(t)}function clearContainer(e){for(;e.first;)remove(e.first)}function destroy(e){if(e.kind===`element`){for(let t of childSnapshot(e))destroy(t);c(e),e.listeners.clear()}if(remove(e),e.kind===`element`){let t=e.widget;t&&typeof t.destroy==`function`&&typeof t.get_parent==`function`&&t.get_parent()===null&&t.destroy(),e.widget=null,e.wrapper=null,e.props={},e.layout=null,e.textFromChildren=!1}}function mountRoot(t,r){materialize(t);let a=r.constructor.$gtype,o=n(a);if(!o)throw e.unknownTag(gtypeNameOf(r));let s={kind:`element`,descriptor:o,widget:r,wrapper:null,slot:null,parent:null,prev:null,next:null,first:null,last:null,handlers:new Map,listeners:new Map,props:{},layout:null,textFromChildren:!1,attached:!0},c=directChildren(r);link(s,t,null);try{ensureWrapper(s,t),i({parent:s,child:t,prevWidget:c.length>0?c[c.length-1]:null,index:c.length,following:[]}),t.attached=!0}catch(e){throw unlink(t),e}}function directChildren(e){let t=[],n=e;if(typeof n.get_first_child!=`function`)return t;for(let e=n.get_first_child();e;e=e.get_next_sibling())t.push(e);return t}const gtypeNameOf=e=>v.type_name(e.constructor.$gtype),parentNode=e=>e.parent,firstChild=e=>e.first,nextSibling=e=>e.next,prevSibling=e=>e.prev;export{clearContainer,createAnchor,createElement,createText,destroy,firstChild,insert,isText,materialize,mountRoot,nextSibling,parentNode,prevSibling,remove,setElementText,setEventHandler,setProp,setSlot,setText};

package/lib/esm/index.js

@@ -0,0 +1 @@
+import{GtkHostError as e}from"./errors.js";import{clearRegistry as t,hasWidget as n,lookupWidget as r,nearestRegistered as i,registerWidget as a,registerWidgets as o,registeredTags as s}from"./registry.js";import{ADW_DESCRIPTORS as c}from"./descriptors/adw.js";import{GTK_DESCRIPTORS as l}from"./descriptors/gtk.js";import{BUILTIN_DESCRIPTORS as u,registerBuiltinWidgets as d}from"./descriptors/index.js";import{addressOf as f,reorderMode as p}from"./policies.js";import{isEventProp as m,toSignalName as h}from"./signals.js";import{constructOnlyNames as g,isConstructOnly as _,isWritable as v,paramSpecs as y,toPropertyName as b}from"./props.js";import{clearContainer as x,createAnchor as S,createElement as C,createText as w,destroy as T,firstChild as E,insert as D,isText as O,materialize as k,mountRoot as A,nextSibling as j,parentNode as M,prevSibling as N,remove as P,setElementText as F,setEventHandler as I,setProp as L,setSlot as R,setText as z}from"./host.js";import"./types.js";export{c as ADW_DESCRIPTORS,u as BUILTIN_DESCRIPTORS,l as GTK_DESCRIPTORS,e as GtkHostError,f as addressOf,x as clearContainer,t as clearRegistry,g as constructOnlyNames,S as createAnchor,C as createElement,w as createText,T as destroy,E as firstChild,n as hasWidget,D as insert,_ as isConstructOnly,m as isEventProp,O as isText,v as isWritable,r as lookupWidget,k as materialize,A as mountRoot,i as nearestRegistered,j as nextSibling,y as paramSpecs,M as parentNode,N as prevSibling,d as registerBuiltinWidgets,a as registerWidget,o as registerWidgets,s as registeredTags,P as remove,p as reorderMode,F as setElementText,I as setEventHandler,L as setProp,R as setSlot,z as setText,b as toPropertyName,h as toSignalName};

package/lib/esm/policies.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{GtkHostError as e,err as t}from"./errors.js";import n from"gi://Gtk?version=4.0";function addressOf(e){let n=e.wrapper??e.widget;if(!n)throw t.notAWidget(e.descriptor.gtype);return n}function makeWrapper(e,t){if(e.kind!==`indexed`||!e.wrap)return null;if(e.wrap===`list-box-row`){if(t instanceof n.ListBoxRow)return null;let e=new n.ListBoxRow;return e.set_child(t),e}if(t instanceof n.FlowBoxChild)return null;let r=new n.FlowBoxChild;return r.set_child(t),r}function insertChild(n){try{placeChild(n)}catch(r){throw r instanceof e?r:t.rejectedChild(n.parent.descriptor.gtype,n.child.descriptor.gtype,r.message)}}function placeChild(e){let{parent:n,child:r}=e,i=n.descriptor.children,a=n.widget,o=addressOf(r);switch(i.kind){case`none`:throw t.unclaimedChild(n.descriptor.gtype,r.descriptor.gtype);case`single`:a[i.set](o);return;case`indexed`:a[i.insert](o,e.index);return;case`coords`:appendChild(n,r,a);return;case`ordered`:if(i.after){a[i.after](o,e.prevWidget??null);return}case`slotted`:case`keyed`:appendChild(n,r,a),rotateTail(n,r,e.following,a);return}}function appendChild(e,n,r){let i=e.descriptor.children,a=addressOf(n);switch(i.kind){case`ordered`:r[i.append](a);return;case`slotted`:{let o=n.slot??i.defaultSlot,s=i.slots[o];if(!s)throw t.unknownSlot(e.descriptor.gtype,o,Object.keys(i.slots));r[s](a);return}case`keyed`:{let e=n.layout?.[i.nameFrom]??n.slot,t=n.layout?.title;i.titled?r[i.add](a,e??null,t??e??``):r[i.add](a);return}case`coords`:{let e=n.layout??{};r[i.attach](a,e.column??0,e.row??0,e.columnSpan??1,e.rowSpan??1);return}default:throw t.unclaimedChild(e.descriptor.gtype,n.descriptor.gtype)}}function rotateTail(e,t,n,r){let i=e.descriptor.children,a=n;if(i.kind===`slotted`){let slotOf=e=>e.slot??i.defaultSlot,e=slotOf(t);if(i.slots[e]?.startsWith(`set_`))return;a=n.filter(t=>slotOf(t)===e)}for(let t of a)detachChild(e,t,r);for(let t of a)appendChild(e,t,r)}function detachChild(e,t,n){let r=e.descriptor.children,i=t.wrapper??t.widget;if(i)switch(r.kind){case`none`:return;case`single`:clearIfCurrent(n,r.set,i);return;case`slotted`:{let e=r.slots[t.slot??r.defaultSlot];if(e?.startsWith(`set_`)){clearIfCurrent(n,e,i);return}n[r.remove](i);return}case`ordered`:case`indexed`:case`keyed`:case`coords`:n[r.remove](i);return}}function clearIfCurrent(e,t,n){let r=t.replace(/^set_/,`get_`),i=typeof e[r]==`function`?e[r]():void 0;(i===void 0||i===n)&&e[t](null)}function removeChild(e,t){let n=e.widget;n&&t.attached&&detachChild(e,t,n)}function reorderMode(e){switch(e.kind){case`ordered`:return e.reorder;case`indexed`:return`native`;case`slotted`:case`keyed`:return`remove-all`;case`coords`:case`single`:case`none`:return`n/a`}}export{addressOf,insertChild,makeWrapper,removeChild,reorderMode};

package/lib/esm/props.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{err as e}from"./errors.js";import t from"gi://GObject";import n from"gi://Adw?version=1";import r from"gi://Gtk?version=4.0";import i from"gi://Gdk?version=4.0";import a from"gi://Pango";const o=[[`Gtk`,r],[`Adw`,n],[`Gdk`,i],[`Pango`,a],[`G`,t]];function toPropertyName(e){return e.includes(`-`)?e:e.replace(/([a-z0-9])([A-Z])/g,`$1-$2`).toLowerCase()}const s=new Map;function paramSpecs(e,t){let n=s.get(t);if(n)return n;n=new Map;for(let t of e.list_properties())n.set(t.get_name(),t);return s.set(t,n),n}const isFlag=(e,t)=>(e&t)!==0,isWritable=e=>isFlag(e.flags,t.ParamFlags.WRITABLE),isConstructOnly=e=>isFlag(e.flags,t.ParamFlags.CONSTRUCT_ONLY);function constructOnlyNames(e,t){let n=[];for(let[r,i]of paramSpecs(e,t))isConstructOnly(i)&&isWritable(i)&&n.push(r);return n}function resolveEnumValue(e,t){for(let[n,r]of o){if(!e.startsWith(n))continue;let i=r[e.slice(n.length)];if(!i)continue;let a=i[t.toUpperCase().replace(/-/g,`_`)];return typeof a==`number`?{resolved:!0,value:a}:{resolved:!0}}return{resolved:!1}}function coerce(n,r,i){if(r==null)return r;let a=n.value_type;if(t.type_is_a(a,t.TYPE_ENUM)&&typeof r==`string`){let o=t.type_name(a),s=resolveEnumValue(o,r);if(s.value!==void 0)return s.value;throw s.resolved?e.badEnum(i,n.get_name(),r,o):e.unresolvableEnum(o)}if(t.type_is_a(a,t.TYPE_FLAGS)&&typeof r==`string`)throw e.badFlags(i,n.get_name(),r,t.type_name(a));if(t.type_is_a(a,t.TYPE_BOOLEAN)){if(typeof r==`boolean`)return r;if(r===`true`)return!0;if(r===`false`)return!1;if(typeof r==`string`)throw e.badBoolean(i,n.get_name(),r);return!!r}if(t.type_is_a(a,t.TYPE_STRING)){if(typeof r==`string`)return r;if(typeof r==`number`||typeof r==`boolean`)return String(r);throw e.badString(i,n.get_name(),typeof r)}return(t.type_is_a(a,t.TYPE_INT)||t.type_is_a(a,t.TYPE_UINT)||t.type_is_a(a,t.TYPE_INT64)||t.type_is_a(a,t.TYPE_UINT64))&&typeof r==`number`?Math.trunc(r):r}function defaultValue(e){return e.get_default_value()}function requireSpec(t,n,r){let i=t.get(r);if(!i)throw e.unknownProp(n,r);if(!isWritable(i))throw e.readOnlyProp(n,r);return i}export{coerce,constructOnlyNames,defaultValue,isConstructOnly,isWritable,paramSpecs,requireSpec,toPropertyName};

package/lib/esm/registry.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{err as e}from"./errors.js";import t from"gi://GObject";const n=new Map;function registerWidget(e){n.set(e.gtype,e)}function registerWidgets(e){for(let t of e)registerWidget(t)}function lookupWidget(t){let r=n.get(t);if(!r)throw e.unknownTag(t);return r}const hasWidget=e=>n.has(e),registeredTags=()=>[...n.keys()].sort();function nearestRegistered(e){let r,i=-1;for(let a of n.values()){let n;try{n=a.ctor().$gtype}catch{continue}if(!t.type_is_a(e,n))continue;let o=depthOf(n);o>i&&(r=a,i=o)}return r}function depthOf(e){let n=0,r=e;for(;r;){let e=t.type_parent(r);if(!e)break;n+=1,r=e}return n}function clearRegistry(){n.clear()}export{clearRegistry,hasWidget,lookupWidget,nearestRegistered,registerWidget,registerWidgets,registeredTags};

package/lib/esm/signals.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{err as e}from"./errors.js";function toSignalName(e,t){if(t?.[e])return t[e];if(e.startsWith(`on:`))return e.slice(3);let n=e.slice(2);return n.startsWith(`Notify`)?`notify::${kebab(n.slice(6))}`:kebab(n)}const kebab=e=>e.replace(/^./,e=>e.toLowerCase()).replace(/([a-z0-9])([A-Z])/g,`$1-$2`).toLowerCase();function isEventProp(e){return e.startsWith(`on:`)||e.length>2&&e.startsWith(`on`)&&e[2]===e[2].toUpperCase()&&e[2]!==e[2].toLowerCase()}let t=0;const beginHostWrite=()=>{t+=1},endHostWrite=()=>{--t},inHostWrite=()=>t>0;function setHandler(t,n,r){let i=toSignalName(n,t.descriptor.eventAliases),a=t.handlers.get(i),o=t.widget;if(a&&a.prop!==n&&r)throw e.signalTaken(t.descriptor.gtype,n,a.prop,i);if(a&&(o.disconnect(a.id),t.handlers.delete(i)),!r)return;let s=i.startsWith(`notify::`),c=o.connect(i,(...e)=>{if(!(s&&inHostWrite()))return r(...e.slice(1))});t.handlers.set(i,{id:c,prop:n})}function clearHandlers(e){if(!e.widget){e.handlers.clear();return}let t=e.widget;for(let{id:n}of e.handlers.values())t.disconnect(n);e.handlers.clear()}export{beginHostWrite,clearHandlers,endHostWrite,inHostWrite,isEventProp,setHandler,toSignalName};

package/lib/types/conformance/diagnostics.d.ts

@@ -0,0 +1,17 @@
+export interface DiagnosticsGate {
+    /** Warning-or-worse messages seen since the last `reset()`. */
+    readonly seen: readonly string[];
+    reset(): void;
+    /** Throw if anything was recorded, naming every message. */
+    assertQuiet(context?: string): void;
+}
+/**
+ * Install the writer func once per process and return the gate.
+ *
+ * `GLib.log_set_writer_func` is process-global and replaces GLib's own writer, so
+ * this forwards rather than swallows — a writer that ate its input would hide the
+ * messages it exists to detect, including its own. The forward threshold matches
+ * what GLib's default writer does with `G_MESSAGES_DEBUG` unset: message-and-above
+ * is printed, info/debug is not.
+ */
+export declare function installDiagnosticsGate(): DiagnosticsGate;

package/lib/types/conformance/index.d.ts

@@ -0,0 +1,26 @@
+export { installDiagnosticsGate, type DiagnosticsGate } from './diagnostics.js';
+import type Gtk from '@girs/gtk-4.0';
+import type { ChildPolicy, HostElement, WidgetDescriptor } from '../types.js';
+/** Every method name a policy names, so the check does not have to know the shapes. */
+export declare function methodsOf(policy: ChildPolicy): string[];
+export interface DescriptorProblem {
+    gtype: string;
+    problem: string;
+}
+/**
+ * Assert the table against the installed typelib.
+ *
+ * A descriptor may name a method that does not exist — libadwaita renames, a
+ * distro ships an older GTK, a copy/paste survives review. Calling it produces
+ * `TypeError: host[policy.append] is not a function` deep inside a render, so
+ * the check runs up front and names the widget.
+ */
+export declare function descriptorProblems(descriptors?: readonly WidgetDescriptor[]): DescriptorProblem[];
+/** Direct GTK children of a widget, in GTK's own order. */
+export declare function gtkChildren(widget: Gtk.Widget): Gtk.Widget[];
+/** GType names of a widget's direct children — the cheap shape assertion. */
+export declare const gtkChildTypes: (widget: Gtk.Widget) => string[];
+/** The addresses a host element's element-children occupy, in shadow order. */
+export declare function addressesOf(el: HostElement): Gtk.Widget[];
+/** Recursive GType dump — what a devtools tree walk would show. */
+export declare function dumpTree(widget: Gtk.Widget, depth?: number): string;

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

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

package/lib/types/descriptors/adw.d.ts

@@ -0,0 +1,2 @@
+import type { WidgetDescriptor } from '../types.js';
+export declare const ADW_DESCRIPTORS: readonly WidgetDescriptor[];

package/lib/types/descriptors/gtk.d.ts

@@ -0,0 +1,2 @@
+import type { WidgetDescriptor } from '../types.js';
+export declare const GTK_DESCRIPTORS: readonly WidgetDescriptor[];

package/lib/types/descriptors/index.d.ts

@@ -0,0 +1,5 @@
+export { GTK_DESCRIPTORS } from './gtk.js';
+export { ADW_DESCRIPTORS } from './adw.js';
+export declare const BUILTIN_DESCRIPTORS: import("../types.js").WidgetDescriptor[];
+/** Install the built-in table. Idempotent — registration is keyed on the GType name. */
+export declare function registerBuiltinWidgets(): void;

package/lib/types/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Every failure this host reports names the tag, the property and the fix.
+ *
+ * The reason is measured, not stylistic: GTK's own failure mode is Exit 0.
+ * Writing a string nick to an enum property is a SILENT no-op through both
+ * `set_property()` and the JS setter (`box.orientation = 'vertical'` leaves it
+ * at `HORIZONTAL`, gjs 1.88.1); writing a read-only property does not throw; and
+ * a mis-parented widget floods stderr with `Gtk-WARNING` while the process still
+ * exits 0. A renderer that stays quiet here produces a wrong window and a green
+ * test run, so this host is loud on purpose.
+ */
+export declare class GtkHostError extends Error {
+    readonly code: string;
+    readonly name = "GtkHostError";
+    constructor(code: string, message: string);
+}
+export declare const err: {
+    unknownTag: (tag: string) => GtkHostError;
+    unknownProp: (tag: string, prop: string) => GtkHostError;
+    readOnlyProp: (tag: string, prop: string) => GtkHostError;
+    badEnum: (tag: string, prop: string, nick: string, gtypeName: string) => GtkHostError;
+    unknownSignal: (tag: string, prop: string, signal: string) => GtkHostError;
+    signalTaken: (tag: string, prop: string, other: string, signal: string) => GtkHostError;
+    badString: (tag: string, prop: string, got: string) => GtkHostError;
+    badBoolean: (tag: string, prop: string, value: string) => GtkHostError;
+    badFlags: (tag: string, prop: string, value: string, gtypeName: string) => GtkHostError;
+    unresolvableEnum: (gtypeName: string) => GtkHostError;
+    textNotAccepted: (tag: string, text: string) => GtkHostError;
+    unclaimedChild: (parentTag: string, childTag: string) => GtkHostError;
+    unknownSlot: (parentTag: string, slot: string, known: string[]) => GtkHostError;
+    rejectedChild: (parentTag: string, childTag: string, reason: string) => GtkHostError;
+    notAWidget: (tag: string) => GtkHostError;
+};

package/lib/types/host.d.ts

@@ -0,0 +1,56 @@
+import GObject from 'gi://GObject';
+import type Gtk from '@girs/gtk-4.0';
+import type { HostAnchor, HostElement, HostNode, HostText, WidgetDescriptor } from './types.js';
+export declare function createElement(tag: string, props?: Record<string, unknown>): HostElement;
+export declare const createText: (data: string) => HostText;
+/**
+ * A position marker with no widget. Vue's `createComment` lands here, and so
+ * does every `v-if`/`<Show>` boundary.
+ *
+ * Anchors never enter the GTK tree. Insertion resolves forward past them to the
+ * next node that owns a widget — which is why an empty branch cannot shift a
+ * sibling's index.
+ */
+export declare const createAnchor: (data?: string) => HostAnchor;
+export declare const isText: (node: HostNode) => node is HostText;
+/**
+ * Build the GObject. Deferred until the widget is actually needed, because
+ * construct-only properties must all be known at `g_object_new` time — and
+ * Solid's `createElement(tag)` contract hands over no properties at all.
+ */
+export declare function materialize(el: HostElement): GObject.Object;
+export declare function setProp(el: HostElement, key: string, next: unknown, _prev?: unknown): void;
+export declare function setEventHandler(el: HostElement, prop: string, next: ((...args: unknown[]) => unknown) | null): void;
+export declare function setSlot(el: HostElement, slot: string | null): void;
+export declare function setText(node: HostText | HostAnchor, data: string): void;
+/** Vue's bulk path and React's `shouldSetTextContent`: drop children, set the sink. */
+export declare function setElementText(el: HostElement, text: string): void;
+export declare function insert(node: HostNode, parent: HostElement, anchor?: HostNode | null): void;
+/** Detach only — reversible. Frameworks move nodes; `remove` must not destroy one. */
+export declare function remove(node: HostNode): void;
+export declare function clearContainer(parent: HostElement): void;
+/**
+ * Tear a subtree down: disconnect every handler, unparent, drop the reference.
+ *
+ * It is eager and it is the only place a handler dies. GJS blocks JS callbacks
+ * during GC ("The offending callback was `dispose()`"), so whatever is not
+ * disconnected here stays connected for the life of the process.
+ *
+ * A toplevel window is the one node unparenting cannot reach — it has no parent
+ * and its `GtkApplication` still holds it — so it is closed explicitly.
+ */
+export declare function destroy(node: HostNode): void;
+/**
+ * Put a host tree inside an existing GTK container the application owns.
+ *
+ * The container is resolved through the SAME table as every other parent —
+ * `nearestRegistered` walks the real type hierarchy, so an application's own
+ * `GObject.registerClass` subclass inherits its ancestor's policy. Guessing a
+ * method name here would be the generic `add` that GTK4 deliberately removed.
+ */
+export declare function mountRoot(el: HostElement, container: Gtk.Widget): void;
+export declare const parentNode: (node: HostNode) => HostElement | null;
+export declare const firstChild: (el: HostElement) => HostNode | null;
+export declare const nextSibling: (node: HostNode) => HostNode | null;
+export declare const prevSibling: (node: HostNode) => HostNode | null;
+export type { WidgetDescriptor };

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

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

package/lib/types/index.d.ts

@@ -0,0 +1,8 @@
+export * from './types.js';
+export { GtkHostError } from './errors.js';
+export { createAnchor, createElement, createText, clearContainer, destroy, firstChild, insert, isText, materialize, mountRoot, nextSibling, parentNode, prevSibling, remove, setElementText, setEventHandler, setProp, setSlot, setText, } from './host.js';
+export { addressOf, reorderMode } from './policies.js';
+export { toSignalName, isEventProp } from './signals.js';
+export { constructOnlyNames, isConstructOnly, isWritable, paramSpecs, toPropertyName } from './props.js';
+export { clearRegistry, hasWidget, lookupWidget, nearestRegistered, registerWidget, registerWidgets, registeredTags, } from './registry.js';
+export { ADW_DESCRIPTORS, BUILTIN_DESCRIPTORS, GTK_DESCRIPTORS, registerBuiltinWidgets } from './descriptors/index.js';

package/lib/types/policies.d.ts

@@ -0,0 +1,33 @@
+import Gtk from 'gi://Gtk?version=4.0';
+import type { ChildPolicy, HostElement } from './types.js';
+/** The object the PARENT addresses: a wrapper row when the policy demands one. */
+export declare function addressOf(el: HostElement): Gtk.Widget;
+/**
+ * `Gtk.ListBox` and `Gtk.FlowBox` wrap arbitrary children; the wrap is the host's job.
+ *
+ * Unless the author already wrote the row themselves — `<GtkListBox><GtkListBoxRow>`
+ * is the spelling anyone reaching for `activatable` or `selectable` uses, and
+ * wrapping a row inside a second row nests two selectable widgets and detaches
+ * activation from the one the author configured.
+ */
+export declare function makeWrapper(policy: ChildPolicy, child: Gtk.Widget): Gtk.Widget | null;
+export interface Placement {
+    parent: HostElement;
+    child: HostElement;
+    /** Address of the preceding element sibling, or null when the child goes first. */
+    prevWidget: Gtk.Widget | null;
+    /** Index among ELEMENT siblings — text and anchors do not count. */
+    index: number;
+    /**
+     * Element siblings after the insertion point, in order.
+     *
+     * ELEMENTS, not widgets: a container that cannot insert is re-placed by
+     * rotating its tail, and re-placing a child needs the child's own slot or
+     * page name, which a bare `Gtk.Widget` cannot answer.
+     */
+    following: HostElement[];
+}
+export declare function insertChild(place: Placement): void;
+export declare function removeChild(parent: HostElement, child: HostElement): void;
+/** Does this parent reorder in place, or does it pay a full re-append? Declared, not guessed. */
+export declare function reorderMode(policy: ChildPolicy): 'native' | 'remove-all' | 'n/a';

package/lib/types/props.d.ts

@@ -0,0 +1,29 @@
+import GObject from 'gi://GObject';
+/** `backgroundColor` and `background-color` both name the GObject property `background-color`. */
+export declare function toPropertyName(name: string): string;
+/** All ParamSpecs of a class, by kebab name. Cached per GType — `list_properties()` is not cheap. */
+export declare function paramSpecs(klass: GObject.ObjectClass, gtypeName: string): Map<string, GObject.ParamSpec>;
+export declare const isWritable: (spec: GObject.ParamSpec) => boolean;
+export declare const isConstructOnly: (spec: GObject.ParamSpec) => boolean;
+/** Construct-only property names of a class, in declaration order. */
+export declare function constructOnlyNames(klass: GObject.ObjectClass, gtypeName: string): string[];
+/**
+ * Turn an authored value into one GObject will actually store.
+ *
+ * The enum branch is the whole reason this function exists: GObject accepts a
+ * string for an enum property and silently keeps the old value. Measured on
+ * gjs 1.88.1 — `set_property('orientation', 'vertical')` emits
+ * `GLib-GObject-CRITICAL` and leaves HORIZONTAL, and the JS setter
+ * `box.orientation = 'vertical'` does the same without any diagnostic at all.
+ */
+export declare function coerce(spec: GObject.ParamSpec, value: unknown, tag: string): unknown;
+/**
+ * The value a property falls back to when a renderer removes it.
+ *
+ * React hands `undefined` for a prop that disappeared, and GObject cannot store
+ * that: `set_property(name, undefined)` throws "Could not guess unspecified
+ * GValue type" (measured). The ParamSpec knows the right answer.
+ */
+export declare function defaultValue(spec: GObject.ParamSpec): unknown;
+/** Look a property up, refusing the two silent failures: unknown and read-only. */
+export declare function requireSpec(specs: Map<string, GObject.ParamSpec>, tag: string, name: string): GObject.ParamSpec;

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

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

package/lib/types/registry.d.ts

@@ -0,0 +1,25 @@
+import GObject from 'gi://GObject';
+import type { WidgetDescriptor } from './types.js';
+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;
+/** Every registered tag — the conformance suite walks this, so coverage is data. */
+export declare const registeredTags: () => string[];
+/**
+ * The nearest registered ancestor of a GType, most specific first.
+ *
+ * Registration is exact, but a consumer may subclass (`GObject.registerClass`)
+ * and still want its parent's placement rules. Dispatch walks the real type
+ * hierarchy rather than a name prefix, which is why `Gtk.HeaderBar` and
+ * `Adw.HeaderBar` can never be confused for one another.
+ */
+export declare function nearestRegistered(gtype: GObject.GType): WidgetDescriptor | undefined;
+/**
+ * Drop every registration.
+ *
+ * A seam for a consumer that wants a table of its own — nothing in this package
+ * calls it, and the specs deliberately share the module-global table because
+ * that is what an application sees.
+ */
+export declare function clearRegistry(): void;

package/lib/types/signals.d.ts

@@ -0,0 +1,11 @@
+import type { HostElement } from './types.js';
+/** `onRowActivated` -> `row-activated`; `onNotifyVisible` -> `notify::visible`. */
+export declare function toSignalName(prop: string, aliases?: Readonly<Record<string, string>>): string;
+/** An event prop is `on:` + a raw signal name, or `on` + an uppercase letter. */
+export declare function isEventProp(prop: string): boolean;
+export declare const beginHostWrite: () => void;
+export declare const endHostWrite: () => void;
+export declare const inHostWrite: () => boolean;
+export declare function setHandler(el: HostElement, prop: string, next: ((...args: unknown[]) => unknown) | null): void;
+/** Disconnect every handler on a node. The only place a handler dies. */
+export declare function clearHandlers(el: HostElement): void;

package/lib/types/types.d.ts

@@ -0,0 +1,145 @@
+import type GObject from '@girs/gobject-2.0';
+import type Gtk from '@girs/gtk-4.0';
+export type NodeKind = 'element' | 'text' | 'anchor';
+export interface HostNodeBase {
+    readonly kind: NodeKind;
+    parent: HostElement | null;
+    prev: HostNode | null;
+    next: HostNode | null;
+}
+/** A text run. GTK has no text node — the OWNING element writes it to its text sink. */
+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.
+ */
+export interface HostAnchor extends HostNodeBase {
+    readonly kind: 'anchor';
+    data: string;
+}
+export interface HostElement extends HostNodeBase {
+    readonly kind: 'element';
+    readonly descriptor: WidgetDescriptor;
+    /** null until materialisation — construct-only properties must be known first. */
+    widget: GObject.Object | null;
+    /** `Gtk.ListBoxRow` & friends: the object the PARENT addresses, not the child itself. */
+    wrapper: Gtk.Widget | null;
+    /** Declared by the CHILD (`slot="end"`), not derived from its position. */
+    slot: string | null;
+    first: HostNode | null;
+    last: HostNode | null;
+    /**
+     * 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.
+     */
+    handlers: Map<string, {
+        id: number;
+        prop: string;
+    }>;
+    /** Authored property values, kebab-normalised. Kept after materialisation so a
+     *  construct-only change can rebuild the widget from the same intent. */
+    props: Record<string, unknown>;
+    /** Authored signal callbacks by prop name — a rebuild has to re-bind them. */
+    listeners: Map<string, (...args: unknown[]) => unknown>;
+    /** Positional data for `coords` parents (`Gtk.Grid`), read off the child. */
+    layout: Record<string, unknown> | null;
+    /** True once text CHILDREN wrote the sink, so removing the last one clears it
+     *  instead of leaving the stale string an authored prop never set. */
+    textFromChildren: boolean;
+    /**
+     * 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.
+     */
+    attached: boolean;
+}
+export type HostNode = HostElement | HostText | HostAnchor;
+export type PolicyKind = 'none' | 'single' | 'ordered' | 'indexed' | 'slotted' | 'keyed' | 'coords';
+/**
+ * How a parent adopts children. GTK4 deleted `GtkContainer`, so there is no
+ * generic `add` — and `Gtk.Buildable.add_child` is introspected as a vfunc only
+ * (`typeof headerBar.add_child === 'undefined'`, measured on gjs 1.88.1), so it
+ * is not an escape hatch either. Every container states its own rules here.
+ */
+export type ChildPolicy = {
+    kind: 'none';
+}
+/** `set_child` / `set_content` / `set_titlebar`: at most one child. */
+ | {
+    kind: 'single';
+    set: string;
+}
+/**
+ * Sequential children. `after` is the O(1) reorder path
+ * (`Gtk.Box.insert_child_after`); a container without it — `Adw.PreferencesGroup`
+ * has `add`/`remove` but no `insert`, measured — declares `reorder: 'remove-all'`
+ * and pays a full re-append per reorder. That degradation is DECLARED, never silent.
+ */
+ | {
+    kind: 'ordered';
+    append: string;
+    after?: string;
+    remove: string;
+    reorder: 'native' | 'remove-all';
+}
+/** `Gtk.ListBox`/`Gtk.FlowBox`: index-addressed, and the parent addresses a WRAPPER row. */
+ | {
+    kind: 'indexed';
+    insert: string;
+    remove: string;
+    wrap: 'list-box-row' | 'flow-box-child' | null;
+}
+/** `Adw.HeaderBar`, `Adw.ToolbarView`, `Adw.ActionRow`: named attachment points. */
+ | {
+    kind: 'slotted';
+    slots: Record<string, string>;
+    defaultSlot: string;
+    remove: string;
+}
+/**
+ * `Gtk.Stack`, `Adw.NavigationView`: children addressed by name/tag.
+ *
+ * `titled` states the ARITY, because it differs and getting it wrong is not
+ * a type error: `gtk_stack_add_titled(child, name, title)` requires all
+ * three and GJS throws "At least 3 arguments required" (measured), while
+ * `adw_navigation_view_add(page)` takes one. `descriptorProblems()` checks
+ * that a method EXISTS, never how many arguments it wants.
+ */
+ | {
+    kind: 'keyed';
+    add: string;
+    remove: string;
+    nameFrom: string;
+    titled: boolean;
+}
+/** `Gtk.Grid`: position is data on the child, so document order carries nothing. */
+ | {
+    kind: 'coords';
+    attach: string;
+    remove: string;
+};
+export interface WidgetDescriptor {
+    /** GType name — and the tag a renderer writes. `GtkButton`, `AdwActionRow`. */
+    readonly gtype: string;
+    /** 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;
+    /**
+     * Where a text child goes. Absent means text under this widget is an ERROR
+     * that names the tag — never a silent drop.
+     */
+    readonly textSink?: string;
+    /** `onActivate` -> `activate` is derived; irregular pairs live here, in the TABLE. */
+    readonly eventAliases?: Readonly<Record<string, string>>;
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+    "name": "@gjsify/gtk-host",
+    "version": "0.41.0",
+    "description": "Framework-agnostic GTK4/Adwaita host: the element model UI-framework renderers bind to",
+    "type": "module",
+    "module": "lib/esm/index.js",
+    "types": "lib/types/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./lib/types/index.d.ts",
+            "default": "./lib/esm/index.js"
+        },
+        "./conformance": {
+            "types": "./lib/types/conformance/index.d.ts",
+            "default": "./lib/esm/conformance/index.js"
+        }
+    },
+    "files": [
+        "lib"
+    ],
+    "scripts": {
+        "clear": "gjsify clear lib tmp tsconfig.tsbuildinfo test.gjs.mjs",
+        "check": "gjsify tsc --noEmit",
+        "build": "gjsify run build:gjsify && gjsify run build:types",
+        "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:gjs": "gjsify build src/test.mts --app gjs --outfile test.gjs.mjs",
+        "test": "gjsify run build:gjsify && gjsify run build:test && gjsify run test:gjs",
+        "test:gjs": "gjsify run test.gjs.mjs"
+    },
+    "keywords": [
+        "gjs",
+        "gtk",
+        "adwaita",
+        "renderer",
+        "host"
+    ],
+    "dependencies": {
+        "@girs/adw-1": "^4.1.0",
+        "@girs/gdk-4.0": "^4.1.0",
+        "@girs/gjs": "^4.1.0",
+        "@girs/gobject-2.0": "^4.1.0",
+        "@girs/gtk-4.0": "^4.1.0",
+        "@girs/pango-1.0": "^4.1.0"
+    },
+    "devDependencies": {
+        "@gjsify/cli": "^0.41.0",
+        "@gjsify/unit": "^0.41.0",
+        "@types/node": "^25.9.2",
+        "typescript": "^6.0.3"
+    },
+    "gjsify": {
+        "runtimes": {
+            "gjs": "polyfill",
+            "node": "none",
+            "browser": "none",
+            "nativescript": "none"
+        },
+        "tier": 3
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gjsify/gjsify.git",
+        "directory": "packages/framework/gtk-host"
+    },
+    "bugs": {
+        "url": "https://github.com/gjsify/gjsify/issues"
+    },
+    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/framework/gtk-host#readme"
+}