@gjsify/gtk-host 0.41.0 → 0.43.0

package/lib/types/generated/surface-data.d.mts

@@ -0,0 +1,22 @@
+/** Declaration GType -> its OWN writable properties, kebab-spelled as GObject knows them. */
+export declare const OWN_PROPS: Readonly<Record<string, readonly string[]>>;
+/** Declaration GType -> its OWN signals. */
+export declare const OWN_SIGNALS: Readonly<Record<string, readonly string[]>>;
+/** Widget GType -> every declaration its members come from, self first. */
+export declare const DECLS: Readonly<Record<string, readonly string[]>>;
+/** Enum GType -> the nicks the surface offers. */
+export declare const ENUM_NICKS: Readonly<Record<string, readonly string[]>>;
+/** Widget GType -> its kebab tag. */
+export declare const TAGS: Readonly<Record<string, string>>;
+/**
+ * `Type.property` / `Type::signal` -> the release that introduced it.
+ *
+ * This is what keeps the runtime cross-check honest across a version gap instead
+ * of needing an allowlist. Measured on the pinned GIR against gtk 4.22.4:
+ * `GtkApplicationWindow::save-state` is in the surface and NOT in the installed
+ * library, because it arrived in 4.24. Without a since-map the only options are to
+ * stop checking signals or to hard-code two names; with it, the rule is exact —
+ * a member the installed library lacks must be explained by a version newer than
+ * the one running, and anything else is a real defect.
+ */
+export declare const SINCE: Readonly<Record<string, string>>;

package/lib/types/generated/widgets.d.ts

@@ -0,0 +1,3 @@
+import type { GeneratedWidget } from '../types.js';
+export declare const GENERATED_PROVENANCE: "Gtk-4.0 Adw-1";
+export declare const GENERATED_WIDGETS: readonly GeneratedWidget[];

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

@@ -0,0 +1,4 @@
+/** `'4.24'` against `'4.22.4'` — true. Missing or equal is NOT newer. */
+export declare const newerThan: (since: string | undefined, running: string) => boolean;
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/generator/emit-types.d.mts

@@ -0,0 +1,54 @@
+/**
+ * Emit the TYPE surfaces: one interface per GIR declaration, two tag maps.
+ *
+ * WHAT THE DIALECTS FORCED, all of it measured rather than assumed (ADR 0028 § 7,
+ * and the numbers live there):
+ *
+ *  - BOTH PROPERTY SPELLINGS, for opposite reasons in the two dialects. Vue does
+ *    not need the kebab key — Volar camelizes an attribute before resolving it, so
+ *    `:height-request` finds `heightRequest` and catches a wrong value type there.
+ *    JSX does need it: TypeScript exempts every hyphenated attribute from
+ *    excess-property checking, so `no-such={1}` on an intrinsic is silently
+ *    accepted, and the only checking a kebab attribute can ever get is the value
+ *    check that a DECLARED key gives it. Declaring both costs 561 extra members
+ *    and buys the one spelling GTK itself uses.
+ *  - JSX KEYS ARE KEBAB, VUE KEYS ARE THE GTYPE NAME. A capitalised
+ *    `JSX.IntrinsicElements` key is never consulted — TypeScript reads `<GtkBox/>`
+ *    as a value reference — while Volar resolves a kebab TAG against a GType key
+ *    but not a Pascal tag against a kebab key. So each dialect gets the one
+ *    spelling that works, from one shared props interface.
+ *  - EXACT HANDLER SIGNATURES, never `(...args: unknown[]) => void`. Measured
+ *    twice over: an annotated `(row: AdwActionRow) => void` will not assign to an
+ *    `unknown[]` rest (TS2322, contravariance), and an inline arrow's parameter
+ *    arrives as `unknown` so using it fails (TS2345). A generated surface that
+ *    typed handlers loosely would break every handler that names its parameter.
+ */
+import type { SurfaceModel } from './surface.mjs';
+/**
+ * Volar's own resolution rule, reproduced so the generator can SEE the gap.
+ *
+ * A Vue template tag is camelized (`-x` -> `X`) and capitalised before lookup, and
+ * that transform has no acronym knowledge: `gtk-gl-area` becomes `GtkGlArea`,
+ * which is not `GtkGLArea`. Measured — `<gtk-gl-area>` against a `GtkGLArea` key
+ * is TS2339. Exactly one of the 164 concrete widgets is affected today, and the
+ * generator finds it rather than leaving it to a bug report: such a widget gets an
+ * extra kebab-spelled key, which a kebab tag does resolve against.
+ */
+export declare const volarResolves: (tag: string, gtype: string) => boolean;
+export interface EmittedFile {
+    readonly path: string;
+    readonly text: string;
+}
+export declare function emitProps(model: SurfaceModel, provenance: string): EmittedFile;
+/**
+ * Emit the data the runtime cross-check reads.
+ *
+ * `.mts`, so it is EXCLUDED from the library build (`src/**​/*.{ts,js}`) and never
+ * ships — the same trick `testing/gate.mts` uses. It exists to let a spec ask the
+ * installed GTK whether the generated surface is true: every property present as a
+ * writable ParamSpec, every signal resolvable by `GObject.signal_lookup`, every
+ * enum nick resolvable through the host's own enum lookup. Shipping this as
+ * runtime data would make it a second source for what `paramSpecs()` already
+ * answers from the class that is actually installed.
+ */
+export declare function emitSurfaceData(model: SurfaceModel, provenance: string): EmittedFile;

package/lib/types/generator/emit.d.mts

@@ -0,0 +1,50 @@
+/**
+ * Emit the widget table, and the four gates that make it trustworthy.
+ *
+ * WHAT SHIPS is deliberately thin: tag, GType and the map between them (ADR 0028
+ * § 1, as amended). Property names, the construct-only set and signal names are
+ * consumed INSIDE the generator to emit the TYPE surfaces — shipping them as
+ * runtime data would be a second source with no consumer, because `props.ts` and
+ * `host.ts` already resolve every property through `paramSpecs()` on the class
+ * that is actually installed.
+ *
+ * The artifact is COMMITTED and gets no regenerate-and-compare gate. Committing
+ * is what makes `check`, `lint`, `format`, the build cache, the tarball and a
+ * fresh clone with no GIR all work unchanged, and it makes a widget table
+ * reviewable in a diff. A byte gate would fail for nothing the day a second CI
+ * leg runs a different GTK: four GTK versions sit on the maintainer workstation
+ * alone (4.16.13, 4.20.4, 4.22.4, 4.23.0) and the pinned `@girs` is a fifth
+ * answer. The machine-INDEPENDENT check is the runtime one that already exists —
+ * `descriptorProblems()` against the installed typelib.
+ */
+import type { ChildPolicy, WidgetDescriptor } from '../types.js';
+import type { GirClass, GirNamespace } from './gir.mjs';
+/**
+ * The `gi://` import a generated table needs, per GIR namespace.
+ *
+ * Injectable through `EmitInput`, not read from here directly, and the fixture
+ * that forced that is the point: with the map hard-coded, G4 rejected every widget
+ * of a five-class test namespace as an "unexpected gtype shape" and the floor check
+ * below it could never be reached. A gate whose own test cannot run is a gate on
+ * trust.
+ */
+export declare const GJS_MODULES: Readonly<Record<string, string>>;
+export interface EmitInput {
+    readonly namespaces: readonly GirNamespace[];
+    readonly widgets: readonly GirClass[];
+    readonly curated: readonly WidgetDescriptor[];
+    /** `methodsOf` from the conformance module — one extractor, not a second copy. */
+    readonly methodsOf: (policy: ChildPolicy) => string[];
+    /** GIR namespace -> `gi://` import. Defaults to the GTK/Adwaita pair. */
+    readonly modules?: Readonly<Record<string, string>>;
+}
+export declare class GateFailure extends Error {
+    readonly gate: string;
+    constructor(gate: string, message: string);
+}
+export interface EmitResult {
+    readonly text: string;
+    readonly count: number;
+    readonly provenance: string;
+}
+export declare function emitWidgets(input: EmitInput, floor?: number): EmitResult;

package/lib/types/generator/gir.d.mts

@@ -0,0 +1,156 @@
+/**
+ * Read the GIR XML into a plain model.
+ *
+ * WHY THE XML AND NOT THE TYPELIB. Both carry the structure — measured on gtk
+ * 4.22.4, `GIRepository` 3.0 answers class enumeration, abstractness, properties
+ * with `CONSTRUCT_ONLY`, signals, methods and property enum types, and its
+ * concrete-widget set is IDENTICAL to the XML's. What the typelib does not carry,
+ * and offers no API that could, is documentation, default values and
+ * since-versions: it strips them by design, which is why gi-docgen reads the GIR.
+ * ADR 0028 § 6 makes these surfaces a PUBLISHED artifact whose point is what a
+ * consumer's editor shows on hover, so the richer input wins.
+ *
+ * WHY @gjsify/domparser. Measured on the 6.2 MB `Gtk-4.0.gir`: 232 ms, RSS 53 MB
+ * -> 96 MB, and its `application/xml` mode is right where it has to be —
+ * selectors are case-SENSITIVE (`CLASS` matches nothing), namespaced tags work
+ * (`glib\:signal` -> 352), namespaced attributes work (`[glib\:type-name]` ->
+ * 445). No new dependency, and a tier-1 package gets dogfooded against a real
+ * 6 MB document.
+ *
+ * ONE FROZEN WART TO KNOW ABOUT: in XML mode `tagName` is LOWERCASED and
+ * `nodeName` UPPERCASED, both wrong by the XML spec and both deliberately frozen
+ * (ADR 0026 § Decision 4) because a measured consumer switches on lowercase tag
+ * literals at 24 sites. Harmless here — every GIR tag is lowercase already — but
+ * a generator for a mixed-case dialect could not use this reader as-is.
+ */
+/**
+ * A GIR type reference, with the array flag kept SEPARATE.
+ *
+ * Not a nicety: `<property name="css-classes"><array><type name="utf8"/></array>`
+ * is `string[]`, and a reader that asked for a descendant `<type>` would answer
+ * `string` — for a property authored as `cssClasses={['card']}` on every second
+ * widget. `querySelector` searches descendants, so the array case has to be
+ * checked FIRST, on own children only.
+ */
+export interface GirType {
+    /** Qualified where GIR wrote a reference (`Gtk.Orientation`), bare for a C scalar (`gboolean`). */
+    readonly name: string;
+    readonly array: boolean;
+}
+export interface GirProperty {
+    readonly name: string;
+    readonly writable: boolean;
+    readonly readable: boolean;
+    readonly constructOnly: boolean;
+    readonly type: GirType;
+    /** GIR carries it, the typelib does not — `GTK_ORIENTATION_HORIZONTAL`. */
+    readonly defaultValue?: string;
+    readonly deprecated: boolean;
+    /** GIR's `version` attribute — the release that introduced this member. */
+    readonly since?: string;
+    readonly doc?: string;
+}
+/**
+ * The GObject nick a GIR enum member would get if GIR did not say.
+ *
+ * GIR writes `baseline_fill`; the nick GObject registered is `baseline-fill`. This
+ * is the FALLBACK for a `<member>` with no `glib:nick` — the attribute itself is
+ * the answer wherever it exists, because the substitution is right for Gtk and Adw
+ * by luck and not by construction: across every GIR in this workspace 40,940
+ * members carry the attribute and 97 disagree with it.
+ */
+export declare const nickOf: (member: string) => string;
+export interface GirParam {
+    readonly name: string;
+    readonly type: GirType;
+    /** GIR's `direction`, which defaults to `in` when the attribute is absent. */
+    readonly direction: 'in' | 'out' | 'inout';
+    /**
+     * GIR's `caller-allocates`. It decides whether a non-`in` slot holds anything
+     * at all — see `renderParam` in `surface.mts`, which is the only reader.
+     */
+    readonly callerAllocates: boolean;
+}
+export interface GirSignal {
+    readonly name: string;
+    /**
+     * WITHOUT the emitting object. GIR lists a signal's `<parameters>` free of the
+     * instance (unlike a `<method>`), and the host strips the instance too —
+     * `next(...args.slice(1))` in `signals.ts`. The two line up exactly, which is
+     * why a generated handler signature can be taken from here verbatim.
+     */
+    readonly params: readonly GirParam[];
+    readonly deprecated: boolean;
+    /** GIR's `version` attribute — the release that introduced this signal. */
+    readonly since?: string;
+    readonly doc?: string;
+}
+export interface GirClass {
+    /** The GType name — `GtkBox`. Absent for a class GIR declares without one. */
+    readonly gtype: string;
+    /** GIR-local name — `Box`. */
+    readonly name: string;
+    readonly namespace: string;
+    readonly kind: 'class' | 'interface';
+    readonly abstract: boolean;
+    /** Namespace-qualified parent — `Gtk.Widget` — or null at the root. */
+    readonly parent: string | null;
+    /** Qualified interfaces (`<implements>`), or an interface's `<prerequisite>`s. */
+    readonly implements: readonly string[];
+    readonly methods: readonly string[];
+    readonly signals: readonly GirSignal[];
+    readonly properties: readonly GirProperty[];
+    readonly doc?: string;
+}
+export interface GirEnum {
+    readonly gtype: string;
+    /** Namespace-qualified — `Gtk.Orientation`. */
+    readonly qualified: string;
+    readonly flags: boolean;
+    /** The NICKS, which is what a string-accepting surface needs. */
+    readonly members: readonly string[];
+}
+export interface GirNamespace {
+    readonly name: string;
+    readonly version: string;
+    /** Classes AND interfaces, in one list: `implements` resolves against the same index. */
+    readonly classes: readonly GirClass[];
+    readonly enums: readonly GirEnum[];
+    /** Every other named type GIR declares — records, unions, callbacks, aliases. */
+    readonly otherTypes: readonly string[];
+}
+export declare function readNamespace(xml: string): GirNamespace;
+/** Every class and interface across the namespaces read, keyed the way GIR references them. */
+export declare function indexClasses(namespaces: readonly GirNamespace[]): Map<string, GirClass>;
+/**
+ * Walk to the root, or as far as the loaded namespaces reach.
+ *
+ * A chain that leaves the loaded set is not an error: `Gtk.Widget`'s own parent
+ * is `GObject.InitiallyUnowned`, and loading GObject-2.0 to learn that would buy
+ * nothing. What matters is whether `Gtk.Widget` is ON the chain.
+ */
+export declare function ancestors(cls: GirClass, index: Map<string, GirClass>): GirClass[];
+/**
+ * Every declaration a class's members can come from — self, ancestors, interfaces.
+ *
+ * The interfaces are not optional and the measurement says why: `GtkBox` declares
+ * four properties of its own and `orientation` is NOT among them. It lives on
+ * `Gtk.Orientable`, an `<implements>` of `GtkBox`, because GObject installs
+ * interface properties on the implementor at runtime while GIR keeps them once,
+ * on the interface. A class-only reader therefore emits a surface in which
+ * `<gtk-box orientation="vertical">` — the most-written GtkBox attribute there is
+ * — is a type error.
+ *
+ * Order is self, then the parent chain, then interfaces of each, so a nearer
+ * declaration of the same property name wins.
+ */
+export declare function declarations(cls: GirClass, index: Map<string, GirClass>): GirClass[];
+/**
+ * Concrete descendants of a root class — the set a renderer can actually create.
+ *
+ * The root is a PARAMETER so a fixture can exercise this with a five-class GIR of
+ * its own. Hard-coding `GtkWidget` would leave the walk, the abstract filter and
+ * the namespace-crossing parent chain testable only against the real 6.2 MB file,
+ * where an off-by-one is invisible.
+ */
+export declare function concreteWidgets(namespaces: readonly GirNamespace[], root?: string): GirClass[];

package/lib/types/generator/main.d.mts

@@ -0,0 +1,23 @@
+/**
+ * The generator CLI.
+ *
+ *   gjsify run generate -- [--gir-dir DIR]... [--out DIR]
+ *
+ * WHY THE GIR PATH IS AN ARGUMENT AND NOT A DEPENDENCY. The GIR files are not in
+ * this repository and should not be: `Gtk-4.0.gir` alone is 6.2 MB, they are
+ * distro artefacts, and four different GTK versions sit on the maintainer
+ * workstation. So the ARTEFACT is committed (ADR 0028 § Implementation) and the
+ * input is located at generation time — from `--gir-dir`, from `GJSIFY_GIR_DIR`,
+ * or from the search list below. A fresh clone builds, checks, packs and tests
+ * with no GIR present at all; only regenerating needs one.
+ *
+ * THERE IS NO `--check` MODE, and the attempt to add one is worth recording: the
+ * `generate` script pipes the output through `gjsify format`, which reflows it
+ * (+4 KB on `props.ts`), so a byte comparison against the committed file reports a
+ * difference on every run. Two of my own measurements said otherwise first, both
+ * because they compared a formatted file against itself. `git diff` after a
+ * regeneration answers the same question with no machinery, and the check that
+ * matters is machine-INDEPENDENT: `generated.spec.ts` asks the installed GTK
+ * whether every generated name is real.
+ */
+export {};

package/lib/types/generator/mini.fixture.d.mts

@@ -0,0 +1,30 @@
+/**
+ * A five-class GIR, so the generator is testable without the 6.2 MB one.
+ *
+ * Every element here earns its place by exercising a branch the real GIR cannot
+ * exercise ON DEMAND:
+ *
+ *  - `Orientable.label` is a `gint` and `Box.label` a `utf8`, so the two bases of
+ *    `MiniBoxProps` disagree and the `Omit` machinery has to fire. Measured, the
+ *    real Gtk+Adw hierarchy produces ZERO such conflicts, which left that code
+ *    shipped and unexercised — this is what turns it into a tested path.
+ *  - `baseline_fill` is a two-word enum member, so the GIR-underscore-to-nick
+ *    substitution is visible.
+ *  - `css-classes` is an ARRAY of a scalar, the case a descendant `<type>` lookup
+ *    gets wrong by answering `string` for `string[]`.
+ *  - `locked` is readable and NOT writable, so the writable filter has something to
+ *    drop.
+ *  - `MiniGLThing` has two adjacent capitals, so `tagOf`'s acronym rule and the
+ *    Volar-resolution gap both have a case.
+ *  - `Nameless` has no `glib:type-name`, and `NotAWidget` does not descend from the
+ *    root — the two reasons a class is skipped.
+ *
+ * Embedded as a string rather than a file: the test bundle runs under gjs from a
+ * path that is not the source tree, and a fixture that cannot be found is a test
+ * that silently checks nothing.
+ */
+export declare const MINI_GIR = "<?xml version=\"1.0\"?>\n<repository version=\"1.2\"\n            xmlns=\"http://www.gtk.org/introspection/core/1.0\"\n            xmlns:c=\"http://www.gtk.org/introspection/c/1.0\"\n            xmlns:glib=\"http://www.gtk.org/introspection/glib/1.0\">\n  <namespace name=\"Mini\" version=\"1.0\">\n    <enumeration name=\"Align\" glib:type-name=\"MiniAlign\">\n      <member name=\"fill\" value=\"0\"/>\n      <member name=\"baseline_fill\" value=\"1\"/>\n      <!-- A nick GIR CARRIES and the substitution would get wrong. 97 members\n           across this workspace's GIRs are shaped like this. -->\n      <member name=\"two_words\" value=\"2\" glib:nick=\"renamed\"/>\n    </enumeration>\n    <bitfield name=\"StateFlags\" glib:type-name=\"MiniStateFlags\">\n      <member name=\"active\" value=\"1\"/>\n    </bitfield>\n    <record name=\"Rect\" c:type=\"MiniRect\"/>\n    <interface name=\"Orientable\" glib:type-name=\"MiniOrientable\">\n      <doc xml:space=\"preserve\">Anything with an orientation. Second sentence, dropped.</doc>\n      <property name=\"orientation\" writable=\"1\">\n        <doc xml:space=\"preserve\">Which way round it goes.</doc>\n        <type name=\"Align\"/>\n      </property>\n      <property name=\"label\" writable=\"1\">\n        <type name=\"gint\"/>\n      </property>\n    </interface>\n    <class name=\"Widget\" glib:type-name=\"MiniWidget\" abstract=\"1\" parent=\"GObject.Object\">\n      <property name=\"visible\" writable=\"1\"><type name=\"gboolean\"/></property>\n      <property name=\"css-classes\" writable=\"1\"><array><type name=\"utf8\"/></array></property>\n      <property name=\"locked\"><type name=\"gint\"/></property>\n      <property name=\"area\" writable=\"1\"><type name=\"Rect\"/></property>\n      <glib:signal name=\"destroy\"/>\n      <method name=\"show\"/>\n    </class>\n    <class name=\"Box\" glib:type-name=\"MiniBox\" parent=\"Widget\">\n      <implements name=\"Orientable\"/>\n      <property name=\"spacing\" writable=\"1\"><type name=\"gint\"/></property>\n      <property name=\"label\" writable=\"1\"><type name=\"utf8\"/></property>\n      <property name=\"old-thing\" writable=\"1\" deprecated=\"1\"><type name=\"gboolean\"/></property>\n      <glib:signal name=\"row-activated\" version=\"1.2\">\n        <parameters>\n          <parameter name=\"row\"><type name=\"Widget\"/></parameter>\n          <parameter name=\"how\"><type name=\"Align\"/></parameter>\n        </parameters>\n      </glib:signal>\n      <method name=\"append\"/>\n      <method name=\"remove\"/>\n    </class>\n    <class name=\"GLThing\" glib:type-name=\"MiniGLThing\" parent=\"Widget\">\n      <property name=\"mode\" writable=\"1\"><type name=\"Align\"/></property>\n      <property name=\"flags\" writable=\"1\"><type name=\"StateFlags\"/></property>\n    </class>\n    <class name=\"Nameless\" parent=\"Widget\"/>\n    <class name=\"NotAWidget\" glib:type-name=\"MiniNotAWidget\" parent=\"GObject.Object\"/>\n  </namespace>\n</repository>\n";
+/** The fixture's own namespace-to-package map, which the real one has no entry for. */
+export declare const MINI_PACKAGES: {
+    readonly Mini: "@girs/mini-1.0";
+};

package/lib/types/generator/surface.d.mts

@@ -0,0 +1,62 @@
+/**
+ * Build the declaration graph the type surfaces are emitted from.
+ *
+ * ONE INTERFACE PER GIR DECLARATION, carrying its OWN members and extending its
+ * bases — not one flat interface per widget. The measurement decides it: the 164
+ * concrete widgets have 6768 writable property slots between them and only 561
+ * distinct property names. Flattening would emit the same `visible?: boolean`
+ * 164 times; mirroring GIR's own inheritance emits it once, on `GtkWidgetProps`,
+ * and the diff of a GTK update then shows what actually changed.
+ *
+ * THE CONFLICT MACHINERY IS NOT DEFENSIVE. TypeScript requires a multiply
+ * inherited member to be IDENTICAL in every base — `string` and `string | null`
+ * are not — and GTK's interfaces do redeclare class properties. So a base that
+ * loses a member is emitted as `Omit<Base, 'name'>`, because a local redeclaration
+ * does NOT repair incompatible bases (it turns one error into another).
+ */
+import { type GirClass, type GirNamespace } from './gir.mjs';
+import { type Universe } from './tsmap.mjs';
+export interface PropMember {
+    readonly kebab: string;
+    readonly camel: string;
+    readonly ts: string;
+    readonly doc?: string;
+    readonly deprecated: boolean;
+    readonly since?: string;
+}
+export interface SignalMember {
+    readonly signal: string;
+    readonly prop: string;
+    /** Already rendered — `(row: Gtk.ListBoxRow) => void`. */
+    readonly ts: string;
+    readonly doc?: string;
+    readonly deprecated: boolean;
+    readonly since?: string;
+}
+export interface Declaration {
+    /** GIR-qualified — `Gtk.Box`. The graph is keyed on this, the way GIR references. */
+    readonly key: string;
+    readonly gtype: string;
+    readonly kind: 'class' | 'interface';
+    /** `GtkBoxProps`. */
+    readonly iface: string;
+    readonly bases: readonly string[];
+    readonly props: readonly PropMember[];
+    readonly signals: readonly SignalMember[];
+    readonly doc?: string;
+}
+export interface SurfaceModel {
+    /** The 164, sorted by GType name. */
+    readonly widgets: readonly GirClass[];
+    readonly declarations: ReadonlyMap<string, Declaration>;
+    /** Widget GType -> the GTypes of every declaration its members come from, self first. */
+    readonly closure: ReadonlyMap<string, readonly string[]>;
+    /** Enum GType -> nicks, for the emitted aliases and for the runtime nick check. */
+    readonly enumNicks: ReadonlyMap<string, readonly string[]>;
+    readonly namespacesUsed: ReadonlySet<string>;
+    /** Copied from the universe, so the emitter needs no second source for it. */
+    readonly packages: Readonly<Record<string, string>>;
+    /** Base -> members it must not contribute, because a nearer declaration disagrees. */
+    readonly omissions: ReadonlyMap<string, ReadonlyMap<string, readonly string[]>>;
+}
+export declare function buildSurface(widgets: readonly GirClass[], namespaces: readonly GirNamespace[], universe: Universe): SurfaceModel;

package/lib/types/generator/tsmap.d.mts

@@ -0,0 +1,73 @@
+/**
+ * GIR type -> TypeScript type, and the two places variance decides the answer.
+ *
+ * Measured over the real Gtk-4.0 + Adw-1 GIR with the seven referenced namespaces
+ * loaded: 6768 writable property slots and 1889 signal parameters, and NOT ONE
+ * type name that fails to resolve. So there is no "unknown fallback" branch to
+ * hide behind — every type either maps or the generator fails and says which.
+ *
+ * WHERE PROPERTIES AND PARAMETERS MUST DIFFER, twice, both times because a
+ * property is an INPUT and a handler parameter is an OUTPUT:
+ *
+ *  1. An enum PROPERTY takes the nick (`orientation="vertical"`) — the host
+ *     resolves it (`coerce()` in props.ts) precisely because GObject would
+ *     silently keep the old value. An enum PARAMETER arrives as a NUMBER: GJS
+ *     hands the marshalled value. Offering the nick union in a parameter would
+ *     invite `if (mode === 'single')`, which is always false — a silent bug worse
+ *     than no typing at all.
+ *  2. Nullability widens a property harmlessly and BREAKS a parameter. GIR marks
+ *     many parameters `nullable="1"`, but a parameter type is contravariant: with
+ *     `(row: Gtk.ListBoxRow | null) => void` declared, the ordinary
+ *     `onRowActivated={(row: Gtk.ListBoxRow) => …}` stops compiling. So object
+ *     PROPERTIES get `| null` (clearing one is legitimate) and parameters do not,
+ *     and this comment is the record that the second was a decision rather than an
+ *     oversight.
+ *
+ * FLAGS ARE `number`, in both positions, and that mirrors the runtime exactly: the
+ * host REFUSES a nick string for a flags property by name (`err.badFlags`),
+ * because resolving a nick set ("horizontal|vertical") is not something GObject
+ * exposes. A union of nicks here would type-check something the host rejects.
+ */
+import type { GirClass, GirEnum, GirNamespace, GirType } from './gir.mjs';
+/** GIR namespace -> the `@girs` package that types it. Only these seven are referenced. */
+export declare const GIRS_PACKAGES: Readonly<Record<string, string>>;
+export interface Universe {
+    readonly enums: Map<string, GirEnum>;
+    readonly classes: Map<string, GirClass>;
+    readonly others: Set<string>;
+    /**
+     * GIR namespace -> the `@girs` package that types it.
+     *
+     * Carried here rather than read from the module constant, so a fixture can
+     * supply its own five-class namespace. Without it the type mapper is only ever
+     * exercised against the real GIR, where the branch that refuses an unknown
+     * namespace can never be reached.
+     */
+    readonly packages: Readonly<Record<string, string>>;
+}
+export declare function buildUniverse(namespaces: readonly GirNamespace[], packages?: Readonly<Record<string, string>>): Universe;
+export { nickOf } from './gir.mjs';
+export interface TsType {
+    readonly text: string;
+    /** GIR namespaces whose `@girs` import the emitted text needs. */
+    readonly namespaces: readonly string[];
+    /** Enum GTypes whose nick alias the emitted text references. */
+    readonly enums: readonly string[];
+}
+export declare class TypeMapError extends Error {
+}
+/** A nick union, or `never` for an enum GIR declares with no members. */
+export declare const nickUnion: (e: GirEnum) => string;
+/** The alias name a nick union is emitted under — the GType name, so it is unique. */
+export declare const nickAliasOf: (e: GirEnum) => string;
+/**
+ * Map one GIR type.
+ *
+ * `where` is not decoration: see the header — an enum in a `prop` accepts nicks
+ * and in a `param` never does, and an object in a `prop` accepts null.
+ */
+export declare function tsTypeOf(type: GirType, u: Universe, where: 'prop' | 'param'): TsType;
+/** `row-activated` -> `onRowActivated`; `notify` handled by the caller. */
+export declare const eventPropOf: (signal: string) => string;
+/** `can-focus` -> `canFocus`. The inverse of the host's `toPropertyName`. */
+export declare const camelOf: (kebab: string) => string;

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

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

package/lib/types/host.d.ts

@@ -26,9 +26,68 @@ 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;
+/**
+ * TWO facts, not one: it says it is an element, and it carries a descriptor.
+ *
+ * `kind` alone is a plain string a GObject wrapper could carry; the descriptor is
+ * what every host op actually dereferences. Checking both keeps the refusal from
+ * being either paranoid or fooled.
+ *
+ * Exported because the Vue adapter had these same two lines VERBATIM, and its own
+ * comment said so — it needs the question before `adopt`, to tell a host parent
+ * from the raw widget `<Teleport :to="el">` hands through. A predicate stated in
+ * two places is a predicate that can disagree with itself about what a node is.
+ */
+export declare function isHostElement(value: unknown): value is HostElement;
+/**
+ * Name a foreign value the way its owner would recognise it.
+ *
+ * ONE function, because there were two and each was wrong for the other's input.
+ * The host's read `constructor.$gtype`, so it could not name a DOM element — the
+ * single most likely thing to arrive from a Solid app that imported `<Dynamic>`
+ * from `solid-js/web`. The Solid adapter's read `tagName`, so it answered
+ * `a Object` for the GObject wrapper `<Teleport :to="el">` hands over. Both are
+ * asking "what did I get instead of a node", so both answers belong to one place.
+ *
+ * ORDER IS LOAD-BEARING, and it is measured rather than reasoned: under gjs
+ * 1.88.1 `({}).constructor.$gtype` EXISTS and `GObject.type_name` calls it
+ * `JSObject`. So a `$gtype`-first version names every object literal — and every
+ * DOM-ish stub, which is an object literal — `JSObject`, and the host's own
+ * documented `a plain object` fallback was unreachable for exactly the shape it
+ * names. `tagName` first, and `JSObject` treated as the absence of a GType.
+ */
+export declare function describeValue(value: unknown): string;
 /** 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;
+/**
+ * Destroy every child of `parent`, bounded.
+ *
+ * Exported because both adapters wrote their OWN `childSnapshot` to do exactly this
+ * — byte-identical to each other, and both walking `next` raw. That is the one walk
+ * the bound above exists to make unforgettable, and it is the walk where the
+ * malformed link actually appears: `insert(node, parent, node)` is a defined DOM
+ * no-op, so Solid's adjacent-swap fast path emits it against a CONTAINER's child
+ * list. Unbounded, that is a hang rather than GTK's usual exit 0.
+ *
+ * This replaces a `clearContainer` that had no callers anywhere and DETACHED rather
+ * than destroyed — the wrong half for every caller that wanted it, and a name React's
+ * own HostConfig already uses for the destroying kind.
+ */
+export declare function destroyChildren(parent: HostElement): void;
+/**
+ * Disconnect a node's handlers WITHOUT touching the tree.
+ *
+ * The narrow half of `destroy`, and it exists because a framework can tell us "this
+ * node is gone" while still holding its sibling links: Solid disposes a per-node
+ * scope BEFORE its reconciler runs, and `reconcileArrays` opens with
+ * `getNextSibling(last)`. Unlinking there made every trailing insertion append at
+ * the end of the parent instead of before the marker.
+ *
+ * The leak this closes is about handlers, not links — GJS blocks JS callbacks
+ * during GC, so an undisconnected handler outlives its widget. The framework's own
+ * `removeNode` still does the unlinking, in its own order.
+ */
+export declare function disconnectHandlers(el: HostElement): void;
 /**
  * Tear a subtree down: disconnect every handler, unparent, drop the reference.
  *
@@ -49,6 +108,48 @@ export declare function destroy(node: HostNode): void;
  * method name here would be the generic `add` that GTK4 deliberately removed.
  */
 export declare function mountRoot(el: HostElement, container: Gtk.Widget): void;
+/**
+ * The materialised widget of a host node — for a `ref`, or for a test.
+ *
+ * ONE implementation. The Solid and React adapters each carried this function,
+ * identical apart from two comment lines, and Vue carried none — so a Vue app had
+ * no supported way to reach a widget at all and its only route was
+ * `materialize()`, which is exactly the call the `destroyed` guard below exists to
+ * intercept.
+ *
+ * The flag is exact and the obvious heuristic is not: `materialize` would happily
+ * build a fresh, propertyless, unparented widget for a destroyed node — `destroy`
+ * clears `props` and `layout` precisely so one cannot look re-materialisable — and
+ * "no widget, not attached, no props" also describes a brand-new element.
+ */
+export declare function widgetOf(node: HostNode): Gtk.Widget;
+/**
+ * An off-screen container the host owns — the analogue of the DOM's detached `<div>`.
+ *
+ * `<KeepAlive>` and `<Suspense>` ask a renderer for one: `KeepAliveImpl.setup`
+ * opens with `createElement("div")` and `SuspenseImpl` does the same for its
+ * `hiddenContainer`. Forwarded as a TAG, "div" reached `lookupWidget` and threw
+ * `unknown-tag` inside `callWithErrorHandling`, whose production arm is
+ * `console.error` with no rethrow: `mount()` returned normally, the container held
+ * zero children, GTK said nothing, exit 0.
+ *
+ * The Vue adapter answered that with `adopt(new Gtk.Box())` — the one runtime
+ * `gi://` import and the one concrete widget class in any adapter, i.e. the widget
+ * knowledge ADR 0027 § 7 forbids. Which widget backs it is the table's business
+ * (`makeDetachedContainer`), and this op is what leaves the adapter with nothing to
+ * know: the deactivated subtree is really unparented from the visible tree and
+ * really held alive, so reactivating it moves the SAME widgets back.
+ */
+export declare const createDetachedContainer: () => HostElement;
+/**
+ * Wrap a widget the application owns as a host element.
+ *
+ * The seam every framework adapter needs: a renderer mounts into a container it
+ * did not create. The descriptor comes from the SAME table as every other parent,
+ * through `nearestRegistered`, so an application's own `GObject.registerClass`
+ * subclass inherits its ancestor's placement rules instead of failing.
+ */
+export declare function adopt(container: Gtk.Widget): HostElement;
 export declare const parentNode: (node: HostNode) => HostElement | null;
 export declare const firstChild: (el: HostElement) => HostNode | null;
 export declare const nextSibling: (node: HostNode) => HostNode | null;

package/lib/types/index.d.ts

@@ -1,8 +1,11 @@
 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 { adopt, createAnchor, createDetachedContainer, createElement, createText, destroyChildren, destroy, disconnectHandlers, firstChild, insert, isHostElement, isText, materialize, mountRoot, nextSibling, parentNode, prevSibling, remove, setElementText, setEventHandler, setProp, setSlot, setText, widgetOf, } 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 { constructOnlyNames, isConstructOnly, isWritable, lookupEnumNick, paramSpecs, toPropertyName, } from './props.js';
+export { assertInjective, tagOf } from './tags.js';
+export { probeEnabled, runHostProbe, runHostProbeApp, type HostProbe, type HostProbeApp, type ProbeCheck, } from './probe.js';
+export type { ElementChild, ElementChildren, JsxAttributes, RawSignalAttributes, SlotAttribute, VueAttributes, WithOnce, } from './attrs.js';
 export { clearRegistry, hasWidget, lookupWidget, nearestRegistered, registerWidget, registerWidgets, registeredTags, } from './registry.js';
-export { ADW_DESCRIPTORS, BUILTIN_DESCRIPTORS, GTK_DESCRIPTORS, registerBuiltinWidgets } from './descriptors/index.js';
+export { ADW_DESCRIPTORS, BUILTIN_DESCRIPTORS, CURATED_DESCRIPTORS, GENERATED_PROVENANCE, GENERATED_WIDGETS, GTK_DESCRIPTORS, mergeGenerated, registerBuiltinWidgets, tableProvenance, } from './descriptors/index.js';